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

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

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