CPack

为二进制安装程序和源代码包配置生成器。

简介

CPack 模块生成配置文件 CPackConfig.cmakeCPackSourceConfig.cmake。 它们旨在用于后续运行的 cpack 程序,在该程序中,它们指导安装程序和/或源代码包的生成。

根据 CMake 生成器,CPack 模块还可以添加两个新的构建目标,packagepackage_source。 有关详细信息,请参见下面的 打包目标 部分。

生成的二进制安装程序将包含已通过 CMake 的 install() 命令(以及已弃用的命令 install_files()install_programs()install_targets())安装的所有文件。 请注意,install() 命令的 DESTINATION 选项必须是相对路径; 否则,CPack 将忽略已安装的文件。

某些类型的二进制安装程序可以配置为允许用户选择要安装的各个应用程序组件。 有关更多详细信息,请参见 CPackComponent 模块。

源代码包(通过 CPackSourceConfig.cmake 配置,并由 CPack Archive Generator 生成)将包含项目目录中的所有源文件,但 CPACK_SOURCE_IGNORE_FILES 中指定的那些文件除外。

CPack 生成器

CPACK_GENERATOR 变量在不同的上下文中具有不同的含义。 在 CMakeLists.txt 文件中,CPACK_GENERATOR生成器列表:当运行 cpack 时,如果没有其他参数,它将遍历该列表,并为每个生成器生成一个包。 在 CPACK_PROJECT_CONFIG_FILE 中,CPACK_GENERATOR 是一个命名单个生成器的字符串。 如果您需要每个 cpack 生成器逻辑来控制其他 cpack 设置,那么您需要一个 CPACK_PROJECT_CONFIG_FILE。 如果设置了 CPACK_PROJECT_CONFIG_FILE,则会自动按每个生成器包含它。 它只需要包含覆盖。

工作原理如下

  • cpack 运行

  • 它包含 CPackConfig.cmake

  • 它遍历由 -G 命令行选项给出的生成器,或者如果没有指定这样的选项,则遍历由 CPACK_GENERATOR 变量给出的生成器列表,该变量在 CPackConfig.cmake 输入文件中设置。

  • 对于每个生成器,然后

这是关键:对于 CPackConfig.cmakeCPACK_GENERATOR 中列出的每个生成器,cpack 将在内部重置 CPACK_GENERATOR当前正在使用的生成器,然后包含 CPACK_PROJECT_CONFIG_FILE

有关可用生成器的列表,请参见 cpack-generators(7)

目标 package 和 package_source

如果使用 Makefile、Ninja 或 Xcode 生成器运行 CMake,则 include(CPack) 会生成目标 package。 这使得可以从 CMake、Make 或 Ninja 构建二进制安装程序:可以调用 cmake --build . --target packagemake packageninja package,而不是 cpack。 VS 生成器创建一个大写目标 PACKAGE

如果使用 Makefile 或 Ninja 生成器运行 CMake,则 include(CPack) 还会生成目标 package_source。 要构建源代码包,可以调用 cmake --build . --target package_sourcemake package_sourceninja package_source,而不是 cpack -G TGZ --config CPackSourceConfig.cmake

所有 CPack 生成器通用的变量

CMakeLists.txt 文件中包含此 CPack 模块之前,可以设置各种变量来自定义生成的安装程序。 最常用的变量是

CPACK_PACKAGE_NAME

包(或应用程序)的名称。 如果未指定,则默认为项目名称。

CPACK_PACKAGE_VENDOR

包供应商的名称。(例如,“Kitware”)。 默认为 “Humanity”。

CPACK_PACKAGE_DIRECTORY

CPack 在其中进行打包的目录。 如果未设置,则默认为(内部)构建目录。 可以在 CPack 配置文件中或从 cpack 命令行选项 -B 定义此变量。 如果设置,则命令行选项将覆盖配置文件中找到的值。

CPACK_PACKAGE_VERSION_MAJOR

包主版本。 此变量将始终设置,但其默认值取决于是否在顶级 CMakeLists.txt 文件中为 project() 命令提供了版本详细信息。 如果提供了版本详细信息,则默认值将为 CMAKE_PROJECT_VERSION_MAJOR。 如果未提供版本详细信息,则将假定默认版本为 0.1.1,从而导致 CPACK_PACKAGE_VERSION_MAJOR 的默认值为 0。

CPACK_PACKAGE_VERSION_MINOR

包次版本。 默认值基于是否在顶级 CMakeLists.txt 文件中为 project() 命令提供了版本详细信息来确定。 如果提供了版本详细信息,则默认值将为 CMAKE_PROJECT_VERSION_MINOR,但是如果未指定次版本组件,则 CPACK_PACKAGE_VERSION_MINOR 将保持未设置状态。 如果根本没有提供项目版本,则将假定默认版本为 0.1.1,从而导致 CPACK_PACKAGE_VERSION_MINOR 的默认值为 1。

CPACK_PACKAGE_VERSION_PATCH

包补丁版本。 默认值基于是否在顶级 CMakeLists.txt 文件中为 project() 命令提供了版本详细信息来确定。 如果提供了版本详细信息,则默认值将为 CMAKE_PROJECT_VERSION_PATCH,但是如果未指定补丁版本组件,则 CPACK_PACKAGE_VERSION_PATCH 将保持未设置状态。 如果根本没有提供项目版本,则将假定默认版本为 0.1.1,从而导致 CPACK_PACKAGE_VERSION_PATCH 的默认值为 1。

CPACK_PACKAGE_DESCRIPTION

项目描述,用于诸如 CPack 生成的 Windows 安装程序的介绍屏幕之类的地方。 如果未设置,则此变量的值从 CPACK_PACKAGE_DESCRIPTION_FILE 命名的文件中填充。

CPACK_PACKAGE_DESCRIPTION_FILE

用于描述项目的文本文件,当 CPACK_PACKAGE_DESCRIPTION 未显式设置时。 CPACK_PACKAGE_DESCRIPTION_FILE 的默认值指向内置模板文件 Templates/CPack.GenericDescription.txt

CPACK_PACKAGE_DESCRIPTION_SUMMARY

项目的简短描述(仅几个词)。 如果设置了 CMAKE_PROJECT_DESCRIPTION 变量,则将其用作默认值,否则默认值将是由 CMake 基于 CMAKE_PROJECT_NAME 生成的字符串。

CPACK_PACKAGE_HOMEPAGE_URL

项目主页 URL。 默认值取自 CMAKE_PROJECT_HOMEPAGE_URL 变量,该变量由顶级 project() 命令设置,否则,如果未向 project() 提供 URL,则默认值为空。

CPACK_PACKAGE_FILE_NAME

要生成的软件包文件的名称,不包括扩展名。 例如,cmake-2.6.1-Linux-i686。 默认值为

${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CPACK_SYSTEM_NAME}
CPACK_PACKAGE_INSTALL_DIRECTORY

目标系统上的安装目录。 某些 CPack 生成器(如 NSIS)可以使用它在安装前缀下创建安装目录,例如 “CMake 2.5”。 所有已安装的元素都将放在此目录中。

CPACK_PACKAGE_ICON

将在安装程序内部显示的品牌形象(由 GUI 安装程序使用)。

CPACK_PACKAGE_CHECKSUM

在 3.7 版本中添加。

将用于生成包含包校验和的附加文件的算法。 输出文件名将是

${CPACK_PACKAGE_FILE_NAME}.${CPACK_PACKAGE_CHECKSUM}

支持的算法是 string(<HASH>) 命令列出的那些算法。

CPACK_PROJECT_CONFIG_FILE

CPack-time 项目 CPack 配置文件。 在 cpack 时间,每次在 CPack 将 CPACK_GENERATOR 设置为正在使用的实际生成器后,都会包含此文件。 它允许在 cpack 时间按生成器设置 CPACK_* 变量。

CPACK_RESOURCE_FILE_LICENSE

要嵌入到安装程序中的许可证。 它通常由生成的安装程序向用户显示(通常带有显式的“接受”按钮,对于图形安装程序),然后在安装之前显示。 此许可证文件未添加到已安装的文件中,但由某些 CPack 生成器(如 NSIS)使用。 如果要使用 UTF-8 字符,则文件需要以 UTF-8 BOM 编码。 如果要将许可证文件(可能与此文件相同)与项目一起安装,则必须在 CMakeLists.txt 中添加适当的 CMake install() 命令。

CPACK_RESOURCE_FILE_README

要嵌入到安装程序中的 ReadMe 文件。 它通常在安装期间详细描述项目的目的。 并非所有 CPack 生成器都使用此文件。

CPACK_RESOURCE_FILE_WELCOME

要嵌入到安装程序中的欢迎文件。 它欢迎用户使用此安装程序。 通常在 Windows 和 Mac OS X 上的图形安装程序中使用。

CPACK_MONOLITHIC_INSTALL

禁用基于组件的安装机制。 设置后,组件规范将被忽略,所有已安装的项目都将放入单个 “MONOLITHIC” 包中。 某些 CPack 生成器默认情况下执行单体打包,并且可以通过将 CPACK_<GENNAME>_COMPONENT_INSTALL 设置为 TRUE 来要求执行组件打包。

CPACK_GENERATOR

要使用的 CPack 生成器列表。 如果未指定,CPack 将创建一个选项集,该选项集遵循命名模式 CPACK_BINARY_<GENNAME>(例如 CPACK_BINARY_NSIS),允许用户启用/禁用单个生成器。 如果在 cpack 命令行上给出了 -G 选项,它将覆盖此变量和任何 CPACK_BINARY_<GENNAME> 选项。

CPACK_OUTPUT_CONFIG_FILE

CPack 二进制配置文件的名称。 此文件是由 CPack 模块为二进制安装程序生成的 CPack 配置。 默认为 CPackConfig.cmake

CPACK_PACKAGE_EXECUTABLES

列出每个可执行文件和关联的文本标签,用于创建“开始”菜单快捷方式。 例如,将其设置为列表 ccmake;CMake 将创建一个名为 “CMake” 的快捷方式,该快捷方式将执行已安装的可执行文件 ccmake。 并非所有 CPack 生成器都使用它(至少 NSIS、Inno Setup 和 WIX 使用)。

CPACK_STRIP_FILES

要剥离的文件列表。 从 CMake 2.6.0 开始,CPACK_STRIP_FILES 将是一个布尔变量,它启用剥离所有文件(文件列表在 CMake 中评估为 TRUE,因此此更改是兼容的)。

CPACK_VERBATIM_VARIABLES

在 3.4 版本中添加。

如果设置为 TRUE,则以 CPACK_ 为前缀的变量的值将在写入配置文件之前进行转义,以便 cpack 程序接收到的值与指定的完全相同。 否则,诸如引号和反斜杠之类的字符可能会导致解析错误或更改 cpack 程序接收的值。 为了向后兼容,默认为 FALSE

CPACK_THREADS

在 3.20 版本中添加。

执行并行操作(例如压缩安装程序包)时要使用的线程数。

CPack 生成器(如 Debian 或 Archive)使用的一些压缩方法可能会利用多个 CPU 核心来加速压缩。 可以设置 CPACK_THREADS 来指定将用于压缩的线程数。

可以使用正整数来指定确切的所需线程数。

当给定负整数时,CPack 将使用绝对值作为上限,但可能会根据可用的硬件并发性选择较低的值。

给定 0,CPack 将尝试使用所有可用的 CPU 核心。

默认情况下,CPACK_THREADS 设置为 1

以下压缩方法可能会利用多个核心

xz

如果 CMake 是使用支持并行压缩的 liblzma 构建的,则支持。

在 3.21 版本中添加: cmake.org 上提供的官方 CMake 二进制文件现在随附支持并行压缩的 liblzma。 较旧版本不支持。

zstd

在 3.24 版本中添加。

如果 CMake 是使用 libarchive 3.6 或更高版本构建的,则支持。 cmake.org 上提供的官方 CMake 二进制文件支持它。

其他压缩方法会忽略此值,并且仅使用一个线程。

源代码包生成器的变量

以下 CPack 变量特定于源代码包,不会影响二进制包

CPACK_SOURCE_PACKAGE_FILE_NAME

源代码包的名称。 例如 cmake-2.6.1

CPACK_SOURCE_STRIP_FILES

源代码树中要剥离的文件列表。 从 CMake 2.6.0 开始,CPACK_SOURCE_STRIP_FILES 将是一个布尔变量,它启用剥离所有文件(文件列表在 CMake 中评估为 TRUE,因此此更改是兼容的)。

CPACK_SOURCE_GENERATOR

用于源代码包的生成器列表。 与 CPACK_GENERATOR 一样,如果未指定,则 CPack 将创建一组选项(例如 CPACK_SOURCE_ZIP),允许用户选择将生成哪些包。

CPACK_SOURCE_OUTPUT_CONFIG_FILE

CPack 源代码配置文件的名称。 此文件是由 CPack 模块为源代码安装程序生成的 CPack 配置。 默认为 CPackSourceConfig.cmake

CPACK_SOURCE_IGNORE_FILES

源代码树中在构建源代码包时不会打包的文件模式。 这是一个正则表达式模式列表(必须正确转义),例如 /CVS/;/\\.svn/;\\.swp$;\\.#;/#;.*~;cscope.*

高级用法的变量

以下变量用于 CPack 的高级用法

CPACK_CMAKE_GENERATOR

如果项目是 CMake 项目,则应使用哪个 CMake 生成器。 默认为 CMAKE_GENERATOR 的值。 很少有用户想要更改此设置。

CPACK_INSTALL_CMAKE_PROJECTS

指定要安装的项目的四个值列表。 这四个值是:构建目录、项目名称、项目组件、目录。 如果省略,CPack 将构建一个安装所有内容的安装程序。

CPACK_SYSTEM_NAME

系统名称,默认为 CMAKE_SYSTEM_NAME 的值,但在 Windows 上,它将是 win32win64

CPACK_PACKAGE_VERSION

包完整版本,内部使用。 默认情况下,它是从 CPACK_PACKAGE_VERSION_MAJORCPACK_PACKAGE_VERSION_MINORCPACK_PACKAGE_VERSION_PATCH 构建的。

CPACK_TOPLEVEL_TAG

已安装文件的目录。

CPACK_INSTALL_COMMANDS

用于安装组件的额外命令。 环境变量 CMAKE_INSTALL_PREFIX 在执行期间设置为临时安装目录。

CPACK_INSTALL_SCRIPTS

在 3.16 版本中添加。

CPack 在其本地暂存安装期间执行的额外 CMake 脚本。 它们在安装要打包的文件之前执行。 这些脚本不是由独立安装调用的(例如:make install)。 对于每个脚本,将设置以下变量:CMAKE_CURRENT_SOURCE_DIRCMAKE_CURRENT_BINARY_DIRCMAKE_INSTALL_PREFIX(设置为暂存安装目录)。 出于历史原因,支持单数形式 CMAKE_INSTALL_SCRIPT 作为替代变量,但是如果设置了 CMAKE_INSTALL_SCRIPTS,则其值将被忽略,并且将发出警告。

另请参阅 CPACK_PRE_BUILD_SCRIPTSCPACK_POST_BUILD_SCRIPTS,它们可用于指定在打包过程后期执行的脚本。

CPACK_PRE_BUILD_SCRIPTS

在版本 3.19 中添加。

在 CPack 将要打包的文件安装到暂存目录之后,以及从这些文件生成软件包之前要执行的 CMake 脚本列表。另请参阅 CPACK_INSTALL_SCRIPTSCPACK_POST_BUILD_SCRIPTS

CPACK_POST_BUILD_SCRIPTS

在版本 3.19 中添加。

在 CPack 生成结果软件包之后,以及将它们复制回构建目录之前要执行的 CMake 脚本列表。另请参阅 CPACK_INSTALL_SCRIPTSCPACK_PRE_BUILD_SCRIPTSCPACK_PACKAGE_FILES

CPACK_PACKAGE_FILES

在版本 3.19 中添加。

暂存目录中创建的软件包文件列表,每个文件都以完整的绝对路径提供。此变量由 CPack 在调用 CPACK_POST_BUILD_SCRIPTS 中列出的后构建脚本之前填充。它是后构建脚本了解要操作的软件包文件集的首选方式。项目不应尝试自行设置此变量。

CPACK_INSTALLED_DIRECTORIES

要安装的额外目录。

CPACK_PACKAGE_INSTALL_REGISTRY_KEY

安装此项目时使用的注册表项。这仅供 Windows 的安装程序使用。默认值基于安装目录。

要创建的桌面链接列表。每个桌面链接都需要一个相应的开始菜单快捷方式,如 CPACK_PACKAGE_EXECUTABLES 创建的快捷方式。

CPACK_BINARY_<GENNAME>

CPack 为二进制生成器生成的选项。CPack.cmake 模块生成(当 CPACK_GENERATOR 未设置时)一组 CMake 选项(请参阅 CMake option() 命令),这些选项可用于选择在构建 package 目标或在不使用 -G 选项的情况下运行 cpack 时要使用的 CPack 生成器。

CPACK_READELF_EXECUTABLE

在版本 3.25 中添加。

指定 CPack 使用的 readelf 可执行文件路径。默认值将取自 CMAKE_READELF 变量(如果已设置),该变量可能会在启用语言时由 CMake 填充。如果未设置 CMAKE_READELF,CPack 将在需要时使用 find_program() 来确定 readelf 路径。

CPACK_OBJCOPY_EXECUTABLE

在版本 3.25 中添加。

指定 CPack 使用的 objcopy 可执行文件路径。默认值将取自 CMAKE_OBJCOPY 变量(如果已设置),该变量可能会在启用语言时由 CMake 填充。如果未设置 CMAKE_OBJCOPY,CPack 将在需要时使用 find_program() 来确定 objcopy 路径。

CPACK_OBJDUMP_EXECUTABLE

在版本 3.25 中添加。

指定 CPack 使用的 objdump 可执行文件路径。默认值将取自 CMAKE_OBJDUMP 变量,该变量可能会在启用语言时由 CMake 填充。如果未设置 CMAKE_OBJDUMP,CPack 将在需要时使用 find_program() 来确定 objdump 路径。