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
命令行选项指定的生成器,如果未指定此类选项,则遍历CPackConfig.cmake
输入文件中设置的CPACK_GENERATOR
变量中指定的生成器列表。对于每个生成器,它然后
将
CPACK_GENERATOR
设置为当前正在迭代的生成器为该生成器生成包
这是关键:对于 CPackConfig.cmake
中 CPACK_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 package
或 make package
或 ninja package
,而不是 cpack
。VS 生成器创建大写目标 PACKAGE
。
如果 CMake 使用 Makefile 或 Ninja 生成器运行,则 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¶
要嵌入到安装程序中的自述文件。它通常在安装过程中详细描述项目的目的。并非所有 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
路径。