CPack¶
为二进制安装程序和源代码包配置生成器。
简介¶
CPack 模块生成配置文件 CPackConfig.cmake
和 CPackSourceConfig.cmake
。 它们旨在用于后续运行的 cpack
程序,在该程序中,它们指导安装程序和/或源代码包的生成。
根据 CMake 生成器,CPack 模块还可以添加两个新的构建目标,package
和 package_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
输入文件中设置。对于每个生成器,然后
将
CPACK_GENERATOR
设置为当前正在迭代的生成器为该生成器生成包
这是关键:对于 CPackConfig.cmake
中 CPACK_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 package
或 make package
或 ninja package
,而不是 cpack
。 VS 生成器创建一个大写目标 PACKAGE
。
如果使用 Makefile 或 Ninja 生成器运行 CMake,则 include(CPack)
还会生成目标 package_source
。 要构建源代码包,可以调用 cmake --build . --target package_source
、make package_source
或 ninja 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
中添加适当的 CMakeinstall()
命令。
- 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 上,它将是win32
或win64
。
- CPACK_PACKAGE_VERSION¶
包完整版本,内部使用。 默认情况下,它是从
CPACK_PACKAGE_VERSION_MAJOR
、CPACK_PACKAGE_VERSION_MINOR
和CPACK_PACKAGE_VERSION_PATCH
构建的。
- CPACK_TOPLEVEL_TAG¶
已安装文件的目录。
- CPACK_INSTALL_COMMANDS¶
用于安装组件的额外命令。 环境变量
CMAKE_INSTALL_PREFIX
在执行期间设置为临时安装目录。
- CPACK_INSTALL_SCRIPTS¶
在 3.16 版本中添加。
CPack 在其本地暂存安装期间执行的额外 CMake 脚本。 它们在安装要打包的文件之前执行。 这些脚本不是由独立安装调用的(例如:
make install
)。 对于每个脚本,将设置以下变量:CMAKE_CURRENT_SOURCE_DIR
,CMAKE_CURRENT_BINARY_DIR
和CMAKE_INSTALL_PREFIX
(设置为暂存安装目录)。 出于历史原因,支持单数形式CMAKE_INSTALL_SCRIPT
作为替代变量,但是如果设置了CMAKE_INSTALL_SCRIPTS
,则其值将被忽略,并且将发出警告。另请参阅
CPACK_PRE_BUILD_SCRIPTS
和CPACK_POST_BUILD_SCRIPTS
,它们可用于指定在打包过程后期执行的脚本。
- CPACK_PRE_BUILD_SCRIPTS¶
在版本 3.19 中添加。
在 CPack 将要打包的文件安装到暂存目录之后,以及从这些文件生成软件包之前要执行的 CMake 脚本列表。另请参阅
CPACK_INSTALL_SCRIPTS
和CPACK_POST_BUILD_SCRIPTS
。
- CPACK_POST_BUILD_SCRIPTS¶
在版本 3.19 中添加。
在 CPack 生成结果软件包之后,以及将它们复制回构建目录之前要执行的 CMake 脚本列表。另请参阅
CPACK_INSTALL_SCRIPTS
、CPACK_PRE_BUILD_SCRIPTS
和CPACK_PACKAGE_FILES
。
- CPACK_PACKAGE_FILES¶
在版本 3.19 中添加。
暂存目录中创建的软件包文件列表,每个文件都以完整的绝对路径提供。此变量由 CPack 在调用
CPACK_POST_BUILD_SCRIPTS
中列出的后构建脚本之前填充。它是后构建脚本了解要操作的软件包文件集的首选方式。项目不应尝试自行设置此变量。
- CPACK_INSTALLED_DIRECTORIES¶
要安装的额外目录。
- CPACK_PACKAGE_INSTALL_REGISTRY_KEY¶
安装此项目时使用的注册表项。这仅供 Windows 的安装程序使用。默认值基于安装目录。
- CPACK_CREATE_DESKTOP_LINKS¶
要创建的桌面链接列表。每个桌面链接都需要一个相应的开始菜单快捷方式,如
CPACK_PACKAGE_EXECUTABLES
创建的快捷方式。
- CPACK_BINARY_<GENNAME>¶
CPack 为二进制生成器生成的选项。
CPack.cmake
模块生成(当CPACK_GENERATOR
未设置时)一组 CMake 选项(请参阅 CMakeoption()
命令),这些选项可用于选择在构建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
路径。