CMakePackageConfigHelpers

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

Добавляет команды configure_package_config_file() и write_basic_package_version_file().

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

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 для установки проекта или библиотеки. Это помогает сделать релоцируемым результирующий пакет, избегая жёстко заданных путей в установленном файле 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@" )

Все 4 представленных выше варианта недостаточны, поскольку первые 3 жёстко задают абсолютные пути к каталогам, а четвёртый вариант работает только в случае корректной логики определения installedPrefix, и если CONFIG_INSTALL_DIR содержит относительный путь, что, как правило, гарантировать нельзя. В результате, файл FooConfig.cmake будет работать плохо под Windows и OSX, где пользователи привыкли выбирать место установки двоичного пакета во время установки, независимо от того, как был задан 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, этот макрос не генерируется в файл FooConfig.cmake.

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

Пример см. в документации по write_basic_package_version_file().

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

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. Этот режим предназначен для пакетов без гарантий совместимости. Если ваш проект имеет более сложные правила сопоставления версий, вам потребуется написать свой собственный пользовательский файл ConfigVersion.cmake вместо использования этого макроса.

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

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

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

CMakeLists.txt:

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 )

FooConfig.cmake.in:

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)