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] и/или список компонентов не указан для рекурсивного вызова внутри модуля поиска, соответствующие аргументы автоматически передаются из внешнего вызова (включая флаг 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 описана ниже в разделе Процедура поиска в режиме Config. После обнаружения проверяется любое ограничение версии, и если оно выполняется, файл конфигурации читается и обрабатывается CMake. Так как файл предоставлен пакетом, он уже знает расположение содержимого пакета. Полный путь к файлу конфигурации хранится в переменной cmake <PackageName>_CONFIG.

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

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

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

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

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

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

Во всех случаях <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 всегда ищется.

Укажите, какие представления реестра должны быть запрошены. Эта опция имеет смысл только на платформах Windows и будет проигнорирована на других. Если не указано иное, используется представление TARGET при установке политики CMP0134 в значение NEW. Обратитесь к CMP0134 для получения значения представления по умолчанию при установке политики в OLD.

64

Запрос в 64-разрядную базу данных реестра. В 32-разрядных системах Windows всегда возвращает строку /REGISTRY-NOTFOUND.

32

Запрос в 32-разрядную базу данных реестра.

64_32

Запрос обоих представлений (64 и 32) и генерация пути для каждого.

32_64

Запрос обоих представлений (32 и 64) и генерация пути для каждого.

HOST

Запрос реестра, соответствующего архитектуре хоста: 64 в 64-разрядных системах Windows и 32 в 32-разрядных системах Windows.

TARGET

Запрос реестра, соответствующего архитектуре, указанной переменной CMAKE_SIZEOF_VOID_P. Если она не определена, используется представление HOST.

BOTH

Запрос обоих представлений (32 и 64). Порядок зависит от следующих правил: если определена переменная CMAKE_SIZEOF_VOID_P, используется следующее представление в зависимости от её значения:

• 8: 64_32
• 4: 32_64

Если переменная CMAKE_SIZEOF_VOID_P не определена, используется архитектура хоста:

• 64-разрядная: 64_32
• 32-разрядная: 32

Если указано 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 может быть отключён или сделан 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

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.

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

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