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(), при создании файла <Name>Config.cmake или <Name>-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.

Если передан аргумент INSTALL_PREFIX, он используется в качестве базового пути для расчёта всех относительных путей. Аргумент <path> должен быть абсолютным путём. Если этот аргумент не передан, вместо него используется переменная CMAKE_INSTALL_PREFIX. Значение по умолчанию подходит при генерации файла FooConfig.cmake для использования пакета из дерева установки. При генерации файла FooConfig.cmake для использования пакета из дерева сборки следует использовать этот вариант.

По умолчанию 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(<package_name>) следует вызывать в конце файла 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|ExactVersion> )

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

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

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

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

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

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

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

CMakeLists.txt:

set(INCLUDE_INSTALL_DIR include/ ... CACHE )
set(LIB_INSTALL_DIR lib/ ... CACHE )
set(SYSCONFIG_INSTALL_DIR etc/foo/ ... CACHE )
#...
include(CMakePackageConfigHelpers)
configure_package_config_file(FooConfig.cmake.in
  ${CMAKE_CURRENT_BINARY_DIR}/FooConfig.cmake
  INSTALL_DESTINATION ${LIB_INSTALL_DIR}/Foo/cmake
  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 ${LIB_INSTALL_DIR}/Foo/cmake )

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)