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_CMAKE_ENVIRONMENT_PATH]
             [NO_CMAKE_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

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

Режим «Конфигурация» предоставляет сложный интерфейс и процедуру поиска. Большая часть интерфейса предоставлена для полноты и для внутреннего использования модулями поиска, загруженными в режиме «Модуль». Большинство кода пользователя должно просто вызвать:

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)

На системах, поддерживающих фреймворки и пакеты приложений 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 установлена. Если PATH_SUFFIXES указан, суффиксы добавляются к каждой записи каталога (W) или (U) по очереди.

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

Набор префиксов установки создаётся с помощью следующих шагов. Если NO_DEFAULT_PATH указан, все NO_* опции активированы.

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

   CMAKE_PREFIX_PATH
   CMAKE_FRAMEWORK_PATH
   CMAKE_APPBUNDLE_PATH
   

2. Пути поиска, указанные в переменных окружения CMake. Они предназначены для установки в конфигурации оболочки пользователя. Это можно пропустить, если передано NO_CMAKE_ENVIRONMENT_PATH:

   <package>_DIR
   CMAKE_PREFIX_PATH
   CMAKE_FRAMEWORK_PATH
   CMAKE_APPBUNDLE_PATH
   

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

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

   PATH
   

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

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

   CMAKE_SYSTEM_PREFIX_PATH
   CMAKE_SYSTEM_FRAMEWORK_PATH
   CMAKE_SYSTEM_APPBUNDLE_PATH
   

7. Поиск путей, хранящихся в реестре пакетов CMake Системного реестра пакетов. Это можно пропустить, если передано NO_CMAKE_SYSTEM_PACKAGE_REGISTRY или установив CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY в значение TRUE. Подробности о системном реестре пакетов см. в руководстве cmake-packages(7).
8. Поиск путей, указанных опцией 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

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

<package>_FIND_QUIETLY

истина, если была задана опция 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

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

<package>_FIND_COMPONENTS

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

<package>_FIND_REQUIRED_<c>

истина, если компонент <c> необходим, ложь, если компонент <c> является необязательным

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

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