CPack 外部生成器¶

添加于版本 3.13。

CPack 提供了许多生成器，用于为各种平台和打包系统创建软件包。CMake/CPack 的目标是成为构建和打包软件项目的完整端到端解决方案。然而，由于技术限制或需要使用某些工具的策略，可能并不总是能够使用 CPack 完成整个打包过程。因此，CPack 提供了“External”生成器，它允许外部打包软件利用 CPack 提供的一些功能，例如组件安装和依赖关系图。

与外部打包工具集成¶

CPack 外部生成器生成一个 .json 文件，其中包含 CPack 内部元数据，该元数据为外部软件提供关于如何打包软件的信息。外部打包软件本身可以调用 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 字段是一个对象，其中组件名称作为键，描述组件的对象作为值。组件对象具有以下字段

name: 组件的名称。这始终与 components 对象中的键相同。
displayName: 传递给 cpack_add_component() 的 DISPLAY_NAME 字段的值。
description: 传递给 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: 使用 ARCHIVE_FILE 参数传递给 cpack_add_component() 的归档文件名。如果未传递 ARCHIVE_FILE 参数，则这是一个空字符串。

componentGroups

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

name: 组件组的名称。这始终与 componentGroups 对象中的键相同。
displayName: 传递给 cpack_add_component_group() 的 DISPLAY_NAME 字段的值。
description: 传递给 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。
components: 作为组的直接成员的组件名称数组（将此组作为其 GROUP 的组件）。不包括子组的组件。
subgroups: 作为组的子组的组件组名称数组（将此组作为其 PARENT_GROUP 的组）。

installationTypes

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

name: 安装类型的名称。这始终与 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。