一、基本调用形式

cmake [<选项>] -S <源码目录> -B <构建目录>
cmake --build <构建目录> [<选项>]
cmake --install <构建目录> [<选项>]

-S：指定顶层 cmakelists.txt 所在的源码目录。

-B：指定构建目录（二进制编译后输出目录），目录不存在时候会自动创建。

也可以不写 -S / -B ,也可以直接在构建目录内运行 cmake <源码目录>

二、配置与生成阶段（Configure & Generate）

首次配置

cmake -S . -B build

在当前目录的 build 子目录下生成构建系统（默认生成Makefile 或 系统所对应的构建系统）

指定生成器

cmake -S . -B build -G "Ninja"
cmake -S . -B build -G "Visual Studio 17 2022" -A x64

-G "生成器名"：指定构建工具，如 “Ninja” ， “Xcode” ， “Visual Studio 17 2022” 等

-A：对多架构生成器指定目标平台（如Win32、x32、x64、ARM64)

指定构建类型与安装前缀

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/usr/local

-D<变量>=<值>：设置CMake变量。单次配置可以配置多个-D

常用变量：

  • CMAKE_BUILD_TYPE：Debug / Release / RelWithDebInfo / MinSizeRel
  • CMAKE_INSTALL_PREFIX：安装路径
  • CMAKE_PREFIX_PATH：查找依赖的路径
  • CMAKE_TOOLCHAIN_FILE：交叉编译工具链文件路径

使用预设（Presets）

cmake --preset <预设名>        # 使用指定预设配置项目。(省去手动指定-B、-G、-D等参数）
cmake --list-presets        # 查看当前项目所有可用预设

预设定义在 CMakePresets.json 中，可以集中管理配置、构建、测试选项。

三、构建阶段

cmake --build build                        # 默认构建所有目标
cmake --build build --target my_app        # 只构建指定目标
cmake --build build --config Release    # 多配置生成器，构建指定配置（Release）
cmake --build build -j 8                # 并行任务数（需要构建系统支持）
cmake --build build -clean-first        # 构建前先清理
  • 使用--build 不用关系底层是make、ninja还是msbuild，CMake会自动调用对应工具。

四、安装阶段

cmake --install build                       # 默认构建所有目标
cmake --install build --prefix /opt/myapp  # 覆盖安装路径
cmake --install build --config Release     # 多配置选择安装那个配置
cmake --install build --component headers  # 只安装制定组建（需项目定义）

五、运行测试（CTest）

cd build && ctest                            # 基础测试
ctest --test-dir build -C Debug              # 多配置选择
ctest --test-dir build -R "My_test"          # 运行名字匹配的测试
ctest --test-dir build --output--on-failure  # 失败时输出详细详细

六、其他实用命令

查看帮组和版本

cmake --version
cmake --help
cmake --help-command add_library     # 查看特定命令文档
cmake --help-property CXX_STANDARD   # 查看属性文档
cmake --help-module FindBoost        # 查看模块文档

列出可用目标

cmake --build build --target help # 对 Make/Ninja 生成器有效

或在构建目标中运行（针对 Make/Ninja）：

make help       # 或 ninja -t targets all

编译数据库（compile_commands.json）

他的作用非常重要：静态分析，代码格式化，语言服务器为 VSCode | Clangd 提供精准的代码不全，跳转和错误提

cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

打开 CMake GUI（非 CLI，但常用）

cmake-gui .

清理与重建

CMake 本身没有 cmake clean 命令，通常做法是：

  • 删除构建目录重新配置：rm -rf build && cmake -S . -B build
  • 或利用 cmake --build build --target clean（需要生成器支持）

七、一次完整的工作流

# 克隆后
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=./install
cmake --build build -j$(nproc)
cmake --install build
ctest --test-dir build -C Release

八、CPack 打包工具

简单说CPack 是CMake 自带的跨平台打包工具，它可以打包为Linux，Windows，Mac的安装程序或者压缩包等等. 它本身不是独立的打包工具，是会读取 CMakeList.txt 的install 命令来决定 如何构建打包规则。并且可以通过 "SET" 命令设置安装包相关信息(包名，作者，版本..),不同平台有不同的配置。

示例

MyApp/
├── CMakeLists.txt
├── main.cpp
└── README.md

CMakeLists.txt

cmake_minimum_required(VERSION 3.10)
project(MyApp VERSION 1.0.0)

# ---------- 1. 构建目标 ----------
add_executable(myapp main.cpp)

# ---------- 2. 定义安装规则（CPack 会读取这些规则） ----------
install(TARGETS myapp
        RUNTIME DESTINATION bin          # 可执行文件安装到 bin 目录
        )

install(FILES README.md
        DESTINATION share/doc/myapp     # 文档安装到 share/doc/myapp
        )

# ---------- 3. 设置 CPack 元数据变量（必须在 include(CPack) 之前） ----------
set(CPACK_PACKAGE_NAME "MyApp")
set(CPACK_PACKAGE_VERSION "${PROJECT_VERSION}")
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "A simple demonstration app")
set(CPACK_PACKAGE_VENDOR "MyCompany")
set(CPACK_PACKAGE_CONTACT "support@mycompany.com")
set(CPACK_PACKAGE_HOMEPAGE "https://mycompany.com/app")

# ---------- 4. 选择打包生成器（按需启用） ----------
# Linux 上常见：生成 .tar.gz 压缩包 + .deb 和 .rpm
set(CPACK_GENERATOR "TGZ;DEB;RPM")

# Windows 上常见：生成 ZIP 压缩包或 NSIS 安装程序
# set(CPACK_GENERATOR "ZIP;NSIS")

# macOS 上常见：生成 .dmg 或 .pkg
# set(CPACK_GENERATOR "DragNDrop;PackageMaker")

# ---------- 可选：针对特定生成器的额外配置 ----------
# Debian 包专用设置
set(CPACK_DEBIAN_PACKAGE_MAINTAINER "MyCompany <support@mycompany.com>")
set(CPACK_DEBIAN_PACKAGE_DEPENDS "libc6 (>= 2.29)")

# NSIS（Windows 安装程序）专用设置
set(CPACK_NSIS_DISPLAY_NAME "MyApp Installer")
set(CPACK_NSIS_CONTACT "support@mycompany.com")

# ---------- 5. 加载 CPack 模块（最后一步） ----------
include(CPack)

构建项目

mkdir build && cd build
cmake ..

打包

在 构建目录下执行，例如 build 目录

cpack
  • 默认生成 在 CMakeLists.txt 中的 set 命令设置的CPACK_GENERATOR 中制定的所有包格式。
  • 也可以手动制定输出格式：cpack -G DEB # 仅生成 .deb

输出位置

生成的安装包会放在构建目录下的 \_CPack\_Packages/ 或直接放在当前目录（取决于 CMake/CPack 版本，通常可以直接在构建目录中找到）。

注意点

  • install命令：定义那些文件（目标、库、文档等）要被打包，以及他们的目标安装路径。
  • CPACK_* 变量：通过 set() 设置包名、版本、作者等信息，部分变量是通用的，部分变量是针对特定生成器生效。
  • include(CPack):必须放在所有install() 和 CPACK_*变量之后，他在读取这些变量后会触发打包逻辑。
  • 生成器（Generator）：CPack 内部调用不同平台的打包工具来制作安装包，这些工具就叫“生成器”。通过 set(CPACK_GENERATOR "DEB;TGZ") 来指定要用哪些生成器，选哪个，最终就产出哪种格式的包。