find_package

Загрузка настроек внешнего проекта.

find_package(<package> [version] [EXACT] [QUIET] [MODULE]
             [REQUIRED] [[COMPONENTS] [components...]]
             [OPTIONAL_COMPONENTS components...]
             [NO_POLICY_SCOPE])

Находит и загружает настройки из внешнего проекта. <package>_FOUND будет установлено, чтобы указать, был ли пакет найден. Когда пакет найден, информация, специфичная для пакета, предоставляется через переменные и Импортированные цели, документированные самим пакетом. Опция QUIET отключает сообщения, если пакет не найден. Опция MODULE отключает вторую подпись, документированную ниже. Опция REQUIRED останавливает обработку с сообщением об ошибке, если пакет не найден.

Указанный пакетом список необходимых компонентов может быть перечислен после опции COMPONENTS (или после опции REQUIRED, если она присутствует). Дополнительные необязательные компоненты могут быть перечислены после OPTIONAL_COMPONENTS. Доступные компоненты и их влияние на то, считается ли пакет найденным, определяются целевым пакетом.

Аргумент [version] запрашивает версию, с которой должен быть совместим найденный пакет (формат major[.minor[.patch[.tweak]]]). Опция EXACT запрашивает точное соответствие версии. Если при рекурсивном вызове внутри модуля поиска не указан [version] и/или список компонентов, соответствующие аргументы автоматически передаются из внешнего вызова (включая флаг EXACT для [version]). Поддержка версий в настоящее время предоставляется только на основе каждого пакета (подробности ниже).

Код пользователя обычно должен искать пакеты, используя вышеупомянутую простую подпись. Остальная часть документации по команде указывает полную подпись команды и детали процесса поиска. Разработчикам проектов, желающим предоставить пакет для поиска с помощью этой команды, рекомендуется продолжить чтение.

Команда имеет два режима поиска пакетов: режим «Модуль» и режим «Конфигурация». Режим «Модуль» доступен, когда команда вызывается с приведенной выше сокращенной подписью. CMake ищет файл под названием Find<package>.cmake в CMAKE_MODULE_PATH, а затем в установке CMake. Если файл найден, он читается и обрабатывается CMake. Он отвечает за поиск пакета, проверку версии и вывод необходимых сообщений. Многие модули поиска предоставляют ограниченную или никакую поддержку версий; см. документацию модуля. Если модуль не найден и опция MODULE не указана, команда переходит в режим «Конфигурация».

Полная подпись команды в режиме «Конфигурация»:

find_package(<package> [version] [EXACT] [QUIET]
             [REQUIRED] [[COMPONENTS] [components...]]
             [CONFIG|NO_MODULE]
             [NO_POLICY_SCOPE]
             [NAMES name1 [name2 ...]]
             [CONFIGS config1 [config2 ...]]
             [HINTS path1 [path2 ... ]]
             [PATHS path1 [path2 ... ]]
             [PATH_SUFFIXES suffix1 [suffix2 ...]]
             [NO_DEFAULT_PATH]
             [NO_CMAKE_ENVIRONMENT_PATH]
             [NO_CMAKE_PATH]
             [NO_SYSTEM_ENVIRONMENT_PATH]
             [NO_CMAKE_PACKAGE_REGISTRY]
             [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
             [NO_CMAKE_SYSTEM_PATH]
             [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
             [CMAKE_FIND_ROOT_PATH_BOTH |
              ONLY_CMAKE_FIND_ROOT_PATH |
              NO_CMAKE_FIND_ROOT_PATH])

Опция CONFIG может быть использована для явного пропуска режима «Модуль» и перехода в режим «Конфигурация». Она является синонимом использования NO_MODULE. Режим «Конфигурация» также подразумевается при использовании опций, не указанных в сокращенной подписи.

Режим «Конфигурация» пытается найти файл конфигурации, предоставленный искомым пакетом. В кэш-запись под названием <package>_DIR сохраняется каталог, содержащий файл. По умолчанию команда ищет пакет с именем <package>. Если опция NAMES указана, вместо <package> используются имена, следующие за ней. Команда ищет файл под названием <name>Config.cmake или <lower-case-name>-config.cmake для каждого указанного имени. Заменяющий набор возможных имён файлов конфигурации может быть задан с помощью опции CONFIGS . Процедура поиска описана ниже. После нахождения файл конфигурации читается и обрабатывается CMake. Поскольку файл предоставлен пакетом, он уже знает расположение содержимого пакета. Полный путь к файлу конфигурации сохраняется в переменной cmake <package>_CONFIG.

Все файлы конфигурации, которые были рассмотрены CMake при поиске установки пакета с соответствующей версией, хранятся в переменной cmake <package>_CONSIDERED_CONFIGS, а связанные версии - в <package>_CONSIDERED_VERSIONS.

Если файл конфигурации пакета не найден, CMake сгенерирует ошибку, описывающую проблему, если не указан аргумент QUIET. Если REQUIRED указан и пакет не найден, генерируется фатальная ошибка, и процесс конфигурирования останавливается. Если <package>_DIR был установлен в каталог, не содержащий файл конфигурации, CMake проигнорирует его и начнет поиск заново.

Когда аргумент [version] задан, режим «Конфигурация» найдёт только версию пакета, которая заявляет о совместимости с запрошенной версией (формат major[.minor[.patch[.tweak]]]). Если задана опция EXACT, может быть найдена только версия пакета, заявляющая о точном соответствии запрошенной версии. CMake не устанавливает никаких соглашений для значения номеров версий. Номера версий пакетов проверяются файлами «version», предоставляемыми самими пакетами. Для кандидата файла конфигурации пакета <config-file>.cmake соответствующий файл версии расположен рядом с ним и называется либо <config-file>-version.cmake либо <config-file>Version.cmake . Если такой файл версии недоступен, считается, что файл конфигурации не совместим ни с какой запрошенной версией. Базовый файл версии, содержащий код для сопоставления версий, можно создать с помощью модуля CMakePackageConfigHelpers.

Когда файл версии найден, он загружается для проверки запрошенного номера версии. Файл версии загружается в вложенном пространстве имен, в котором определены следующие переменные:

PACKAGE_FIND_NAME

имя <package>

PACKAGE_FIND_VERSION

полная строка запрошенной версии

PACKAGE_FIND_VERSION_MAJOR

главная версия, если запрошена, иначе 0

PACKAGE_FIND_VERSION_MINOR

вторая версия, если запрошена, иначе 0

PACKAGE_FIND_VERSION_PATCH

третья версия, если запрошена, иначе 0

PACKAGE_FIND_VERSION_TWEAK

дополнительная версия, если запрошена, иначе 0

PACKAGE_FIND_VERSION_COUNT

количество компонентов версии, от 0 до 4

Файл версии проверяет, удовлетворяет ли он запрошенной версии и устанавливает эти переменные:

PACKAGE_VERSION

полная предоставленная строка версии

PACKAGE_VERSION_EXACT

истина, если версия является точным совпадением

PACKAGE_VERSION_COMPATIBLE

истина, если версия совместима

PACKAGE_VERSION_UNSUITABLE

истина, если не подходит как любая версия

Эти переменные проверяются командой find_package для определения того, предоставляет ли файл конфигурации приемлемую версию. Они недоступны после возвращения вызова find_package. Если версия приемлема, устанавливаются следующие переменные:

<package>_VERSION

полная предоставленная строка версии

<package>_VERSION_MAJOR

главная версия, если предоставлена, иначе 0

<package>_VERSION_MINOR

вторая версия, если предоставлена, иначе 0

<package>_VERSION_PATCH

третья версия, если предоставлена, иначе 0

<package>_VERSION_TWEAK

дополнительная версия, если предоставлена, иначе 0

<package>_VERSION_COUNT

количество компонентов версии, от 0 до 4

и соответствующий файл конфигурации пакета загружается. При наличии нескольких файлов конфигурации пакетов, файлы версий которых заявляют о совместимости с запрошенной версией, не определено, какой из них будет выбран. Не предпринимается попыток выбрать номер версии наивысшего или ближайшего значения.

Режим «Конфигурация» предоставляет сложный интерфейс и процедуру поиска. Большая часть интерфейса предоставлена для полноты и для внутреннего использования модулями поиска, загружаемыми в режиме «Модуль». Большинству кодов пользователей достаточно просто вызвать:

find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])

чтобы найти пакет. Разработчикам пакетов CMake, предоставляющим файлы конфигурации пакета, рекомендуется называть и устанавливать их таким образом, чтобы описанная ниже процедура находила их без необходимости дополнительных опций.

CMake создаёт набор возможных префиксов установки для пакета. Под каждым префиксом ищутся несколько каталогов для файла конфигурации. Таблицы ниже показывают искомые каталоги. Каждая запись предназначена для деревьев установки, следующих соглашениям Windows (W), UNIX (U) или Apple (A):

<prefix>/                                               (W)
<prefix>/(cmake|CMake)/                                 (W)
<prefix>/<name>*/                                       (W)
<prefix>/<name>*/(cmake|CMake)/                         (W)
<prefix>/(lib/<arch>|lib|share)/cmake/<name>*/          (U)
<prefix>/(lib/<arch>|lib|share)/<name>*/                (U)
<prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/  (U)

В системах, поддерживающих OS X Frameworks и Application Bundles, ищутся следующие каталоги для фреймворков или пакетов приложений, содержащих файл конфигурации:

<prefix>/<name>.framework/Resources/                    (A)
<prefix>/<name>.framework/Resources/CMake/              (A)
<prefix>/<name>.framework/Versions/*/Resources/         (A)
<prefix>/<name>.framework/Versions/*/Resources/CMake/   (A)
<prefix>/<name>.app/Contents/Resources/                 (A)
<prefix>/<name>.app/Contents/Resources/CMake/           (A)

Во всех случаях <name> обрабатывается как регистронезависимое и соответствует любому из указанных имён (<package> или имена, заданные NAMES). Пути с lib/<arch> активируются, если переменная CMAKE_LIBRARY_ARCHITECTURE установлена. Если PATH_SUFFIXES указан, суффиксы добавляются к каждой записи каталога (W) или (U) поочерёдно.

Этот набор каталогов предназначен для работы с проектами, которые предоставляют файлы конфигурации в своих деревьях установки. Каталоги, помеченные (W), предназначены для установок на Windows, где префикс может указывать на верхнюю часть каталога установки приложения. Те, что помечены (U), предназначены для установок на платформах UNIX, где префикс используется для нескольких пакетов. Это всего лишь соглашение, поэтому все каталоги (W) и (U) по-прежнему проверяются на всех платформах. Каталоги, помеченные (A), предназначены для установок на платформах Apple. Переменные CMAKE_FIND_FRAMEWORK и CMAKE_FIND_APPBUNDLE определяют порядок предпочтения.

Набор префиксов установки создается с помощью следующих шагов. Если NO_DEFAULT_PATH указан, все опции NO_* активируются.

1. Пути поиска, указанные в переменных кэша CMake. Они предназначены для использования в командной строке с -DVAR=value. Это можно пропустить, если передать NO_CMAKE_PATH.

   CMAKE_PREFIX_PATH
   CMAKE_FRAMEWORK_PATH
   CMAKE_APPBUNDLE_PATH
   

2. Пути поиска, указанные в переменных среды CMake. Они предназначены для настройки в конфигурации оболочки пользователя. Это можно пропустить, если передать NO_CMAKE_ENVIRONMENT_PATH.

   <package>_DIR
   CMAKE_PREFIX_PATH
   CMAKE_FRAMEWORK_PATH
   CMAKE_APPBUNDLE_PATH
   

3. Пути поиска, указанные параметром HINTS. Эти пути должны быть вычислены путем анализа системы, например, подсказкой из местоположения другого уже найденного элемента. Жестко заданные предположения должны быть указаны с помощью параметра PATHS.

4. Поиск в стандартных переменных среды системы. Это можно пропустить, если передать NO_SYSTEM_ENVIRONMENT_PATH. Пути, заканчивающиеся на /bin или /sbin, автоматически преобразуются в родительские каталоги:

   PATH
   

5. Поиск путей, хранящихся в реестре пакетов CMake Пользовательский реестр пакетов. Это можно пропустить, если передать NO_CMAKE_PACKAGE_REGISTRY или установив CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY в TRUE. См. руководство cmake-packages(7) для получения подробной информации о пользовательском реестре пакетов.

6. Поиск переменных CMake, определённых в файлах платформы для текущей системы. Это можно пропустить, если передать NO_CMAKE_SYSTEM_PATH.

   CMAKE_SYSTEM_PREFIX_PATH
   CMAKE_SYSTEM_FRAMEWORK_PATH
   CMAKE_SYSTEM_APPBUNDLE_PATH
   

7. Поиск путей, хранящихся в реестре пакетов CMake Реестр системных пакетов. Это можно пропустить, если передать NO_CMAKE_SYSTEM_PACKAGE_REGISTRY или установив CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY в TRUE. См. руководство cmake-packages(7) для получения подробной информации о системном реестре пакетов.
8. Поиск путей, заданных параметром PATHS. Обычно это жестко заданные предположения.

Переменная CMake CMAKE_FIND_ROOT_PATH определяет один или несколько каталогов, которые будут добавлены в начало всех других каталогов поиска. Это фактически «перезадает корень» всего поиска в указанных местах. Пути, являющиеся потомками CMAKE_STAGING_PREFIX, исключаются из этого перезадания корня, поскольку эта переменная всегда является путём на хост-системе. По умолчанию CMAKE_FIND_ROOT_PATH пуста.

Переменная CMAKE_SYSROOT также может быть использована для указания ровно одного каталога, используемого в качестве префикса. Установка CMAKE_SYSROOT также имеет и другие эффекты. Для получения более подробной информации см. документацию по этой переменной.

Эти переменные особенно полезны при кросс-компиляции, чтобы указать корневой каталог целевой среды, и CMake также будет искать там. По умолчанию сначала ищутся каталоги, перечисленные в CMAKE_FIND_ROOT_PATH, затем каталог CMAKE_SYSROOT, а затем каталоги без перезадания корня.

По умолчанию порядок поиска разработан для наибольшей специфичности к наименьшей для общих случаев использования. Проекты могут переопределить порядок, просто вызывая команду несколько раз и используя параметры NO_*.

find_package (<package> PATHS paths... NO_DEFAULT_PATH)
find_package (<package>)

Как только один из вызовов окажется успешным, переменная результата будет установлена и сохранена в кэше, так что ни один вызов больше не будет искать.

Каждый вызов find_package, который не является обязательным, может быть отключён, установив переменную CMAKE_DISABLE_FIND_PACKAGE_<PackageName> в значение TRUE.

При загрузке файла конфигурации модуля или пакета find_package определяет переменные, чтобы предоставить информацию о параметрах вызова (и восстанавливает их исходное состояние перед возвратом):

CMAKE_FIND_PACKAGE_NAME

имя <package>, которое ищется

<package>_FIND_REQUIRED

истинно, если был задан параметр REQUIRED

<package>_FIND_QUIETLY

истинно, если был задан параметр QUIET

<package>_FIND_VERSION

полная запрошенная строка версии

<package>_FIND_VERSION_MAJOR

главный номер версии, если запрошен, иначе 0

<package>_FIND_VERSION_MINOR

второй номер версии, если запрошен, иначе 0

<package>_FIND_VERSION_PATCH

дополнительный номер версии, если запрошен, иначе 0

<package>_FIND_VERSION_TWEAK

дополнительный номер версии, если запрошен, иначе 0

<package>_FIND_VERSION_COUNT

количество компонентов версии, от 0 до 4

<package>_FIND_VERSION_EXACT

истинно, если был задан параметр EXACT

<package>_FIND_COMPONENTS

список запрошенных компонентов

<package>_FIND_REQUIRED_<c>

истинно, если компонент <c> необходим, ложно, если компонент <c> необязателен

В режиме модуля загруженный модуль поиска отвечает за выполнение запроса, подробности которого указаны в этих переменных; см. модуль поиска для получения подробностей. В режиме конфигурации find_package автоматически обрабатывает параметры REQUIRED, QUIET, и [version], но оставляет обработку компонентов на файле конфигурации пакета, чтобы он понимал, что это имеет смысл для пакета. Файл конфигурации пакета может установить <package>_FOUND в ложь, чтобы сообщить find_package, что требования к компоненту не выполнены.

См. документацию по команде cmake_policy() для обсуждения параметра NO_POLICY_SCOPE.