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_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 не устанавливает никаких соглашений о значении версий. Номера версий пакетов проверяются файлами «версии», предоставляемыми самими пакетами. Для кандидатского файла конфигурации пакета <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. Они предназначены для установки в конфигурации оболочки пользователя и поэтому используют системный разделитель путей хоста (; в Windows и : в UNIX). Это можно пропустить, если передано 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. Поиск путей, указанных в файлах платформы для текущей системы. Это можно пропустить, если передано 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.