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 запрашивает, чтобы версия точно совпадала. Если при рекурсивном вызове внутри find-модуля не указана [version] и/или список компонентов, соответствующие аргументы автоматически передаются из внешнего вызова (включая флаг EXACT для [version]). Поддержка версий в настоящее время предоставляется только на основе пакета (подробности ниже).

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

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

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

Для управления порядком, в котором find_package проверяет совместимость, используйте две переменные CMAKE_FIND_PACKAGE_SORT_ORDER и CMAKE_FIND_PACKAGE_SORT_DIRECTION. Например, чтобы выбрать наивысшую версию, можно установить:

SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)

перед вызовом find_package.

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

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)
<prefix>/<name>*/(lib/<arch>|lib|share)/cmake/<name>*/          (W/U)
<prefix>/<name>*/(lib/<arch>|lib|share)/<name>*/                (W/U)
<prefix>/<name>*/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/  (W/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. Они предназначены для задания в конфигурации оболочки пользователя и поэтому используют системный разделитель путей хоста (; в Windows и : в UNIX). Это можно пропустить, если передано 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. Поиск путей, определенных в файлах платформы для текущей системы. Это можно пропустить, если передано 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, а затем каталоги без корневого каталога. Поведение по умолчанию можно настроить, установив CMAKE_FIND_ROOT_PATH_MODE_PACKAGE.

Это поведение можно переопределить на основе вызова с помощью опций:

CMAKE_FIND_ROOT_PATH_BOTH

Искать в порядке, описанном выше.

NO_CMAKE_FIND_ROOT_PATH

Не использовать переменную CMAKE_FIND_ROOT_PATH.

ONLY_CMAKE_FIND_ROOT_PATH

Искать только в переопределенных каталогах и каталогах ниже CMAKE_STAGING_PREFIX.

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

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

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

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

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

CMAKE_FIND_PACKAGE_NAME

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

<package>_FIND_REQUIRED

true, если была указана опция REQUIRED

<package>_FIND_QUIETLY

true, если была указана опция 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

true, если была указана опция EXACT

<package>_FIND_COMPONENTS

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

<package>_FIND_REQUIRED_<c>

true, если компонент <c> обязателен, false, если компонент <c> необязателен

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

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