CMakePackageConfigHelpers

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

Генерация файла конфигурации пакета

configure_package_config_file

Создать файл конфигурации для проекта:

configure_package_config_file(<input> <output>
  INSTALL_DESTINATION <path>
  [PATH_VARS <var1> <var2> ... <varN>]
  [NO_SET_AND_CHECK_MACRO]
  [NO_CHECK_REQUIRED_COMPONENTS_MACRO]
  [INSTALL_PREFIX <path>]
  )

configure_package_config_file() следует использовать вместо команды configure_file(), когда создаётся файл <PackageName>Config.cmake или <PackageName>-config.cmake для установки проекта или библиотеки. Это помогает сделать результирующий пакет переносимым, избегая жёстко заданных путей в установленных файлах <PackageName>Config.cmake.

В файле FooConfig.cmake может быть код, подобный этому, чтобы указать места установки используемому проекту:

set(FOO_INCLUDE_DIR   "@CMAKE_INSTALL_FULL_INCLUDEDIR@" )
set(FOO_DATA_DIR   "@CMAKE_INSTALL_PREFIX@/@RELATIVE_DATA_INSTALL_DIR@" )
set(FOO_ICONS_DIR   "@CMAKE_INSTALL_PREFIX@/share/icons" )
#...logic to determine installedPrefix from the own location...
set(FOO_CONFIG_DIR  "${installedPrefix}/@CONFIG_INSTALL_DIR@" )

Все четыре показанных варианта недостаточны. Первые три жёстко задают абсолютные пути к каталогам. Четвёртый вариант работает только в том случае, если логика определения installedPrefix верна, и если CONFIG_INSTALL_DIR содержит относительный путь, что, как правило, гарантировать нельзя. Это приводит к тому, что результирующий файл FooConfig.cmake будет работать плохо в Windows и macOS, где пользователи привыкли выбирать место установки бинарного пакета во время установки, независимо от того, как CMAKE_INSTALL_PREFIX был задан во время сборки/CMake.

Использование configure_package_config_file() помогает. Если используется правильно, оно делает результирующий файл FooConfig.cmake переносимым. Использование:

1. Напишите файл FooConfig.cmake.in, как вы обычно это делаете.
2. Вставьте в начало строку, содержащую только строку @PACKAGE_INIT@.
3. Вместо set(FOO_DIR "@SOME_INSTALL_DIR@"), используйте set(FOO_DIR "@PACKAGE_SOME_INSTALL_DIR@") (эта строка должна следовать за строкой @PACKAGE_INIT@).
4. Вместо обычной команды configure_file(), используйте configure_package_config_file().

Аргументы <input> и <output> являются входным и выходным файлами, точно так же, как в configure_file().

<path> , предоставленное INSTALL_DESTINATION, должно быть местом назначения, куда будет установлен файл FooConfig.cmake. Этот путь может быть абсолютным или относительным к пути INSTALL_PREFIX.

Переменные <var1> до <varN>, заданные как PATH_VARS, являются переменными, содержащими места установки. Для каждой из них макрос создаст вспомогательную переменную PACKAGE_<var...>. Эти вспомогательные переменные должны использоваться в файле FooConfig.cmake.in для задания места установки. Они вычисляются configure_package_config_file(), так что всегда являются относительными к месту установки пакета. Это работает как для относительных, так и для абсолютных путей. Для абсолютных путей это работает только в том случае, если абсолютный путь является подкаталогом INSTALL_PREFIX.

По умолчанию, configure_package_config_file() также генерирует два вспомогательных макроса, set_and_check() и check_required_components(), в файл FooConfig.cmake.

set_and_check() следует использовать вместо обычной команды set() для задания каталогов и мест расположения файлов. Помимо задания переменной, он также проверяет, что указанный файл или каталог действительно существуют, и выдаёт ошибку с сообщением об ошибке, если этого нет. Это гарантирует, что сгенерированный файл FooConfig.cmake не содержит неправильных ссылок. Добавьте опцию NO_SET_AND_CHECK_MACRO для предотвращения генерации макроса set_and_check() в файле FooConfig.cmake.

check_required_components(<PackageName>) следует вызывать в конце файла FooConfig.cmake. Этот макрос проверяет, все ли запрошенные, не необязательные компоненты были найдены, и если это не так, задаёт переменную Foo_FOUND значение FALSE, так что пакет считается не найденным. Это делается путём проверки переменных Foo_<Component>_FOUND для всех запрошенных необходимых компонентов. Этот макрос следует вызывать даже если пакет не предоставляет никаких компонентов, чтобы убедиться, что пользователи не указывают компоненты ошибочно. Добавьте опцию NO_CHECK_REQUIRED_COMPONENTS_MACRO для предотвращения генерации макроса check_required_components() в файле FooConfig.cmake.

См. также Примеры генерации файлов пакета.

Генерация файла версии пакета

write_basic_package_version_file

Создать файл версии для проекта:

write_basic_package_version_file(<filename>
  [VERSION <major.minor.patch>]
  COMPATIBILITY <AnyNewerVersion|SameMajorVersion|SameMinorVersion|ExactVersion>
  [ARCH_INDEPENDENT] )

Создаёт файл для использования в качестве файла <PackageName>ConfigVersion.cmake в <filename>. Смотрите документацию find_package() для подробностей о таких файлах.

<filename> — имя выходного файла, которое должно находиться в дереве сборки. <major.minor.patch> — номер версии проекта, который будет установлен.

Если VERSION не указан, используется переменная PROJECT_VERSION. Если она не задана, возникает ошибка.

Режим COMPATIBILITY AnyNewerVersion означает, что установленная версия пакета будет считаться совместимой, если она новее или точно такая же, как запрошенная версия. Этот режим следует использовать для пакетов, которые полностью совместимы назад, также и между основными версиями. Если используется SameMajorVersion, то поведение отличается от AnyNewerVersion тем, что номер основной версии должен быть таким же, как запрошенный, например, версия 2.0 не будет считаться совместимой, если запрошена версия 1.0. Этот режим следует использовать для пакетов, которые гарантируют обратную совместимость в рамках одной основной версии. Если используется SameMinorVersion, поведение такое же, как у SameMajorVersion, но и основная, и второстепенная версия должны быть такими же, как запрошенные, например, версия 0.2 не будет считаться совместимой, если запрошена версия 0.1. Если используется ExactVersion, пакет считается совместимым только в том случае, если запрошенная версия точно совпадает с его собственной версией (не учитывая незначительные изменения). Например, версия 1.2.3 пакета считается совместимой только с запрошенной версией 1.2.3. Этот режим предназначен для пакетов без гарантий совместимости. Если в вашем проекте есть более сложные правила сопоставления версий, вам необходимо написать свой собственный файл <PackageName>ConfigVersion.cmake вместо использования этого макроса.

Внутренне, эта макрокоманда выполняет configure_file() для создания итогового файла версии. В зависимости от COMPATIBILITY, используется соответствующий файл BasicConfigVersion-<COMPATIBILITY>.cmake.in. Обратите внимание, что эти файлы внутренние для CMake, и вы не должны сами вызывать configure_file() на них, но их можно использовать в качестве отправной точки для создания более сложных пользовательских файлов <PackageName>ConfigVersion.cmake.

Генерация файла выбора платформы Apple

generate_apple_platform_selection_file

Добавлен в версии 3.29.

Создать файл выбора платформы Apple:

generate_apple_platform_selection_file(<filename>
  INSTALL_DESTINATION <path>
  [INSTALL_PREFIX <path>]
  [MACOS_INCLUDE_FILE <file>]
  [IOS_INCLUDE_FILE <file>]
  [IOS_SIMULATOR_INCLUDE_FILE <file>]
  [IOS_CATALYST_INCLUDE_FILE <file>]
  [TVOS_INCLUDE_FILE <file>]
  [TVOS_SIMULATOR_INCLUDE_FILE <file>]
  [WATCHOS_INCLUDE_FILE <file>]
  [WATCHOS_SIMULATOR_INCLUDE_FILE <file>]
  [VISIONOS_INCLUDE_FILE <file>]
  [VISIONOS_SIMULATOR_INCLUDE_FILE <file>]
  [ERROR_VARIABLE <variable>]
  )

Записать файл, который включает файл, специфичный для платформы Apple .cmake, например, для использования в качестве <PackageName>Config.cmake. Это можно использовать совместно с аргументом XCFRAMEWORK_LOCATION команды export(SETUP) для экспорта пакетов таким образом, чтобы ими могли пользоваться проекты, построенные для любой платформы Apple.

INSTALL_DESTINATION <path>

Путь, по которому вызывающий компонент установит сгенерированный файл, например, с помощью install(FILES). Путь может быть относительным к INSTALL_PREFIX или абсолютным.

INSTALL_PREFIX <path>

Префикс пути, по которому вызывающий компонент установит пакет. Аргумент <path> должен быть абсолютным путем. Если этот аргумент не передан, будет использоваться переменная CMAKE_INSTALL_PREFIX вместо этого.

MACOS_INCLUDE_FILE <file>

Файл для включения, если платформа macOS.

IOS_INCLUDE_FILE <file>

Файл для включения, если платформа iOS.

IOS_SIMULATOR_INCLUDE_FILE <file>

Файл для включения, если платформа iOS Simulator.

IOS_CATALYST_INCLUDE_FILE <file>

Добавлен в версии 3.31.

Файл для включения, если платформа iOS Catalyst.

TVOS_INCLUDE_FILE <file>

Файл для включения, если платформа tvOS.

TVOS_SIMULATOR_INCLUDE_FILE <file>

Файл для включения, если платформа tvOS Simulator.

WATCHOS_INCLUDE_FILE <file>

Файл для включения, если платформа watchOS.

WATCHOS_SIMULATOR_INCLUDE_FILE <file>

Файл для включения, если платформа watchOS Simulator.

VISIONOS_INCLUDE_FILE <file>

Файл для включения, если платформа visionOS.

VISIONOS_SIMULATOR_INCLUDE_FILE <file>

Файл для включения, если платформа visionOS Simulator.

ERROR_VARIABLE <variable>

Если потребляющий проект построен для неподдерживаемой платформы, установите <variable> в сообщение об ошибке. Включающий компонент может использовать эту информацию для имитации отсутствия пакета. Если этот параметр не задан, по умолчанию выдаётся фатальная ошибка.

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

Генерация файла выбора архитектуры Apple

generate_apple_architecture_selection_file

Добавлен в версии 3.29.

Создать файл выбора архитектуры Apple:

generate_apple_architecture_selection_file(<filename>
  INSTALL_DESTINATION <path>
  [INSTALL_PREFIX <path>]
  [SINGLE_ARCHITECTURES <arch>...
   SINGLE_ARCHITECTURE_INCLUDE_FILES <file>...]
  [UNIVERSAL_ARCHITECTURES <arch>...
   UNIVERSAL_INCLUDE_FILE <file>]
  [ERROR_VARIABLE <variable>]
  )

Записать файл, который включает файл, специфичный для архитектуры Apple .cmake, на основе CMAKE_OSX_ARCHITECTURES, например, для включения из файла <PackageName>Config.cmake специфичного для Apple.

INSTALL_DESTINATION <path>

Путь, по которому вызывающий компонент установит сгенерированный файл, например, с помощью install(FILES). Путь может быть относительным к INSTALL_PREFIX или абсолютным.

INSTALL_PREFIX <path>

Префикс пути, по которому вызывающий компонент установит пакет. Аргумент <path> должен быть абсолютным путем. Если этот аргумент не передан, будет использоваться переменная CMAKE_INSTALL_PREFIX вместо этого.

SINGLE_ARCHITECTURES <arch>...

Архитектуры, предоставляемые записями SINGLE_ARCHITECTURE_INCLUDE_FILES.

SINGLE_ARCHITECTURE_INCLUDE_FILES <file>...

Архитектурные файлы. Один из них будет загружен, когда CMAKE_OSX_ARCHITECTURES содержит единственную архитектуру, соответствующую соответствующей записи SINGLE_ARCHITECTURES.

UNIVERSAL_ARCHITECTURES <arch>...

Архитектуры, предоставленные UNIVERSAL_INCLUDE_FILE.

Список может включать $(ARCHS_STANDARD) для поддержки использования с генератором Xcode, но архитектуры также всегда должны быть перечислены индивидуально.

UNIVERSAL_INCLUDE_FILE <file>

Файл для загрузки, когда CMAKE_OSX_ARCHITECTURES содержит (нестрогую) подмножество UNIVERSAL_ARCHITECTURES и не соответствует ни одному из SINGLE_ARCHITECTURES.

ERROR_VARIABLE <variable>

Если потребляющий проект построен для неподдерживаемой архитектуры, установите <variable> в сообщение об ошибке. Включающий компонент может использовать эту информацию для имитации отсутствия пакета. Если этот параметр не задан, по умолчанию выдаётся фатальная ошибка.

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

Пример использования команд configure_package_config_file() и write_basic_package_version_file():

include(GNUInstallDirs)
set(INCLUDE_INSTALL_DIR ${CMAKE_INSTALL_INCLUDEDIR}/Foo
    CACHE PATH "Location of header files" )
set(SYSCONFIG_INSTALL_DIR ${CMAKE_INSTALL_SYSCONFDIR}/foo
    CACHE PATH "Location of configuration files" )
#...
include(CMakePackageConfigHelpers)
configure_package_config_file(FooConfig.cmake.in
  ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
  INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Foo
  PATH_VARS INCLUDE_INSTALL_DIR SYSCONFIG_INSTALL_DIR)
write_basic_package_version_file(
  ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
  VERSION 1.2.3
  COMPATIBILITY SameMajorVersion )
install(FILES ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
              ${CMAKE_CURRENT_BINARY_DIR}/FooConfigVersion.cmake
        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Foo )

set(FOO_VERSION x.y.z)
...
@PACKAGE_INIT@
...
set_and_check(FOO_INCLUDE_DIR "@PACKAGE_INCLUDE_INSTALL_DIR@")
set_and_check(FOO_SYSCONFIG_DIR "@PACKAGE_SYSCONFIG_INSTALL_DIR@")

check_required_components(Foo)