find_package

• Базовая подпись и режим модуля
• Полная подпись и режим конфигурации
• Выбор версии
• Процедура поиска
• Переменные интерфейса файла пакета

Найти внешний проект и загрузить его настройки.

Базовая подпись и режим модуля

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

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

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

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

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

Команда имеет два режима поиска пакетов: «Модуль» и «Конфигурация». Вышеуказанная подпись выбирает режим «Модуль». Если модуль не найден, команда переходит к режиму «Конфигурация», описанному ниже. Этот переход отключается, если указана опция MODULE.

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

Если опция MODULE не указана в вышеприведенной подписи, CMake сначала ищет пакет в режиме «Модуль». Затем, если пакет не найден, он снова ищет в режиме «Конфигурация». Пользователь может установить переменную CMAKE_FIND_PACKAGE_PREFER_CONFIG в значение TRUE, чтобы направить CMake сначала искать в режиме «Конфигурация», прежде чем переходить к режиму «Модуль».

Полная подпись и режим конфигурации

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

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

find_package(<PackageName> [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_PACKAGE_ROOT_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, или использование опций, не указанных в базовой подписи, все навязывают чистый режим «Конфигурация». В чистом режиме «Конфигурация» команда пропускает поиск в режиме «Модуль» и сразу переходит к поиску в режиме «Конфигурация».

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

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

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

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

Выбор версии

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

PACKAGE_FIND_NAME

<PackageName>

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

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

PACKAGE_VERSION_COMPATIBLE

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

PACKAGE_VERSION_UNSUITABLE

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

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

<PackageName>_VERSION

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

<PackageName>_VERSION_MAJOR

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

<PackageName>_VERSION_MINOR

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

<PackageName>_VERSION_PATCH

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

<PackageName>_VERSION_TWEAK

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

<PackageName>_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.

Процедура поиска

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)

В системах, поддерживающих macOS FRAMEWORK и BUNDLE, следующие каталоги проверяются на наличие фреймворков или пакетов приложений, содержащих конфигурационный файл:

<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> интерпретируется как регистронезависимая и соответствует любому из указанных имен (<PackageName> или имена, заданные NAMES).

Пути с lib/<arch> активируются, если переменная CMAKE_LIBRARY_ARCHITECTURE установлена. lib* включает одно или несколько значений lib64, lib32, libx32 или lib (проверяются в указанном порядке).

• Пути с lib64 проверяются в 64-битных платформах, если свойство FIND_LIBRARY_USE_LIB64_PATHS установлено в значение TRUE.
• Пути с lib32 проверяются в 32-битных платформах, если свойство FIND_LIBRARY_USE_LIB32_PATHS установлено в значение TRUE.
• Пути с libx32 проверяются в платформах, использующих ABI x32, если свойство FIND_LIBRARY_USE_LIBX32_PATHS установлено в значение TRUE.
• Путь lib всегда проверяется.

Если PATH_SUFFIXES указан, суффиксы добавляются к каждому (W) или (U) элементу каталога по одному.

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

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

1. Проверяются пути, указанные в переменной CMake <PackageName>_ROOT и переменной среды <PackageName>_ROOT, где <PackageName> — пакет, который нужно найти. Переменные корня пакета хранятся как стек, поэтому, если вызов происходит из модуля поиска, пути корня родительского модуля поиска также будут проверяться после путей текущего пакета. Это можно пропустить, если передано NO_PACKAGE_ROOT_PATH. См. политику CMP0074.

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

   CMAKE_PREFIX_PATH
   CMAKE_FRAMEWORK_PATH
   CMAKE_APPBUNDLE_PATH
   

3. Проверяются пути, указанные в переменных среды, специфичных для CMake. Они предназначены для задания в конфигурации оболочки пользователя и, следовательно, используют разделитель путей хоста (; в Windows и : в UNIX). Это можно пропустить, если передано NO_CMAKE_ENVIRONMENT_PATH:

   <PackageName>_DIR
   CMAKE_PREFIX_PATH
   CMAKE_FRAMEWORK_PATH
   CMAKE_APPBUNDLE_PATH
   

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

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

   PATH
   

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

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

   CMAKE_SYSTEM_PREFIX_PATH
   CMAKE_SYSTEM_FRAMEWORK_PATH
   CMAKE_SYSTEM_APPBUNDLE_PATH
   

8. Проверяются пути, сохранённые в реестре пакетов CMake системы. Это можно пропустить, если передано NO_CMAKE_SYSTEM_PACKAGE_REGISTRY или путём установки CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY в значение TRUE. См. руководство cmake-packages(7) для получения информации о реестре пакетов системы.
9. Проверяются пути, указанные опцией 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 (<PackageName> PATHS paths... NO_DEFAULT_PATH)
find_package (<PackageName>)

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

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

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

Переменные интерфейса файла пакета

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

CMAKE_FIND_PACKAGE_NAME

искомый <PackageName>

<PackageName>_FIND_REQUIRED

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

<PackageName>_FIND_QUIETLY

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

<PackageName>_FIND_VERSION

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

<PackageName>_FIND_VERSION_MAJOR

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

<PackageName>_FIND_VERSION_MINOR

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

<PackageName>_FIND_VERSION_PATCH

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

<PackageName>_FIND_VERSION_TWEAK

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

<PackageName>_FIND_VERSION_COUNT

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

<PackageName>_FIND_VERSION_EXACT

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

<PackageName>_FIND_COMPONENTS

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

<PackageName>_FIND_REQUIRED_<c>

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

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