CPack 外部生成器

在 3.13 版本加入.

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

与外部打包工具集成

CPack External 生成器生成一个包含 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 对象中的键相同。

显示名称

传递给 cpack_add_component 的 DISPLAY_NAME 字段的值。

描述

DESCRIPTION 字段的值传递给 cpack_add_component()。

是隐藏的

如果 HIDDEN 被传递给 cpack_add_component 则为真，否则为假。

是必需的

如果 REQUIRED 被传递给 cpack_add_component 则为真，否则为假。

isDisabledByDefault

如果 DISABLED 被传递给 cpack_add_component 则为真，否则为假。

组

仅在将 GROUP 传递给 cpack_add_component() 时出现。如果是这样，该字段是一个包含组件组的字符串值。

依赖关系

组件所依赖的组件数组。这包含传递给 cpack_add_component() 的 DEPENDS 参数中的值。如果未传递“DEPENDS”参数，则这是一个空列表。

安装类型

组件所属的一组安装类型。这包含传递给 cpack_add_component 的 INSTALL_TYPES 参数中的值。如果没有传递 INSTALL_TYPES 参数，这是一个空列表。

isDownloaded

如果 DOWNLOADED 被传递给 cpack_add_component 则为真，否则为假。

存档文件

存档文件的名称与 ARCHIVE_FILE 参数一起传递给 cpack_add_component()。如果没有传递 ARCHIVE_FILE 参数，这是一个空字符串。

组件组

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

名字

组件组的名称。这始终与 componentGroups 对象中的键相同。

显示名称

传递给 cpack_add_component_group 的 DISPLAY_NAME 字段的值。

描述

传递给 cpack_add_component_group 的 DESCRIPTION 字段的值。

父组

只有在 PARENT_GROUP 被传递给 cpack_add_component_group() 时才会出现。如果是，则此字段是一个字符串值，其中包含组件组的父组。

isExpandedByDefault

如果 EXPANDED 被传递给 cpack_add_component_group() 则为真，否则为假。

是粗体

如果 BOLD_TITLE 被传递给 cpack_add_component_group 则为真，否则为假。

组件

作为组的直接成员的组件名称数组（将此组作为其“GROUP”的组件）。不包括子组的组件。

子组

作为组子组的组件组名称的数组（将此组作为其 PARENT_GROUP 的组）。

安装类型

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

名字

安装类型的名称。这始终与“installationTypes”对象中的键相同。

显示名称

传递给 cpack_add_install_type 的 DISPLAY_NAME 字段的值。

索引

列表中安装类型的整数索引。

项目

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

项目名称

传递给 CPACK_INSTALL_CMAKE_PROJECTS 的项目名称。

组件

组成项目的组件或组件集的名称。

目录

CMake 项目的构建目录。这是包含 cmake_install.cmake 脚本的目录。

子目录

将项目安装到 CPack 包内的子目录。

包名

CPACK_PACKAGE_NAME 中给出的包名称。仅在设置此选项时出现。

包版本

CPACK_PACKAGE_VERSION 中给出的包版本。仅在设置此选项时出现。

packageDescriptionFile

CPACK_PACKAGE_DESCRIPTION_FILE 中给出的包描述文件。仅在设置此选项时出现。

packageDescriptionSummary

CPACK_PACKAGE_DESCRIPTION_SUMMARY 中给出的包描述摘要。仅在设置此选项时出现。

buildConfig

使用 cpack -C 选项提供给 CPack 的构建配置。仅在设置此选项时出现。

默认目录权限

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

setDestdir

如果 CPACK_SET_DESTDIR 为真，则为真，否则为假。

packagingInstallPrefix

CPACK_PACKAGING_INSTALL_PREFIX 中给出的安装前缀。仅当 CPACK_SET_DESTDIR 为真时出现。

stripFiles

如果 CPACK_STRIP_FILES 为真，则为真，否则为假。

warnOnAbsoluteInstallDestination

如果 CPACK_WARN_ON_ABSOLUTE_INSTALL_DESTINATION 为真，则为真，否则为假。

errorOnAbsoluteInstallDestination

如果 CPACK_ERROR_ON_ABSOLUTE_INSTALL_DESTINATION 为真，则为真，否则为假。

特定于 CPack 外部生成器的变量

CPACK_EXTERNAL_REQUESTED_VERSIONS

此变量用于请求特定版本的 CPack 外部生成器。它是 major.minor 值的列表，用分号分隔。

如果此变量设置为非空值，CPack External 生成器将遍历列表中的每个项目以搜索它知道如何生成的版本。请求的版本应按客户端软件的降序顺序列出，因为将生成列表中的第一个匹配版本。

如果生成器的主版本与请求的主版本完全匹配，并且其次版本大于或等于请求的次版本，则生成器知道如何生成版本。例如，如果 CPACK_EXTERNAL_REQUESTED_VERSIONS 包含 1.0，并且 CPack External 生成器知道如何生成 1.1，它将生成 1.1。如果生成器不知道如何生成列表中的版本，它会跳过该版本并查看下一个版本。如果它不知道如何生成任何请求的版本，则会抛出错误。

如果此变量未设置或为空，则 CPack 外部生成器将生成它知道如何生成的最高主要和次要版本。

如果在 CPACK_EXTERNAL_REQUESTED_VERSIONS 中遇到无效版本（与 major.minor 不匹配的版本，其中 major 和 minor 是整数），它将被忽略。

CPACK_EXTERNAL_ENABLE_STAGING

可以将此变量设置为 true 以启用可选安装到临时暂存区域，然后可以由外部打包工具拾取和打包。 CPack 用于当前打包任务的顶级目录包含在 CPACK_TOPLEVEL_DIRECTORY 中。在启动打包之前，它会在每次运行时自动清理，并可用于外部打包工具所需的自定义临时文件。它还包含暂存区“CPACK_TEMPORARY_DIRECTORY”，启用暂存后，CPack 会在其中执行安装。

CPACK_EXTERNAL_PACKAGE_SCRIPT

此变量可以选择指定要作为 CPack 调用的一部分运行的 CMake 脚本文件的完整路径。它在（可选）暂存发生后调用，并可能运行外部打包工具。该脚本可以访问 CPack 配置文件定义的变量。

CPACK_EXTERNAL_BUILT_PACKAGES

在 3.19 版本加入.

CPACK_EXTERNAL_PACKAGE_SCRIPT 脚本可以将此列表变量设置为生成的包文件的完整路径。 CPack 会将这些文件从暂存目录复制回顶级构建目录，如果设置了 CPACK_PACKAGE_CHECKSUM，则可能会生成校验和文件。