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>]
  [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 Симулятор.

TVOS_INCLUDE_FILE <file>

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

TVOS_SIMULATOR_INCLUDE_FILE <file>

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

WATCHOS_INCLUDE_FILE <file>

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

WATCHOS_SIMULATOR_INCLUDE_FILE <file>

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

VISIONOS_INCLUDE_FILE <file>

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

VISIONOS_SIMULATOR_INCLUDE_FILE <file>

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

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)