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

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

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

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

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

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

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

Во всех случаях <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. Новое в версии 3.12: Пути поиска, указанные в переменной CMake <PackageName>_ROOT и переменной окружения <PackageName>_ROOT, где <PackageName> - пакет для поиска (первый аргумент find_package, сохраняющий регистр). Переменные корневого каталога пакета поддерживаются как стек, поэтому при вызове из модуля поиска будут также просматриваться корневые пути родительского модуля поиска после путей текущего пакета. Это можно пропустить, если передано 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, определённых в файлах платформы для текущей системы. Поиск 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 одновременно является ошибкой.

Выбор версии в режиме Config

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