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() для задания директорий и местоположений файлов. В дополнение к установке переменной, он также проверяет, что ссылка на файл или директорию существует на самом деле, и завершается ошибкой FATAL_ERROR, если этого нет. Это гарантирует, что созданный файл 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|SameMinorVersion|ExactVersion> )

Записывает файл для использования в качестве файла <package>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:

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)