find_package

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

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

Типичное использование

Большинство вызовов find_package() обычно имеют следующий вид:

find_package(<PackageName> [<version>] [REQUIRED] [COMPONENTS <components>...])

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

Вышеприведённая форма — сокращённый вариант базовой подписи. По возможности проекты должны искать пакеты в этой форме. Это уменьшает сложность и максимизирует способы поиска или предоставления пакета.

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

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

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

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

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

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

Процедура поиска в режиме конфигурации

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

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

Во всех случаях <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 может быть отключён или сделан 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 в ложь, чтобы сообщить find_package о том, что требования к компонентам не удовлетворены.