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>]
  )

在安装项目或库以创建 <PackageName>Config.cmake 或 <PackageName>-config.cmake 文件时，应使用 configure_package_config_file() 代替普通的 configure_file() 命令。它通过避免在安装的 <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 时 CMAKE_INSTALL_PREFIX 的设置方式无关。

使用 configure_package_config_file() 有所帮助。如果使用得当，它能使生成的 FooConfig.cmake 文件可重定位。用法

1. 像往常一样编写一个 FooConfig.cmake.in 文件。

2. 在顶部插入一行，仅包含字符串 @PACKAGE_INIT@。

3. 使用 set(FOO_DIR "@PACKAGE_SOME_INSTALL_DIR@" 代替 set(FOO_DIR "@SOME_INSTALL_DIR@"（此行必须在 @PACKAGE_INIT@ 行之后）。

4. 使用 configure_package_config_file() 代替普通的 configure_file() 命令。

<input> 和 <output> 参数是输入和输出文件，与 configure_file() 中的含义相同。

提供给 INSTALL_DESTINATION 的 <path> 必须是 FooConfig.cmake 文件将被安装到的目标路径。此路径可以是绝对路径，也可以是相对于 INSTALL_PREFIX 路径的相对路径。

PATH_VARS 作为参数给出的变量 <var1> 到 <varN> 是包含安装目标的变量。对于其中每一个变量，宏将创建一个辅助变量 PACKAGE_<var...>。这些辅助变量必须在 FooConfig.cmake.in 文件中用于设置安装位置。它们由 configure_package_config_file() 计算，以便它们始终相对于包的安装位置。这适用于相对路径和绝对路径。对于绝对路径，只有当绝对路径是 INSTALL_PREFIX 的子目录时才有效。

Added in version 3.30: 变量 PACKAGE_PREFIX_DIR 在 @PACKAGE_INIT@ 行之后始终被定义。它将保存基本安装位置的值。通常，应使用通过 PATH_VARS 机制定义的变量，但 PACKAGE_PREFIX_DIR 可用于那些 PATH_VARS 难以处理的情况，例如安装到基本安装位置而不是其子目录的文件。

注意

当生成文件的使用者使用 CMake 3.29 或更早版本时，PACKAGE_PREFIX_DIR 的值可以通过调用 find_dependency() 或 find_package() 来更改。如果一个项目依赖于 PACKAGE_PREFIX_DIR，那么该项目有责任确保 PACKAGE_PREFIX_DIR 的值在任何此类调用或可能包含由 configure_package_config_file() 生成的其他文件的调用中都得以保留。

Added in version 3.1: 如果传递了 INSTALL_PREFIX 参数，它将用作计算所有相对路径的基本路径。 <path> 参数必须是绝对路径。如果未传递此参数，则改用 CMAKE_INSTALL_PREFIX 变量。在生成用于从安装树中使用的包的 FooConfig.cmake 文件时，默认值很好。在生成用于从构建树中使用的包的 FooConfig.cmake 文件时，应使用此选项。

默认情况下，configure_package_config_file() 还在 FooConfig.cmake 文件中生成两个辅助宏：set_and_check() 和 check_required_components()。

set_and_check() 应代替普通的 set() 命令来设置目录和文件位置。除了设置变量外，它还检查引用的文件或目录是否存在，如果不存在则发出致命错误。这确保生成的 FooConfig.cmake 文件不包含错误的引用。添加 NO_SET_AND_CHECK_MACRO 选项以阻止在 FooConfig.cmake 文件中生成 set_and_check() 宏。

check_required_components(<PackageName>) 应在 FooConfig.cmake 文件末尾调用。此宏检查是否已找到所有请求的非可选组件，如果未找到，则将 Foo_FOUND 变量设置为 FALSE，以便将包视为未找到。它通过测试所有已请求的必需组件的 Foo_<Component>_FOUND 变量来做到这一点。即使包不提供任何组件，也应调用此宏，以确保用户不会错误地指定组件。添加 NO_CHECK_REQUIRED_COMPONENTS_MACRO 选项以阻止在 FooConfig.cmake 文件中生成 check_required_components() 宏。

另请参阅 生成包文件的示例。

生成包版本文件

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 不同，主版本号必须与请求的版本相同，例如，如果请求 1.0，则 2.0 不被视为兼容。此模式适用于保证同一主版本内的向后兼容性的包。如果使用 SameMinorVersion，则行为与 SameMajorVersion 相同，但主版本和次版本号都必须与请求的版本相同，例如，如果请求 0.1，则 0.2 不兼容。如果使用 ExactVersion，则仅当请求的版本号与包自身的版本号（不考虑修订版本号）完全匹配时，才认为包兼容。例如，包的版本 1.2.3 仅与请求的版本 1.2.3 兼容。此模式适用于没有兼容性保证的包。如果您的项目有更复杂的版本匹配规则，您将需要编写自己的自定义 <PackageName>ConfigVersion.cmake 文件，而不是使用此宏。

Added in version 3.11: SameMinorVersion 兼容模式。

Added in version 3.14: 如果指定了 ARCH_INDEPENDENT，则即使安装的包版本是为不同于请求的体系结构构建的，也认为它是兼容的。否则，将执行体系结构检查，并且仅当体系结构完全匹配时，才认为包兼容。例如，如果包是为 32 位体系结构构建的，那么只有当它在 32 位体系结构上使用时，才认为它兼容，除非指定了 ARCH_INDEPENDENT，在这种情况下，包在任何体系结构上都认为兼容。

注意

ARCH_INDEPENDENT 适用于仅标头库或类似的无二进制文件包。

Added in version 3.19: 由 COMPATIBILITY 的 AnyNewerVersion、SameMajorVersion 和 SameMinorVersion 参数生成的版本文件处理版本范围（如果指定了版本范围，请参阅 find_package() 命令以获取详细信息）。ExactVersion 模式与版本范围不兼容，如果指定了版本范围，则会显示作者警告。

内部来说，此宏执行 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>]
  )

写入一个文件，该文件包含一个 Apple 平台特定的 .cmake 文件，例如用于 <PackageName>Config.cmake。这可以与 export(SETUP) 的 XCFRAMEWORK_LOCATION 参数结合使用，以导出包，从而使为任何 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 模拟器，则包含的文件。

IOS_CATALYST_INCLUDE_FILE <file>

在版本 3.31 中添加。

如果平台是 iOS Catalyst，则包含的文件。

TVOS_INCLUDE_FILE <file>

如果平台是 tvOS，则包含的文件。

TVOS_SIMULATOR_INCLUDE_FILE <file>

如果平台是 tvOS 模拟器，则包含的文件。

WATCHOS_INCLUDE_FILE <file>

如果平台是 watchOS，则包含的文件。

WATCHOS_SIMULATOR_INCLUDE_FILE <file>

如果平台是 watchOS 模拟器，则包含的文件。

VISIONOS_INCLUDE_FILE <file>

如果平台是 visionOS，则包含的文件。

VISIONOS_SIMULATOR_INCLUDE_FILE <file>

如果平台是 visionOS 模拟器，则包含的文件。

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_OSX_ARCHITECTURES 包含一个 Apple 体系结构特定的 .cmake 文件，例如用于从 Apple 特定 <PackageName>Config.cmake 文件中包含。

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() 命令的示例

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)