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 задан, и пакет не найден, генерируется ошибка, и шаг конфигурации прекращает выполнение. Если <PackageName>_DIR задан в каталог, не содержащий файл конфигурации, CMake проигнорирует его и начнёт поиск заново.

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

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

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

1

Новая в версии 3.25.

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