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 命令行选项指定的生成器,如果未指定此类选项,则遍历 CPackConfig.cmake 输入文件中设置的 CPACK_GENERATOR 变量中指定的生成器列表。

  • 对于每个生成器,它然后

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

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

目标 package 和 package_source

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

如果 CMake 使用 Makefile 或 Ninja 生成器运行,则 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

要嵌入到安装程序中的自述文件。它通常在安装过程中详细描述项目的目的。并非所有 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 路径。