find_package

• Базовая подпись и режим модуля
• Полная подпись и режим конфигурации
• Выбор версии
• Процедура поиска
• Переменные интерфейса файла пакета

Найдите внешний проект и загрузите его настройки.

Базовая подпись и режим модуля

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

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

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

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

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

Команда имеет два режима поиска пакетов: режим «Модуль» и режим «Конфигурация». Вышеуказанная подпись выбирает режим «Модуль». Если модуль не найден, команда переходит в режим «Конфигурация», описанный ниже. Этот переход отключается, если указана опция MODULE.

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

Полная подпись и режим конфигурации

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

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

find_package(<PackageName> [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, или использование опций, не указанных в базовой подписи, навязывают чистый режим «Конфигурация». В чистом режиме «Конфигурация» команда пропускает поиск в режиме «Модуль» и сразу переходит к поиску в режиме «Конфигурация».

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

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

Если файл конфигурации пакета не найден, CMake сгенерирует сообщение об ошибке, если не задан аргумент QUIET. Если REQUIRED указан, и пакет не найден, генерируется ошибка «fatal» и процесс конфигурации останавливается. Если <PackageName>_DIR установлен в каталог, не содержащий файла конфигурации, CMake проигнорирует его и начнёт поиск заново.

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

Выбор версии

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

PACKAGE_FIND_NAME

<PackageName>

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. Если версия приемлема, устанавливаются следующие переменные:

<PackageName>_VERSION

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

<PackageName>_VERSION_MAJOR

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

<PackageName>_VERSION_MINOR

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

<PackageName>_VERSION_PATCH

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

<PackageName>_VERSION_TWEAK

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

<PackageName>_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.

Процедура поиска

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)

В системах, поддерживающих macOS Frameworks и Application Bundles, ищутся следующие каталоги для поиска фреймворков или пакетов, содержащих файл конфигурации:

<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> рассматривается как нечувствительный к регистру и соответствует любому из указанных имён (<PackageName> или имена, заданные 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 ищутся в платформах с ABI x32, если свойство 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:

   <PackageName>_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. Поиск путей, определённых переменными CMake в файлах платформы для текущей системы. Это можно пропустить, если передано 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 (<PackageName> PATHS paths... NO_DEFAULT_PATH)
find_package (<PackageName>)

После успешного выполнения одного из вызовов переменная результата будет установлена и сохранена в кэше, поэтому никакой вызов не будет производить поиск повторно.

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

Переменные интерфейса файлов пакета

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

CMAKE_FIND_PACKAGE_NAME

искомый <PackageName>

<PackageName>_FIND_REQUIRED

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

<PackageName>_FIND_QUIETLY

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

<PackageName>_FIND_VERSION

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

<PackageName>_FIND_VERSION_MAJOR

главный номер версии, если запрошен, иначе 0

<PackageName>_FIND_VERSION_MINOR

второй номер версии, если запрошен, иначе 0

<PackageName>_FIND_VERSION_PATCH

поправочный номер версии, если запрошен, иначе 0

<PackageName>_FIND_VERSION_TWEAK

номер версии доработки, если запрошен, иначе 0

<PackageName>_FIND_VERSION_COUNT

количество компонентов версии, от 0 до 4

<PackageName>_FIND_VERSION_EXACT

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

<PackageName>_FIND_COMPONENTS

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

<PackageName>_FIND_REQUIRED_<c>

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

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