diff options
Diffstat (limited to 'Modules/CMakePackageConfigHelpers.cmake')
| -rw-r--r-- | Modules/CMakePackageConfigHelpers.cmake | 282 |
1 files changed, 165 insertions, 117 deletions
diff --git a/Modules/CMakePackageConfigHelpers.cmake b/Modules/CMakePackageConfigHelpers.cmake index 3c56b7fcc6..855af9c9f5 100644 --- a/Modules/CMakePackageConfigHelpers.cmake +++ b/Modules/CMakePackageConfigHelpers.cmake @@ -1,135 +1,183 @@ -# - CONFIGURE_PACKAGE_CONFIG_FILE(), WRITE_BASIC_PACKAGE_VERSION_FILE() +#.rst: +# CMakePackageConfigHelpers +# ------------------------- +# +# CONFIGURE_PACKAGE_CONFIG_FILE(), WRITE_BASIC_PACKAGE_VERSION_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] +# [NO_FIND_DEPENDENCY_MACRO]) +# # -# CONFIGURE_PACKAGE_CONFIG_FILE(<input> <output> INSTALL_DESTINATION <path> -# [PATH_VARS <var1> <var2> ... <varN>] -# [NO_SET_AND_CHECK_MACRO] -# [NO_CHECK_REQUIRED_COMPONENTS_MACRO] -# [NO_FIND_DEPENDENCY_MACRO]) # # CONFIGURE_PACKAGE_CONFIG_FILE() should be used instead of the plain -# configure_file() command when creating the <Name>Config.cmake or <Name>-config.cmake -# file for installing a project or library. It helps making the resulting package -# relocatable by avoiding hardcoded paths in the installed Config.cmake file. +# configure_file() command when creating the <Name>Config.cmake or +# <Name>-config.cmake file for installing a project or library. It +# helps making the resulting package relocatable by avoiding hardcoded +# paths in the installed Config.cmake file. # # In a FooConfig.cmake file there may be code like this to make the # install destinations know to the using project: -# 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@" ) -# All 4 options shown above are not sufficient, since the first 3 hardcode -# the absolute directory locations, and the 4th case works only if the logic -# to determine the installedPrefix is correct, and if CONFIG_INSTALL_DIR contains -# a relative path, which in general cannot be guaranteed. -# This has the effect that the resulting FooConfig.cmake file would work poorly -# under Windows and OSX, where users are used to choose the install location -# of a binary package at install time, independent from how CMAKE_INSTALL_PREFIX -# was set at build/cmake time. -# -# Using CONFIGURE_PACKAGE_CONFIG_FILE() helps. If used correctly, it makes the -# resulting FooConfig.cmake file relocatable. -# Usage: -# 1. write a FooConfig.cmake.in file as you are used to -# 2. insert a line containing only the string "@PACKAGE_INIT@" -# 3. instead of set(FOO_DIR "@SOME_INSTALL_DIR@"), use set(FOO_DIR "@PACKAGE_SOME_INSTALL_DIR@") -# (this must be after the @PACKAGE_INIT@ line) -# 4. instead of using the normal configure_file(), use CONFIGURE_PACKAGE_CONFIG_FILE() -# -# The <input> and <output> arguments are the input and output file, the same way -# as in configure_file(). -# -# The <path> given to INSTALL_DESTINATION must be the destination where the FooConfig.cmake -# file will be installed to. This can either be a relative or absolute path, both work. -# -# The variables <var1> to <varN> given as PATH_VARS are the variables which contain -# install destinations. For each of them the macro will create a helper variable -# PACKAGE_<var...>. These helper variables must be used -# in the FooConfig.cmake.in file for setting the installed location. They are calculated -# by CONFIGURE_PACKAGE_CONFIG_FILE() so that they are always relative to the -# installed location of the package. This works both for relative and also for absolute locations. -# For absolute locations it works only if the absolute location is a subdirectory -# of CMAKE_INSTALL_PREFIX. -# -# By default configure_package_config_file() also generates two helper macros, -# set_and_check() and check_required_components() into the FooConfig.cmake file. -# -# set_and_check() should be used instead of the normal set() -# command for setting directories and file locations. Additionally to setting the -# variable it also checks that the referenced file or directory actually exists -# and fails with a FATAL_ERROR otherwise. This makes sure that the created -# FooConfig.cmake file does not contain wrong references. -# When using the NO_SET_AND_CHECK_MACRO, this macro is not generated into the +# +# :: +# +# 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@" ) +# +# All 4 options shown above are not sufficient, since the first 3 +# hardcode the absolute directory locations, and the 4th case works only +# if the logic to determine the installedPrefix is correct, and if +# CONFIG_INSTALL_DIR contains a relative path, which in general cannot +# be guaranteed. This has the effect that the resulting FooConfig.cmake +# file would work poorly under Windows and OSX, where users are used to +# choose the install location of a binary package at install time, +# independent from how CMAKE_INSTALL_PREFIX was set at build/cmake time. +# +# Using CONFIGURE_PACKAGE_CONFIG_FILE() helps. If used correctly, it +# makes the resulting FooConfig.cmake file relocatable. Usage: +# +# :: +# +# 1. write a FooConfig.cmake.in file as you are used to +# 2. insert a line containing only the string "@PACKAGE_INIT@" +# 3. instead of set(FOO_DIR "@SOME_INSTALL_DIR@"), use set(FOO_DIR "@PACKAGE_SOME_INSTALL_DIR@") +# (this must be after the @PACKAGE_INIT@ line) +# 4. instead of using the normal configure_file(), use CONFIGURE_PACKAGE_CONFIG_FILE() +# +# +# +# The <input> and <output> arguments are the input and output file, the +# same way as in configure_file(). +# +# The <path> given to INSTALL_DESTINATION must be the destination where +# the FooConfig.cmake file will be installed to. This can either be a +# relative or absolute path, both work. +# +# The variables <var1> to <varN> given as PATH_VARS are the variables +# which contain install destinations. For each of them the macro will +# create a helper variable PACKAGE_<var...>. These helper variables +# must be used in the FooConfig.cmake.in file for setting the installed +# location. They are calculated by CONFIGURE_PACKAGE_CONFIG_FILE() so +# that they are always relative to the installed location of the +# package. This works both for relative and also for absolute +# locations. For absolute locations it works only if the absolute +# location is a subdirectory of CMAKE_INSTALL_PREFIX. +# +# By default configure_package_config_file() also generates two helper +# macros, set_and_check() and check_required_components() into the # FooConfig.cmake file. # -# check_required_components(<package_name>) should be called at the end of the -# FooConfig.cmake file if the package supports components. -# This macro checks whether all requested, non-optional components have been found, -# and if this is not the case, sets the Foo_FOUND variable to FALSE, so that the package -# is considered to be not found. -# It does that by testing the Foo_<Component>_FOUND variables for all requested -# required components. -# When using the NO_CHECK_REQUIRED_COMPONENTS option, this macro is not generated +# set_and_check() should be used instead of the normal set() command for +# setting directories and file locations. Additionally to setting the +# variable it also checks that the referenced file or directory actually +# exists and fails with a FATAL_ERROR otherwise. This makes sure that +# the created FooConfig.cmake file does not contain wrong references. +# When using the NO_SET_AND_CHECK_MACRO, this macro is not generated # into the FooConfig.cmake file. # -# For an example see below the documentation for WRITE_BASIC_PACKAGE_VERSION_FILE(). -# -# -# WRITE_BASIC_PACKAGE_VERSION_FILE( filename VERSION major.minor.patch COMPATIBILITY (AnyNewerVersion|SameMajorVersion|ExactVersion) ) -# -# Writes a file for use as <package>ConfigVersion.cmake file to <filename>. -# See the documentation of find_package() for details on this. -# filename is the output filename, it should be in the build tree. -# major.minor.patch is the version number of the project to be installed -# The COMPATIBILITY mode AnyNewerVersion means that the installed package version -# will be considered compatible if it is newer or exactly the same as the requested version. -# This mode should be used for packages which are fully backward compatible, -# also across major versions. -# If SameMajorVersion is used instead, then the behaviour differs from AnyNewerVersion -# in that the major version number must be the same as requested, e.g. version 2.0 will -# not be considered compatible if 1.0 is requested. -# This mode should be used for packages which guarantee backward compatibility within the -# same major version. -# If ExactVersion is used, then the package is only considered compatible if the requested -# version matches exactly its own version number (not considering the tweak version). -# For example, version 1.2.3 of a package is only considered compatible to requested version 1.2.3. -# This mode is for packages without compatibility guarantees. -# If your project has more elaborated version matching rules, you will need to write your -# own custom ConfigVersion.cmake file instead of using this macro. -# -# Internally, this macro executes configure_file() to create the resulting -# version file. Depending on the COMPATIBLITY, either the file -# BasicConfigVersion-SameMajorVersion.cmake.in or BasicConfigVersion-AnyNewerVersion.cmake.in -# is used. Please note that these two files are internal to CMake and you should -# not call configure_file() on them yourself, but they can be used as starting +# check_required_components(<package_name>) should be called at the end +# of the FooConfig.cmake file if the package supports components. This +# macro checks whether all requested, non-optional components have been +# found, and if this is not the case, sets the Foo_FOUND variable to +# FALSE, so that the package is considered to be not found. It does +# that by testing the Foo_<Component>_FOUND variables for all requested +# required components. When using the NO_CHECK_REQUIRED_COMPONENTS +# option, this macro is not generated into the FooConfig.cmake file. +# +# For an example see below the documentation for +# WRITE_BASIC_PACKAGE_VERSION_FILE(). +# +# +# +# :: +# +# WRITE_BASIC_PACKAGE_VERSION_FILE( filename VERSION major.minor.patch COMPATIBILITY (AnyNewerVersion|SameMajorVersion|ExactVersion) ) +# +# +# +# Writes a file for use as <package>ConfigVersion.cmake file to +# <filename>. See the documentation of find_package() for details on +# this. +# +# :: +# +# filename is the output filename, it should be in the build tree. +# major.minor.patch is the version number of the project to be installed +# +# The COMPATIBILITY mode AnyNewerVersion means that the installed +# package version will be considered compatible if it is newer or +# exactly the same as the requested version. This mode should be used +# for packages which are fully backward compatible, also across major +# versions. If SameMajorVersion is used instead, then the behaviour +# differs from AnyNewerVersion in that the major version number must be +# the same as requested, e.g. version 2.0 will not be considered +# compatible if 1.0 is requested. This mode should be used for packages +# which guarantee backward compatibility within the same major version. +# If ExactVersion is used, then the package is only considered +# compatible if the requested version matches exactly its own version +# number (not considering the tweak version). For example, version +# 1.2.3 of a package is only considered compatible to requested version +# 1.2.3. This mode is for packages without compatibility guarantees. +# If your project has more elaborated version matching rules, you will +# need to write your own custom ConfigVersion.cmake file instead of +# using this macro. +# +# Internally, this macro executes configure_file() to create the +# resulting version file. Depending on the COMPATIBLITY, either the +# file BasicConfigVersion-SameMajorVersion.cmake.in or +# BasicConfigVersion-AnyNewerVersion.cmake.in is used. Please note that +# these two files are internal to CMake and you should not call +# configure_file() on them yourself, but they can be used as starting # point to create more sophisticted custom ConfigVersion.cmake files. # # -# Example using both configure_package_config_file() and 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 ) +# +# Example using both configure_package_config_file() and +# 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 ) +# +# # # With a 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) +# +# :: +# +# 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) #============================================================================= |