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...]]
             [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 не устанавливает никаких соглашений о значении версий. Версии пакетов проверяются файлами «версии», предоставляемыми самими пакетами. Для кандидата файла конфигурации пакета <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

   Пути платформы, содержащиеся в этих переменных, представляют собой расположения, которые обычно включают установленное программное обеспечение. Примером является /usr/local для платформ на базе UNIX.

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>)

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

По умолчанию значение, хранящееся в переменной result, будет путем, в котором найден файл. Переменная 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 о том, что требования к компонентам не удовлетворены.