CPack 外部生成器¶

3.13 版本新增。

CPack 提供了许多生成器，用于为各种平台和打包系统创建软件包。其目的是让 CMake/CPack 成为构建和打包软件项目的完整端到端解决方案。然而，由于技术限制或要求使用特定工具的策略，可能无法始终将 CPack 用于整个打包过程。出于这个原因，CPack 提供了“外部”生成器，它允许外部打包软件利用 CPack 提供的一些功能，例如组件安装和依赖项图。

与外部打包工具集成¶

CPack 外部生成器会生成一个包含 CPack 内部元数据的 .json 文件，该文件为外部软件提供了有关如何打包软件的信息。外部打包软件可以自行调用 CPack，使用生成的元数据，并根据需要安装和打包文件。

或者，CPack 也可以通过 CPACK_EXTERNAL_PACKAGE_SCRIPT 中的可选自定义 CMake 脚本来调用外部打包软件。

当通过 CPACK_EXTERNAL_ENABLE_STAGING 变量启用时，生成器也可以选择性地处理安装文件的暂存。

JSON 格式¶

JSON 元数据文件包含 CPack 组件和组件组的列表，传递给 cpack_add_component() 和 cpack_add_component_group() 的各种选项，组件和组件组之间的依赖关系，以及传递给 CPack 的各种其他选项。

JSON 的根对象将始终提供两个字段：formatVersionMajor 和 formatVersionMinor，它们始终是描述生成器输出格式的整数。输出格式的向后兼容更改（例如，添加一个以前不存在的新字段）会导致次版本号递增，而向后不兼容的更改（例如，删除字段或更改其含义）会导致主版本号递增并将次版本号重置为 0。格式版本始终为 major.minor 格式。换句话说，它始终有两部分，用句点分隔。

您可以通过 CPACK_EXTERNAL_REQUESTED_VERSIONS 来请求一个或多个特定版本的输出格式，如下所述。输出格式的主版本将与请求的主版本完全匹配，次版本将大于或等于请求的次版本。如果使用 CPACK_EXTERNAL_REQUESTED_VERSIONS 未请求版本，则默认使用最新已知的主版本。目前，唯一支持的格式是 1.0，如下所述。

版本 1.0¶

除了标准的格式字段外，格式版本 1.0 在根目录下提供了以下字段

组件

components 字段是一个对象，其中组件名称作为键，描述组件的对象作为值。组件对象具有以下字段

名称: 组件的名称。这始终与 components 对象中的键相同。
displayName: 传递给 cpack_add_component() 的 DISPLAY_NAME 字段的值。
描述: 传递给 cpack_add_component() 的 DESCRIPTION 字段的值。
isHidden: 如果传递了 HIDDEN 给 cpack_add_component()，则为 True；否则为 False。
isRequired: 如果传递了 REQUIRED 给 cpack_add_component()，则为 True；否则为 False。
isDisabledByDefault: 如果传递了 DISABLED 给 cpack_add_component()，则为 True；否则为 False。
group: 仅当将 GROUP 传递给 cpack_add_component() 时存在。如果存在，此字段是包含组件组的字符串值。
dependencies: 组件所依赖的组件数组。这包含传递给 cpack_add_component() 的 DEPENDS 参数中的值。如果未传递 DEPENDS 参数，则这是一个空列表。
installationTypes: 组件所属的安装类型数组。这包含传递给 cpack_add_component() 的 INSTALL_TYPES 参数中的值。如果未传递 INSTALL_TYPES 参数，则这是一个空列表。
isDownloaded: 如果传递了 DOWNLOADED 给 cpack_add_component()，则为 True；否则为 False。
archiveFile: 传递给 cpack_add_component() 的 ARCHIVE_FILE 参数的存档文件名。如果未传递 ARCHIVE_FILE 参数，则为空字符串。

componentGroups

componentGroups 字段是一个对象，其中组件组名称作为键，描述组件组的对象作为值。组件组对象具有以下字段

名称: 组件组的名称。这始终与 componentGroups 对象中的键相同。
displayName: 传递给 cpack_add_component_group() 的 DISPLAY_NAME 字段的值。
描述: 传递给 cpack_add_component_group() 的 DESCRIPTION 字段的值。
parentGroup: 仅当将 PARENT_GROUP 传递给 cpack_add_component_group() 时存在。如果存在，此字段是包含组件组父组的字符串值。
isExpandedByDefault: 如果传递了 EXPANDED 给 cpack_add_component_group()，则为 True；否则为 False。
isBold: 如果传递了 BOLD_TITLE 给 cpack_add_component_group()，则为 True；否则为 False。
组件: 属于该组的直接组件名称数组（组件的 GROUP 设置为此组）。子组的组件不包括在内。
subgroups: 属于该组的子组件组的名称数组（这些组的 PARENT_GROUP 设置为此组）。

installationTypes

installationTypes 字段是一个对象，其中安装类型名称作为键，描述安装类型的对象作为值。安装类型对象具有以下字段

名称: 安装类型的名称。这始终与 installationTypes 对象中的键相同。
displayName: 传递给 cpack_add_install_type() 的 DISPLAY_NAME 字段的值。
索引: 安装类型在列表中的整数索引。

projects

projects 字段是一个对象数组，描述构成 CPack 项目的 CMake 项目。此字段中的值来自 CPACK_INSTALL_CMAKE_PROJECTS。在大多数情况下，这只会是一个项目。项目对象具有以下字段

projectName: 传递给 CPACK_INSTALL_CMAKE_PROJECTS 的项目名称。
component: 构成项目的组件或组件集的名称。
directory: CMake 项目的构建目录。这是包含 cmake_install.cmake 脚本的目录。
subDirectory: CPack 包内安装项目的子目录。

packageName

在 CPACK_PACKAGE_NAME 中给出的包名称。仅当设置了此选项时才存在。

packageVersion

在 CPACK_PACKAGE_VERSION 中给出的包版本。仅当设置了此选项时才存在。

packageDescriptionFile

在 CPACK_PACKAGE_DESCRIPTION_FILE 中给出的包描述文件。仅当设置了此选项时才存在。

packageDescriptionSummary

在 CPACK_PACKAGE_DESCRIPTION_SUMMARY 中给出的包描述摘要。仅当设置了此选项时才存在。

buildConfig

通过 cpack -C 选项传递给 CPack 的构建配置。仅当设置了此选项时才存在。

defaultDirectoryPermissions

在 CPACK_INSTALL_DEFAULT_DIRECTORY_PERMISSIONS 中给出的默认目录权限。仅当设置了此选项时才存在。

setDestdir

如果 CPACK_SET_DESTDIR 为 True，则为 True；否则为 False。

packagingInstallPrefix

在 CPACK_PACKAGING_INSTALL_PREFIX 中给出的安装前缀。仅当 CPACK_SET_DESTDIR 为 True 时才存在。

stripFiles

如果 CPACK_STRIP_FILES 为 True，则为 True；否则为 False。

warnOnAbsoluteInstallDestination

如果 CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION 为 True，则为 True；否则为 False。

errorOnAbsoluteInstallDestination

如果 CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION 为 True，则为 True；否则为 False。