C++ CMake打包指南：CPack生成安装包详解

CPack生成安装包前必须设置PROJECT_NAME和PROJECT_VERSION，否则默认版本0.0.0导致包名不可用；需用install(TARGETS...)显式声明可执行文件及依赖库；Linux下需设CPACK_GENERATOR为"TGZ"以稳定生成.tar.gz；Windows NSIS需配置显示名、图标、许可证等且路径须用正斜杠。

CPack 生成安装包前必须设置 PROJECT_NAME 和 PROJECT_VERSION

CPack 不会自动读取 CMakeLists.txt 中的 project() 指令以外的信息，如果漏写或只写了 project(MyApp) 而没带版本，cpack 会默认用 0.0.0，导致生成的安装包名变成 MyApp-0.0.0-Linux.sh 这类不可用名称。

正确写法是：

project(MyApp VERSION 1.2.3 LANGUAGES CXX)

这样 CPack 才能从 CMAKE_PROJECT_VERSION 提取版本号。Windows 下若用 NSIS 生成 exe 安装包，还要求 PROJECT_NAME 不能含空格或特殊字符，否则 NSIS 编译失败并报错：Invalid character in output filename。

可执行文件必须通过 install(TARGETS ...) 显式声明安装规则

仅靠 add_executable(myapp main.cpp) 不会让 CPack 打包它——CPack 只打包被 install() 命令明确指定的目标。

常见错误是只写：

add_executable(myapp main.cpp)
# 忘了 install() —— myapp 不会被包含进安装包

正确做法是补上：

install(TARGETS myapp
  RUNTIME DESTINATION bin
  COMPONENT runtime)

RUNTIME 表示这是 Windows 的 .exe 或 Linux/macOS 的可执行文件；DESTINATION bin 决定它在安装后路径（如 /usr/local/bin）；COMPONENT runtime 是可选分组，方便后续用 cpack -C runtime 单独打包运行时部分。

如果你的程序依赖动态库，也要对 add_library(... SHARED) 目标加 install(TARGETS ... LIBRARY ...)，否则安装后直接运行会报 libxxx.so: cannot open shared object file。

Linux 下生成 tar.gz 需启用 PACKAGE_FORMAT 和设置 CPACK_GENERATOR

默认运行 cpack 只生成 tar.gz，但实际行为取决于 CMake 版本和系统环境：CMake 3.21+ 默认启用 TBZ2（.tar.bz2），老版本可能 fallback 到 TAR（无压缩）。想稳定输出 .tar.gz，必须显式设置：

set(CPACK_GENERATOR "TGZ")
set(CPACK_PACKAGE_FILE_NAME "${CMAKE_PROJECT_NAME}-${CMAKE_PROJECT_VERSION}-Linux")

注意：TGZ 是唯一对应 .tar.gz 的生成器名，别写成 TAR.GZ 或 GZIP——CPack 会静默忽略并退回到默认行为。

另外，CPACK_PACKAGE_EXECUTABLES 可用于标记哪些文件是“主程序”，让 Windows 安装器在桌面/开始菜单创建快捷方式，Linux 下虽不生效，但设了也没副作用：

set(CPACK_PACKAGE_EXECUTABLES "myapp" "My Application")

Windows NSIS 安装包需额外配置图标、许可证和安装路径

NSIS 是 CPack 在 Windows 上最常用的生成器，但默认生成的安装包非常简陋：无图标、无许可协议、默认装到 C:/Program Files/...（普通用户无权限），且卸载项里显示名字是 MyApp 而不是你期望的完整产品名。

关键配置项包括：

• CPACK_NSIS_DISPLAY_NAME：控制控制面板“已安装程序”里显示的名字
• CPACK_NSIS_PACKAGE_NAME：安装向导窗口标题栏文字
• CPACK_RESOURCE_FILE_LICENSE：指向 LICENSE.txt 的绝对路径（必须存在，否则 NSIS 编译失败）
• CPACK_NSIS_MUI_ICON 和 CPACK_NSIS_MUI_UNIICON：分别指定安装/卸载界面图标（.ico 格式）
• CPACK_NSIS_INSTALL_ROOT：推荐设为 C:/Program Files 或 C:/Program Files (x86)，避免写死用户家目录

这些变量要在 project() 之后、include(CPack) 之前设置，否则无效。

CPack 对路径敏感，所有资源文件路径（如图标、许可证）必须用正斜杠 / 或双反斜杠 \\，单反斜杠 \ 会导致 NSIS 解析失败并中断构建。