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() также генерирует в файл FooConfig.cmake два вспомогательных макроса set_and_check() и check_required_components().

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>]
  [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. Это можно использовать совместно с аргументом 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.

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_OSX_ARCHITECTURES, например, для включения из файла, специфичного для Apple <PackageName>Config.cmake.

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)