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 не устанавливает никаких соглашений о значении номеров версий. Номера версий пакетов проверяются с помощью файлов «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

истина, если версия — точное соответствие

PACKAGE_VERSION_COMPATIBLE

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

PACKAGE_VERSION_UNSUITABLE

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

Эти переменные проверяются командой 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 Framework и Application Bundle, следующие каталоги ищутся для фреймворков или пакетов, содержащих файл конфигурации:

<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. Поиск путей, хранящихся в переменных 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