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-модули предоставляют ограниченную или вообще не предоставляют поддержку версий; см. документацию модуля.

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

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

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

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

find_package(<PackageName> [version] [EXACT] [QUIET]
             [REQUIRED] [[COMPONENTS] [components...]]
             [OPTIONAL_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 не устанавливает никаких соглашений о значении номеров версий. Номера версий пакетов проверяются с помощью файлов «version», предоставляемых самими пакетами. Для кандидата на файл конфигурации пакета <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 или установив CMAKE_FIND_USE_PACKAGE_ROOT_PATH в значение FALSE. См. политику CMP0074.

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

   CMAKE_PREFIX_PATH
   CMAKE_FRAMEWORK_PATH
   CMAKE_APPBUNDLE_PATH
   

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

   <PackageName>_DIR
   CMAKE_PREFIX_PATH
   CMAKE_FRAMEWORK_PATH
   CMAKE_APPBUNDLE_PATH
   

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

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

   PATH
   

6. Проверка путей, сохранённых в реестре пакетов CMake Пользовательский реестр пакетов. Это можно пропустить, передав NO_CMAKE_PACKAGE_REGISTRY или установив переменную CMAKE_FIND_USE_PACKAGE_REGISTRY в FALSE или устаревшую переменную CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY в TRUE.

   Подробности о пользовательском реестре пакетов см. в руководстве cmake-packages(7).

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

   CMAKE_SYSTEM_PREFIX_PATH
   CMAKE_SYSTEM_FRAMEWORK_PATH
   CMAKE_SYSTEM_APPBUNDLE_PATH
   

8. Проверка путей, сохранённых в реестре пакетов CMake Системный реестр пакетов. Это можно пропустить, передав NO_CMAKE_SYSTEM_PACKAGE_REGISTRY или установив CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY переменную в FALSE или устаревшую переменную 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 о том, что требования к компонентам не удовлетворены.