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

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

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

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

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

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

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

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

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

PACKAGE_VERSION_COMPATIBLE

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

PACKAGE_VERSION_UNSUITABLE

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

Эти переменные проверяются командой 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 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> рассматривается как нечувствительная к регистру и соответствует любому из указанных имён (<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 пользователя (User Package Registry). Это можно пропустить, если передано NO_CMAKE_PACKAGE_REGISTRY или установив CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY в TRUE. См. руководство cmake-packages(7) для получения подробной информации о реестре пакетов пользователя.

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

   CMAKE_SYSTEM_PREFIX_PATH
   CMAKE_SYSTEM_FRAMEWORK_PATH
   CMAKE_SYSTEM_APPBUNDLE_PATH
   

8. Поиск путей, сохранённых в системе реестра пакетов CMake (System Package Registry). Это можно пропустить, если передано 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

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

<PackageName>_FIND_QUIETLY

истина, если был задан параметр 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

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

<PackageName>_FIND_COMPONENTS

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

<PackageName>_FIND_REQUIRED_<c>

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

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