CPack 完整使用指南（CMake 官方打包工具）

CPack 是 CMake 内置的跨平台项目打包工具，依托 CMake 构建体系，可将编译完成的项目一键打包为 ZIP、TGZ、DEB、RPM、NSIS、WiX、STGZ 等主流安装包/压缩包格式，跨 Linux、Windows、macOS 多平台使用。本文基于基础用法做全面扩展，涵盖配置、多格式打包、进阶参数、实战案例、排错方案。

一、基本概念

运行依赖
CPack 并非独立工具，强依赖 CMake 项目上下文，读取 CMakeLists.txt 中 install() 安装规则、CPack 系列变量生成打包清单，最终组装安装包。
工作流程
CMake 配置项目 → 编译项目 → CPack 读取安装规则 & 打包配置 → 生成对应格式安装包。
核心组成
- include(CPack)：启用 CPack 模块，自动生成打包脚本；
- install()：定义哪些文件/目录/程序需要被打包；
- CPACK_* 系列变量：控制包名、版本、格式、作者、平台、依赖等元信息。

二、CMakeLists.txt 中 CPack 核心配置

2.1 引入 CPack 模块（必写）

所有 CPack 功能都需要先加载内置模块，建议写在 CMakeLists.txt 文件末尾（所有 install 规则之后）。

# 加载 CPack 打包模块，启用打包功能
include(CPack)

2.2 通用基础信息配置（全格式通用变量）

这类变量作用于所有打包生成器，定义软件基础元数据，为必填常用项。

# 1. 软件包名称（默认包名前缀）
set(CPACK_PACKAGE_NAME "MyProject")
# 2. 软件版本号
set(CPACK_PACKAGE_VERSION "1.0.0")
# 3. 简短描述（包管理器展示）
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "CMake + CPack demo project")
# 4. 开发商/作者/公司
set(CPACK_PACKAGE_VENDOR "Demo Corp")
# 5. 开源协议
set(CPACK_PACKAGE_LICENSE "MIT")
# 6. 项目官网地址
set(CPACK_PACKAGE_HOMEPAGE_URL "https://github.com/demo/cpack-demo")

# 可选扩展变量
set(CPACK_PACKAGE_DESCRIPTION "Complete description for my CPack project.") # 详细描述
set(CPACK_PACKAGE_CONTACT "admin@demo.com") # 联系邮箱

2.3 指定打包生成器（CPACK_GENERATOR）

通过 CPACK_GENERATOR 选择打包格式，支持单个/多个格式同时打包，主流生成器如下：

# 单个格式：仅生成 ZIP 压缩包
set(CPACK_GENERATOR "ZIP")

# 多个格式：同时生成 ZIP + TGZ 两种压缩包（用分号分隔）
# set(CPACK_GENERATOR "ZIP;TGZ")

# Linux 常用：DEB(Debian/Ubuntu) + RPM(CentOS/RHEL)
# set(CPACK_GENERATOR "DEB;RPM")

# Windows 常用：NSIS( exe 安装包 ) + ZIP
# set(CPACK_GENERATOR "NSIS;ZIP")

主流生成器对照表

生成器名称	对应格式	适用平台
ZIP	标准 zip 压缩包	全平台
TGZ / TZ	tar.gz 压缩包	Linux / macOS
DEB	deb 安装包	Debian、Ubuntu、Deepin 等 Debian 系 Linux
RPM	rpm 安装包	CentOS、Rocky、Fedora 等 RHEL 系 Linux
NSIS	Windows exe 图形安装程序	Windows
WiX	Windows msi 安装包	Windows
STGZ	自解压 shell 脚本	Linux

2.4 核心：install 安装规则（决定打包内容）

CPack 只会打包 install() 指令声明的文件/程序，没有 install 规则则打包为空包。

2.4.1 安装可执行程序

# 编译目标 MyExecutable 安装到系统 bin 目录
install(TARGETS MyExecutable
  RUNTIME DESTINATION bin       # 可执行文件路径
  LIBRARY DESTINATION lib       # 动态库路径
  ARCHIVE DESTINATION lib       # 静态库路径
)

2.4.2 安装头文件、配置文件、资源文件

# 批量安装头文件
install(DIRECTORY include/ DESTINATION include)

# 单独安装配置文件
install(FILES config.ini README.md DESTINATION share/MyProject)

2.4.3 安装整个目录（递归拷贝）

# 拷贝 res 资源目录到安装目录
install(DIRECTORY res/ DESTINATION share/MyProject/res)

三、完整编译 + 打包流程（命令行）

3.1 标准流程（跨平台通用）

# 1. 创建编译目录
mkdir build && cd build

# 2. CMake 配置项目（生成构建文件 + CPack 打包脚本）
cmake ..

# 3. 编译项目（必执行，否则无可打包文件）
make          # Linux/macOS
# cmake --build .  # 跨平台通用编译命令（Windows/Linux 都可用）

# 4. 执行 CPack 生成安装包
cpack

3.2 命令行临时指定打包格式（优先级高于 CMake 配置）

无需修改 CMakeLists.txt，通过 -G 临时指定生成器，覆盖配置文件中的 CPACK_GENERATOR：

# 仅生成 ZIP 包
cpack -G ZIP

# 同时生成 DEB 和 TGZ 包
cpack -G "DEB;TGZ"

3.3 常用 CPack 命令行参数

cpack -V        # 详细日志输出（排查打包错误首选）
cpack --verbose # 等同于 -V，打印完整打包过程
cpack -C Release # 指定打包 Release 版本文件
cpack -D CPACK_PACKAGE_VERSION=2.0.0 # 临时覆盖版本号

四、高级配置（分平台/分格式专属配置）

4.1 自定义输出包名

默认包名：项目名-版本-系统名，可手动自定义文件名：

# 自定义包名：MyProject-1.0.0-Linux-x86_64
set(CPACK_PACKAGE_FILE_NAME 
  "${CPACK_PACKAGE_NAME}-${CPACK_PACKAGE_VERSION}-${CMAKE_SYSTEM_NAME}-${CMAKE_SYSTEM_PROCESSOR}"
)

4.2 Linux DEB 包专属配置（Debian/Ubuntu）

DEB 包需要维护人、软件依赖、分类等 Debian 规范字段：

# 包维护人（格式：姓名 <邮箱>，DEB 必选）
set(CPACK_DEBIAN_PACKAGE_MAINTAINER "Demo User <user@demo.com>")
# 运行依赖（多个依赖用逗号分隔）
set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.14), libstdc++6")
# 软件分类
set(CPACK_DEBIAN_PACKAGE_SECTION "utils")
# 优先级
set(CPACK_DEBIAN_PACKAGE_PRIORITY "optional")

4.3 Linux RPM 包专属配置（CentOS/RHEL）

# RPM 运行依赖
set(CPACK_RPM_PACKAGE_REQUIRES "glibc >= 2.14, libstdc++")
# RPM 软件分组
set(CPACK_RPM_PACKAGE_GROUP "Development/Tools")
# RPM 发布版本号
set(CPACK_RPM_PACKAGE_RELEASE "1")

4.4 Windows NSIS 安装包专属配置

生成 Windows 可视化 exe 安装程序，支持安装界面、默认路径、卸载功能：

# NSIS 默认安装路径
set(CPACK_NSIS_INSTALL_ROOT "$PROGRAMFILES")
# 桌面快捷方式
set(CPACK_NSIS_CREATE_ICONS_EXTRA "CreateShortCut '$DESKTOP\\MyProject.lnk' '$INSTDIR\\bin\\MyExecutable.exe'")
# 开始菜单名称
set(CPACK_NSIS_PACKAGE_NAME "MyProject Tool")

4.5 多项目联合打包

若工程包含多个 CMake 子项目，使用如下配置统一打包：

set(CPACK_INSTALL_CMAKE_PROJECTS 
  "${CMAKE_BINARY_DIR};${CPACK_PACKAGE_NAME};ALL;/"
)

五、依赖安装（各平台打包前置环境）

不同打包格式需要系统预装对应工具，缺少则打包报错。

5.1 Debian / Ubuntu（生成 DEB 包）

sudo apt update
sudo apt install dpkg-dev binutils

5.2 CentOS / Rocky（生成 RPM 包）

sudo yum install rpm-build rpmdevtools

5.3 Windows（生成 NSIS 安装包）

安装 NSIS；
将 NSIS 安装目录加入系统环境变量。

5.4 通用压缩包（ZIP/TGZ）

绝大多数系统自带对应工具，一般无需额外安装。

六、常见问题 & 排错方案

6.1 打包后文件为空

原因：未编写 install() 安装规则，CPack 无内容可打包。
解决：补充 install(TARGETS / FILES / DIRECTORY) 指令。

6.2 执行 cpack 提示「找不到对应工具」

现象：error: Cannot find dpkg-deb / error: Cannot find rpmbuild
解决：参考第五节安装对应平台的打包依赖工具。

6.3 打包过程报错，无明确提示

解决1：使用 cpack -V 输出详细日志，定位错误；
解决2：查看编译目录下日志文件：CMakeFiles/CPackErrorLog.txt、CPackLog-*.log。

6.4 DEB/RPM 安装时提示依赖缺失

原因：未配置 CPACK_DEBIAN_PACKAGE_DEPENDS / CPACK_RPM_PACKAGE_REQUIRES。
解决：根据程序运行库，补充依赖字段。

6.5 Windows NSIS 无法生成 exe

原因：NSIS 未安装，或未配置系统环境变量。
解决：重装 NSIS 并配置环境变量，重启终端重试。

七、完整最小示例（可直接运行）

CMakeLists.txt 完整代码

cmake_minimum_required(VERSION 3.10)
project(MyProject)

# 设置 C++ 标准
set(CMAKE_CXX_STANDARD 11)

# 编译可执行文件
add_executable(MyExecutable main.cpp)

# ========== 安装规则 ==========
install(TARGETS MyExecutable DESTINATION bin)
install(FILES README.md DESTINATION share/MyProject)

# ========== CPack 打包配置 ==========
set(CPACK_PACKAGE_NAME "MyProject")
set(CPACK_PACKAGE_VERSION "1.0.0")
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "CPack Demo Application")
set(CPACK_PACKAGE_VENDOR "Demo Company")
set(CPACK_PACKAGE_LICENSE "MIT")

# 指定打包格式
set(CPACK_GENERATOR "ZIP;TGZ")

# Linux DEB 专属配置
set(CPACK_DEBIAN_PACKAGE_MAINTAINER "Test User <test@demo.com>")

# 启用 CPack 模块（放在最后）
include(CPack)

执行命令

mkdir build && cd build
cmake ..
make
cpack

执行完成后，build 目录下会生成 .zip 和 .tar.gz 两个安装包。

八、总结

核心流程：CMake 配置 → 编译 → cpack 打包，install() 是打包内容的核心；
配置优先级：命令行 cpack -G > CMake 变量 CPACK_GENERATOR；
跨平台适配：通用变量全平台生效，DEB/RPM/NSIS 需搭配对应专属变量；
排错技巧：优先使用 cpack -V 和 CPackErrorLog.txt 定位问题，提前安装系统依赖。

CPack 深度融合 CMake 生态，是跨平台软件分发、发布安装包的标准方案，适合 C/C++ 项目自动化打包发布。

CPack 完整使用指南（CMake 官方打包工具）