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

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

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.