CMakePackageConfigHelpers

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

Загрузите этот модуль в проекте CMake с помощью:

include(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() для задания каталогов и расположения файлов следует использовать set_and_check(). Помимо задания переменной, она проверяет, существует ли указанный файл или каталог, и при его отсутствии завершается с фатальной ошибкой. Это гарантирует, что сгенерированный файл 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|
                 SamePatchVersion|SameFullVersion|SemanticVersion|
                 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. При использовании SamePatchVersion пакет считается совместимым, только если запрошенная версия точно совпадает вплоть до версии исправления, без учета версии доработки. Например, версия пакета 1.2.3.4 считается совместимой с запрошенной версией 1.2.3.5, но не с запрошенной версией 1.2.4. При использовании SameFullVersion пакет считается совместимым, только если запрошенная версия точно совпадает со всеми указанными компонентами версии. Например, версия пакета 1.2.3.4 считается совместимой только с запрошенной версией 1.2.3.4. Отсутствующие компоненты версии не считаются неявными нулями, поэтому версия 1.2.3 не считается совместимой с запрошенной версией 1.2.3.0. При использовании SemanticVersion поведение соответствует обычной интерпретации семантического версионирования: если основной компонент установленной версии пакета больше нуля, поведение совпадает с SameMajorVersion. Если основной компонент установленной версии пакета равен нулю, поведение совпадает с SameMinorVersion. При использовании ExactVersion поведение совпадает с SamePatchVersion.

Если в проекте используются более сложные правила сопоставления версий, потребуется написать собственный файл <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>]
  )

Запишите файл, который включает файл .cmake для конкретной платформы Apple, например для использования в качестве <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>]
  )

Запишите файл, который включает файл .cmake для конкретной архитектуры Apple на основе 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)