find_package

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

Найти пакет (обычно предоставляемый внешним по отношению к проекту компонентом) и загрузить его пакетные детали. Вызовы этой команды также могут быть перехвачены поставщиками зависимостей.

Режимы поиска

Команда использует несколько режимов поиска пакетов:

Режим модуля

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

Файл Find<PackageName>.cmake обычно не предоставляется самим пакетом. Вместо этого он обычно предоставляется чем-то внешним, таким как операционная система, сама CMake или даже проект, из которого была вызвана команда find_package(). Будучи внешними, модули поиска Модулей поиска обычно являются эвристическими и могут устаревать. Обычно они ищут определённые библиотеки, файлы и другие артефакты пакета.

Режим модуля поддерживается только базовой сигнатурой команды базовой сигнатуры.

Режим конфигурации

В этом режиме CMake ищет файл <lowercasePackageName>-config.cmake или <PackageName>Config.cmake. Также будут просмотрены файлы <lowercasePackageName>-config-version.cmake или <PackageName>ConfigVersion.cmake, если были указаны детали версии (см. Выбор версии в режиме конфигурации для объяснения использования этих отдельных файлов версии).

В режиме конфигурации команде можно предоставить список имен для поиска пакетов. Места, где CMake ищет конфигурационные и файлы версии, значительно сложнее, чем в режиме модуля (см. Процедуру поиска в режиме конфигурации).

Конфигурационные и файлы версии обычно устанавливаются как часть пакета, поэтому они, как правило, более надёжны, чем модули поиска. Они обычно содержат прямые сведения о содержимом пакета, поэтому поиск или эвристические методы не требуются внутри самих файлов конфигурации или версии.

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

Режим перенаправления FetchContent

Добавлено в версии 3.24: Вызов find_package() может быть перенаправлен внутри на пакет, предоставляемый модулем FetchContent. Для вызывающего компонента поведение будет похоже на режим конфигурации, за исключением того, что логика поиска пропускается, и информация о компонентах не используется. См. FetchContent_Declare() и FetchContent_MakeAvailable() для получения более подробной информации.

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

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

Базовая сигнатура

find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
             [REQUIRED] [[COMPONENTS] [components...]]
             [OPTIONAL_COMPONENTS components...]
             [REGISTRY_VIEW  (64|32|64_32|32_64|HOST|TARGET|BOTH)]
             [GLOBAL]
             [NO_POLICY_SCOPE]
             [BYPASS_PROVIDER])

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

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

После ключевого слова COMPONENTS может быть указан пакетный список необходимых компонентов. Если любой из этих компонентов не может быть удовлетворён, пакет в целом считается не найденным. Если также присутствует опция REQUIRED, это рассматривается как фатальная ошибка, в противном случае выполнение продолжается. В качестве сокращения, если присутствует опция REQUIRED, ключевое слово COMPONENTS можно опустить, а необходимые компоненты можно указать непосредственно после REQUIRED.

Дополнительные необязательные компоненты могут быть указаны после OPTIONAL_COMPONENTS . Если эти компоненты не могут быть удовлетворены, пакет всё ещё может считаться найденным, если все необходимые компоненты удовлетворены.

Множество доступных компонентов и их значения определяются целевым пакетом. Формально, целевой пакет сам определяет, как интерпретировать предоставленную ему информацию о компонентах, но он должен соответствовать вышеизложенным ожиданиям. Для вызовов, где не указаны компоненты, нет единого ожидаемого поведения, и целевые пакеты должны чётко определять, что происходит в таких случаях. Общие варианты включают предположение, что должны быть найдены все компоненты, нет компонентов или какой-то хорошо определённый подмножество доступных компонентов.

Аргумент [version] запрашивает версию, с которой должен быть совместим найденный пакет. Существует два возможных формата:

• Единая версия в формате major[.minor[.patch[.tweak]]], где каждый компонент — числовое значение.
• Диапазон версий в формате versionMin...[<]versionMax где versionMin и versionMax имеют тот же формат и ограничения на компоненты, что и единая версия (целые числа). По умолчанию оба крайних значения включаются. Указав <, верхний предел будет исключен. Диапазоны версий поддерживаются только с CMake 3.19 и выше.

Опция EXACT запрашивает точное соответствие версии. Эта опция несовместима с указанием диапазона версий.

Если [version] и/или список компонентов не заданы для рекурсивного вызова внутри find-модуля, соответствующие аргументы автоматически передаются из внешнего вызова (включая флаг EXACT для [version]). Поддержка версий в настоящее время предоставляется только на основе пакетов (см. раздел Выбор версии ниже). Если указан диапазон версий, но пакет предназначен только для одной версии, пакет проигнорирует верхнюю границу диапазона и учтёт только версию в нижней границе диапазона.

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

Полная сигнатура

find_package(<PackageName> [version] [EXACT] [QUIET]
             [REQUIRED] [[COMPONENTS] [components...]]
             [OPTIONAL_COMPONENTS components...]
             [CONFIG|NO_MODULE]
             [GLOBAL]
             [NO_POLICY_SCOPE]
             [BYPASS_PROVIDER]
             [NAMES name1 [name2 ...]]
             [CONFIGS config1 [config2 ...]]
             [HINTS path1 [path2 ... ]]
             [PATHS path1 [path2 ... ]]
             [REGISTRY_VIEW  (64|32|64_32|32_64|HOST|TARGET|BOTH)]
             [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_INSTALL_PREFIX]
             [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
             [CMAKE_FIND_ROOT_PATH_BOTH |
              ONLY_CMAKE_FIND_ROOT_PATH |
              NO_CMAKE_FIND_ROOT_PATH])

Опция CONFIG, синонимичная опция NO_MODULE, или использование не указанных в основной сигнатуре опций, все вместе обеспечивают чистый режим Config. В чистом режиме Config команда пропускает поиск в режиме Module и сразу переходит к поиску в режиме Config.

Поиск в режиме Config пытается найти файл конфигурации, предоставляемый пакетом. В кэш сохраняется запись с именем <PackageName>_DIR, содержащая каталог с файлом. По умолчанию команда ищет пакет с именем <PackageName>. Если задана опция NAMES, вместо <PackageName> используются имена, следующие за ней. Эти имена также учитываются при определении перенаправления вызова на пакет, предоставляемый модулем FetchContent.

Команда ищет файл с именем <PackageName>Config.cmake или <lowercasePackageName>-config.cmake для каждого указанного имени. Список возможных имён файлов конфигурации может быть изменён с помощью опции CONFIGS . Процедура поиска в режиме Config описана ниже. После нахождения, проверяется соответствие ограничениям версии и, при выполнении условия, файл конфигурации считывается и обрабатывается CMake. Поскольку файл предоставляется пакетом, он уже знает расположение содержимого пакета. Полный путь к файлу конфигурации хранится в переменной cmake <PackageName>_CONFIG.

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

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

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

Процедура поиска в режиме Config

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

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

Во всех случаях <name> обрабатывается как регистронезависимое и соответствует любому из указанных имён (<PackageName> или имена, заданные NAMES).

Если хотя бы один компилируемый язык включён, могут быть просмотрены архитектурно-специфичные каталоги lib/<arch> и lib* в зависимости от целевой архитектуры компилятора, в следующем порядке:

lib/<arch>

Просматривается, если переменная CMAKE_LIBRARY_ARCHITECTURE установлена.

lib64

Просматривается на 64-битных платформах (CMAKE_SIZEOF_VOID_P равно 8) и свойство FIND_LIBRARY_USE_LIB64_PATHS установлено в TRUE.

lib32

Просматривается на 32-битных платформах (CMAKE_SIZEOF_VOID_P равно 4) и свойство 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. Поиск префиксов, уникальных для текущего <PackageName>, которые находятся. См. политику CMP0074.

   Новое в версии 3.12.

   В частности, префиксы поиска, указанные следующими переменными, в порядке:

   1. <PackageName>_ROOT Переменная CMake, где <PackageName> — имя пакета, сохраняющее регистр.

   2. <PACKAGENAME>_ROOT Переменная CMake, где <PACKAGENAME> — имя пакета в верхнем регистре. См. политику CMP0144.

      Новое в версии 3.27.

   3. <PackageName>_ROOT Переменная среды, где <PackageName> — имя пакета, сохраняющее регистр.

   4. <PACKAGENAME>_ROOT Переменная среды, где <PACKAGENAME> — имя пакета в верхнем регистре. См. политику CMP0144.

      Новое в версии 3.27.

   Переменные корневого каталога пакета хранятся в виде стека, поэтому если вызывается из модуля поиска, пути корневого каталога модуля родителя также будут проверяться после путей текущего пакета. Это можно пропустить, если передано NO_PACKAGE_ROOT_PATH или установив CMAKE_FIND_USE_PACKAGE_ROOT_PATH в FALSE.

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, определённых в файлах платформы для текущей системы. Поиск CMAKE_INSTALL_PREFIX и CMAKE_STAGING_PREFIX можно пропустить, если передано NO_CMAKE_INSTALL_PREFIX или установив CMAKE_FIND_USE_INSTALL_PREFIX в FALSE. Все эти расположения можно пропустить, если передано 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_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH, CMAKE_SYSTEM_IGNORE_PATH и CMAKE_SYSTEM_IGNORE_PREFIX_PATH также могут привести к игнорированию некоторых из вышеперечисленных расположений.

Переменная 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 отключает пакет. Это также отключает перенаправление к пакету, предоставленному FetchContent.
• Установка переменной CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> в TRUE делает пакет обязательным (REQUIRED).

Установка обоих переменных в TRUE одновременно является ошибкой.

Выбор версии режима конфигурации

Когда задается аргумент [version], режим конфигурации будет искать только версию пакета, которая заявляет о совместимости с запрошенной версией (см. спецификацию формата). Если задана опция EXACT, будет найдена только версия пакета, заявляющая о точном соответствии запрошенной версии. CMake не устанавливает никаких соглашений о значении версий. Версии пакетов проверяются файлами «version», предоставляемыми самими пакетами или FetchContent. Для файла конфигурации кандидатного пакета <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_FIND_VERSION_RANGE

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

PACKAGE_FIND_VERSION_RANGE_MIN

Указывает, должна ли нижняя граница диапазона версий включаться или исключаться. В настоящее время единственное поддерживаемое значение для этой переменной — INCLUDE.

PACKAGE_FIND_VERSION_RANGE_MAX

Указывает, должна ли верхняя граница диапазона версий включаться или исключаться. Поддерживаемые значения для этой переменной — INCLUDE и EXCLUDE.

PACKAGE_FIND_VERSION_MIN

Полная строка запрошенной версии нижней границы диапазона

PACKAGE_FIND_VERSION_MIN_MAJOR

Главная версия нижней границы диапазона, если запрошена, иначе 0

PACKAGE_FIND_VERSION_MIN_MINOR

Дополнительная версия нижней границы диапазона, если запрошена, иначе 0

PACKAGE_FIND_VERSION_MIN_PATCH

Версия исправления нижней границы диапазона, если запрошена, иначе 0

PACKAGE_FIND_VERSION_MIN_TWEAK

Версия настройки нижней границы диапазона, если запрошена, иначе 0

PACKAGE_FIND_VERSION_MIN_COUNT

Количество компонентов версии нижней границы, от 0 до 4

PACKAGE_FIND_VERSION_MAX

Полная строка запрошенной версии верхней границы диапазона

PACKAGE_FIND_VERSION_MAX_MAJOR

Главная версия верхней границы диапазона, если запрошена, иначе 0

PACKAGE_FIND_VERSION_MAX_MINOR

Дополнительная версия верхней границы диапазона, если запрошена, иначе 0

PACKAGE_FIND_VERSION_MAX_PATCH

Версия исправления верхней границы диапазона, если запрошена, иначе 0

PACKAGE_FIND_VERSION_MAX_TWEAK

Версия настройки верхней границы диапазона, если запрошена, иначе 0

PACKAGE_FIND_VERSION_MAX_COUNT

Количество компонентов версии верхней границы, от 0 до 4

Независимо от того, задана ли одна версия или диапазон версий, переменная PACKAGE_FIND_VERSION_COMPLETE будет определена и будет содержать полную запрошенную строку версии, как указано.

Файл версии проверяет, удовлетворяет ли он запрошенной версии, и устанавливает эти переменные:

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.

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

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

CMAKE_FIND_PACKAGE_NAME

Искомый <PackageName>

<PackageName>_FIND_REQUIRED

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

<PackageName>_FIND_QUIETLY

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

<PackageName>_FIND_REGISTRY_VIEW

Запрошенный вид, если был задан параметр REGISTRY_VIEW

<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> необязателен

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

<PackageName>_FIND_VERSION_RANGE

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

<PackageName>_FIND_VERSION_RANGE_MIN

Определяет, включена или исключена нижняя граница диапазона версии. В настоящее время INCLUDE — единственное поддерживаемое значение.

<PackageName>_FIND_VERSION_RANGE_MAX

Определяет, включена или исключена верхняя граница диапазона версии. Возможные значения для этой переменной — INCLUDE или EXCLUDE.

<PackageName>_FIND_VERSION_MIN

Полная строка запрошенной версии нижней границы диапазона

<PackageName>_FIND_VERSION_MIN_MAJOR

Основная версия нижней границы, если запрошена, иначе 0

<PackageName>_FIND_VERSION_MIN_MINOR

Дополнительная версия нижней границы, если запрошена, иначе 0

<PackageName>_FIND_VERSION_MIN_PATCH

Версия исправления нижней границы, если запрошена, иначе 0

<PackageName>_FIND_VERSION_MIN_TWEAK

Версия доработки нижней границы, если запрошена, иначе 0

<PackageName>_FIND_VERSION_MIN_COUNT

Количество компонентов версии нижней границы, от 0 до 4

<PackageName>_FIND_VERSION_MAX

Полная строка запрошенной версии верхней границы диапазона

<PackageName>_FIND_VERSION_MAX_MAJOR

Основная версия верхней границы, если запрошена, иначе 0

<PackageName>_FIND_VERSION_MAX_MINOR

Дополнительная версия верхней границы, если запрошена, иначе 0

<PackageName>_FIND_VERSION_MAX_PATCH

Версия исправления верхней границы, если запрошена, иначе 0

<PackageName>_FIND_VERSION_MAX_TWEAK

Версия доработки верхней границы, если запрошена, иначе 0

<PackageName>_FIND_VERSION_MAX_COUNT

Количество компонентов версии верхней границы, от 0 до 4

Независимо от того, указана ли одиночная версия или диапазон версий, переменная <PackageName>_FIND_VERSION_COMPLETE будет определена и будет содержать полную строку запрошенной версии, как указано.

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