find_package

Загрузка настроек внешнего проекта.

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

Находит и загружает настройки из внешнего проекта. <package>_FOUND будет установлено, чтобы указать, был ли пакет найден. Когда пакет найден, информация, специфичная для пакета, предоставляется через переменные и Импортированные цели, документированные самим пакетом. Опция QUIET отключает сообщения, если пакет не найден. Опция MODULE отключает вторую подпись, документированную ниже. Опция REQUIRED останавливает обработку с сообщением об ошибке, если пакет не найден.

Указанный пакетом список необходимых компонентов может быть перечислен после опции COMPONENTS (или после опции REQUIRED , если она присутствует). Дополнительные необязательные компоненты могут быть перечислены после OPTIONAL_COMPONENTS. Доступные компоненты и их влияние на то, считается ли пакет найденным, определяются целевым пакетом.

Аргумент [version] запрашивает версию, с которой должна быть совместима найденная версия пакета (формат major[.minor[.patch[.tweak]]]). Опция EXACT запрашивает точное совпадение версии. Если ни [version] , ни список компонентов не заданы для рекурсивного вызова внутри модуля поиска, соответствующие аргументы автоматически передаются из внешнего вызова (включая флаг EXACT для [version]). Поддержка версий в настоящее время предоставляется только на основе пакета (подробнее ниже).

Код пользователя, как правило, должен искать пакеты, используя вышеупомянутую простую подпись. Остальная часть документации по команде описывает полную подпись команды и детали процесса поиска. Разработчикам проектов, желающим предоставить пакет, который должен быть найден с помощью этой команды, рекомендуется продолжить чтение.

Команда имеет два режима поиска пакетов: режим «Модуль» и режим «Конфигурация». Режим «Модуль» доступен, когда команда вызывается с приведенной выше сокращенной подписью. CMake ищет файл под названием Find<package>.cmake в CMAKE_MODULE_PATH, а затем в установке CMake. Если файл найден, он считывается и обрабатывается CMake. Он отвечает за поиск пакета, проверку версии и вывод необходимых сообщений. Многие модули поиска предоставляют ограниченную или никакую поддержку версионирования; обратитесь к документации модуля. Если модуль не найден и не задана опция MODULE, команда переходит в режим «Конфигурация».

Полная подпись команды в режиме «Конфигурация»:

find_package(<package> [version] [EXACT] [QUIET]
             [REQUIRED] [[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. Режим «Конфигурация» также подразумевается при использовании опций, не указанных в сокращенной подписи.

Режим «Конфигурация» пытается найти файл конфигурации, предоставляемый искомым пакетом. В кэш-запись под названием <package>_DIR записывается каталог, содержащий файл. По умолчанию команда ищет пакет с именем <package>. Если задана опция NAMES , вместо <package> используются имена, следующие за ней. Команда ищет файл под названием <name>Config.cmake или <lower-case-name>-config.cmake для каждого указанного имени. Замена возможных имен файлов конфигурации может быть задана с помощью опции CONFIGS. Процедура поиска указана ниже. После того, как файл найден, он считывается и обрабатывается CMake. Поскольку файл предоставляется пакетом, он уже знает расположение содержимого пакета. Полный путь к файлу конфигурации хранится в переменной cmake <package>_CONFIG.

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

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

Когда аргумент [version] задан, режим «Конфигурация» будет находить только версию пакета, которая заявляет о совместимости с запрошенной версией (формат major[.minor[.patch[.tweak]]]). Если задана опция EXACT , может быть найдена только версия пакета, утверждающая точное совпадение с запрошенной версией. CMake не устанавливает никакой соглашения о значении версий. Номера версий пакетов проверяются файлами «version», предоставляемыми самими пакетами. Для кандидата в файл конфигурации пакета <config-file>.cmake соответствующий файл версии находится рядом с ним и называется либо <config-file>-version.cmake , либо <config-file>Version.cmake . Если такой файл версии недоступен, файл конфигурации считается несовместимым с запрошенной версией. Базовый файл версии, содержащий код для общего сопоставления версий, можно создать с помощью модуля CMakePackageConfigHelpers.

Когда файл версии найден, он загружается для проверки запрошенного номера версии. Файл версии загружается вложенном области, в которой определены следующие переменные:

PACKAGE_FIND_NAME

имя <package>

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_VERSION

полная строка предоставленной версии

PACKAGE_VERSION_EXACT

true, если версия является точным совпадением

PACKAGE_VERSION_COMPATIBLE

true, если версия совместима

PACKAGE_VERSION_UNSUITABLE

true, если не подходит как любая версия

Эти переменные проверяются командой find_package , чтобы определить, предоставляет ли файл конфигурации приемлемую версию. Они недоступны после возвращения вызова find_package. Если версия приемлема, устанавливаются следующие переменные:

<package>_VERSION

полная строка предоставленной версии

<package>_VERSION_MAJOR

главная версия, если предоставлена, иначе 0

<package>_VERSION_MINOR

второстепенная версия, если предоставлена, иначе 0

<package>_VERSION_PATCH

исправленная версия, если предоставлена, иначе 0

<package>_VERSION_TWEAK

дополнительная версия, если предоставлена, иначе 0

<package>_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(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])

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

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)

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

<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> обрабатывается как регистронезависимый и соответствует любому из указанных имен (<package> или именам, заданным с помощью 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 ищутся в платформах с x32 ABI, если свойство 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. Поиск путей, указанных в переменной CMake <PackageName>_ROOT и переменной среды <PackageName>_ROOT, где <PackageName> — искомый пакет. Переменные корневого пути пакета поддерживаются в виде стека, поэтому, если вызов происходит изнутри модуля поиска, пути корня родительского модуля поиска также будут проверены после путей текущего пакета. Это можно пропустить, если передать NO_PACKAGE_ROOT_PATH. См. политику CMP0074.

2. Поиск путей, указанных в переменных кэша, специфичных для CMake. Они предназначены для использования в командной строке с -DVAR=value. Значения интерпретируются как ;-списки. Это можно пропустить, если передать NO_CMAKE_PATH:

   CMAKE_PREFIX_PATH
   CMAKE_FRAMEWORK_PATH
   CMAKE_APPBUNDLE_PATH
   

3. Поиск путей, указанных в переменных среды, специфичных для CMake. Они предназначены для установки в конфигурации оболочки пользователя, поэтому используют родной разделитель путей хоста (; в Windows и : в UNIX). Это можно пропустить, если передать NO_CMAKE_ENVIRONMENT_PATH:

   <package>_DIR
   CMAKE_PREFIX_PATH
   CMAKE_FRAMEWORK_PATH
   CMAKE_APPBUNDLE_PATH
   

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

5. Поиск в стандартных переменных среды. Это можно пропустить, если передать NO_SYSTEM_ENVIRONMENT_PATH. Элементы пути, оканчивающиеся на /bin или /sbin, автоматически преобразуются в свои родительские каталоги:

   PATH
   

6. Поиск путей, сохранённых в реестре пакетов CMake Пользовательский реестр пакетов. Это можно пропустить, если передать NO_CMAKE_PACKAGE_REGISTRY или установив CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY в TRUE. См. руководство cmake-packages(7) для получения подробной информации о пользовательском реестре пакетов.

7. Поиск путей, определённых в файлах платформы для текущей системы. Это можно пропустить, если передать NO_CMAKE_SYSTEM_PATH:

   CMAKE_SYSTEM_PREFIX_PATH
   CMAKE_SYSTEM_FRAMEWORK_PATH
   CMAKE_SYSTEM_APPBUNDLE_PATH
   

8. Поиск путей, хранящихся в реестре пакетов CMake Системный реестр пакетов. Это можно пропустить, если передать NO_CMAKE_SYSTEM_PACKAGE_REGISTRY или установив CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY в TRUE. См. руководство cmake-packages(7) для получения подробной информации о системном реестре пакетов.
9. Поиск путей, указанных в опции PATHS. Обычно это жёстко заданные предположения.

Переменная 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 (<package> PATHS paths... NO_DEFAULT_PATH)
find_package (<package>)

Как только один из вызовов завершится успешно, переменная результата будет установлена и сохранена в кэше, так что ни один вызов не будет производить поиск ещё раз.

Каждый вызов find_package, не являющийся REQUIRED, может быть отключён, установив переменную CMAKE_DISABLE_FIND_PACKAGE_<PackageName> в TRUE.

При загрузке модуля поиска или файла конфигурации пакета find_package определяет переменные, чтобы предоставить информацию об аргументах вызова (и восстанавливает их исходное состояние перед возвратом):

CMAKE_FIND_PACKAGE_NAME

имя <package>, которое ищется

<package>_FIND_REQUIRED

true, если опция REQUIRED была задана

<package>_FIND_QUIETLY

true, если опция QUIET была задана

<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_EXACT

true, если опция EXACT была задана

<package>_FIND_COMPONENTS

список запрошенных компонентов

<package>_FIND_REQUIRED_<c>

true, если компонент <c> необходим, false, если компонент <c> необязателен

В режиме модуля загруженный модуль поиска отвечает за выполнение запроса, детализированного этими переменными; см. модуль поиска для получения подробностей. В режиме конфигурации find_package автоматически обрабатывает опции REQUIRED, QUIET, и [version], но делегирует обработку компонентов файлу конфигурации пакета, чтобы он обрабатывал их логичным способом для пакета. Файл конфигурации пакета может установить <package>_FOUND в false, чтобы сообщить find_package, что требования к компонентам не выполнены.

См. документацию команды cmake_policy() для обсуждения опции NO_POLICY_SCOPE.