Spec-Zone.ru › CMake 3.23

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

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

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

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

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

Базовая подпись

find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
             [REQUIRED] [[COMPONENTS] [components...]]
             [OPTIONAL_COMPONENTS components...]
             [NO_POLICY_SCOPE])

Базовая подпись поддерживается как в режиме модуля, так и в режиме конфигурации. Ключевое слово 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]
             [NO_POLICY_SCOPE]
             [NAMES name1 [name2 ...]]
             [CONFIGS config1 [config2 ...]]
             [HINTS path1 [path2 ... ]]
             [PATHS path1 [path2 ... ]]
             [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_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> будут использованы указанные имена. Команда ищет файл <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, предоставляющие файлы конфигурации пакета, должны называть и устанавливать их таким образом, чтобы процедура поиска в режиме конфигурации, описанная ниже, находила их без необходимости дополнительных опций.

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

Примечание

При использовании режима Config этот порядок поиска применяется независимо от того, указана ли полная или базовая подпись.

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

<prefix>/                                                       (W)
<prefix>/(cmake|CMake)/                                         (W)
<prefix>/<name>*/                                               (W)
<prefix>/<name>*/(cmake|CMake)/                                 (W)
<prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/                 (U)
<prefix>/(lib/<arch>|lib*|share)/<name>*/                       (U)
<prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/         (U)
<prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/         (W/U)
<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/               (W/U)
<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U)

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

<prefix>/<name>.framework/Resources/                    (A)
<prefix>/<name>.framework/Resources/CMake/              (A)
<prefix>/<name>.framework/Versions/*/Resources/         (A)
<prefix>/<name>.framework/Versions/*/Resources/CMake/   (A)
<prefix>/<name>.app/Contents/Resources/                 (A)
<prefix>/<name>.app/Contents/Resources/CMake/           (A)

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

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

Добавлен в версии 3.16: Добавлены переменные CMAKE_FIND_USE_<CATEGORY> для глобального отключения различных мест поиска.

Переменная 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 вызов может быть отключён или сделан обязательным:

  • Установка переменной CMAKE_DISABLE_FIND_PACKAGE_<PackageName> в значение TRUE отключает пакет.
  • Установка переменной CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> в значение TRUE делает пакет обязательным.

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

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

Примечание

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

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

© 2000–2022 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.23/command/find_package.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API