1 / 4概念
Toolchain: CMake
CMake 不编译源码,它生成一套能编译源码的构建文件。判断一份 CMakeLists.txt 是否合格,不看命令是否齐全,而看三件事:使用要求是否挂在 target 上、下游能否只靠 find_package 就拿到同样的编译选项、增量构建能否只重编受影响的目标。
1 概念
1.1 一句话定义
CMake 是构建系统生成器:configure 阶段执行 CMakeLists.txt 并写出 CMakeCache.txt,generate 阶段产出 Ninja、Makefile 或 Visual Studio 工程,build 阶段由生成器调用编译器。target 是唯一的属性载体,target_* 命令写属性,PRIVATE、PUBLIC、INTERFACE 决定属性是否流向下游。
1.2 它解决什么问题
- 跨平台一套描述:同一份
CMakeLists.txt在 Ninja 与 Visual Studio 下都能生成可构建工程。 - 安装与消费:
install(EXPORT)让下游用find_package拿到 imported target,而不是手写-I与-l。 - 可复现配置:presets 把生成器、构建目录与缓存变量写进仓库,消除“本机能过、CI 不能过”。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
-std、ABI 宏与编译器差异 | Toolchain: Compilers and Standards(cpp-compilers) |
| 依赖获取、二进制缓存与 ABI 匹配 | Toolchain: Dependencies(cpp-dependencies) |
ctest、sanitizer 与调试器 | Toolchain: Test and Debug(cpp-testing-and-debugging) |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| target | 构建图中的节点,库或可执行文件,也是一切属性的宿主 | 不是源文件列表 |
| imported target | 由外部包声明、本工程不构建的 target,通常带 :: | 不能修改其属性,只能读取 |
| usage requirement | 跟随 target 传播给消费者的编译与链接要求 | 不是全局变量 |
| generator expression | generate 阶段求值,如 $<CONFIG:Debug> 与 $<BUILD_INTERFACE:...> | 不是 configure 阶段的变量 |
| generator | 实际产出构建文件的程序:Ninja、Makefiles、VS、Xcode | 不是编译器 |
| preset | CMakePresets.json 中固化的配置、构建与测试参数 | 不是 shell 脚本 |
| toolchain file | 声明交叉编译的编译器、sysroot 与目标三元组 | 只在首次 configure 生效 |
2 机制
2.1 心智模型
一次 CMake 运行有三段:configure 执行命令式脚本、求值变量、建立 target 与依赖关系;generate 把 target 图翻译成具体构建文件,此时生成器表达式才求值;build 交给 Ninja 或 MSBuild 执行。属性传播发生在 configure,命令行生成发生在 generate。所以"改了 CMakeLists.txt 但构建没变“多半卡在缓存,而”编译选项没传下去"多半是传播模式写错。
2.2 机制拆解
- target 即接口:
add_library与add_executable建 target,target_*只管一个 target;目录级命令(include_directories、link_directories)污染整个目录树,应避免。 - 三向传播:
PRIVATE只写本 target 的COMPILE_*;PUBLIC同时写INTERFACE_*;INTERFACE只写INTERFACE_*,自身不编译任何东西。 - 标准与特性:
target_compile_features(tgt PUBLIC cxx_std_20)让 CMake 选择满足该标准的编译选项,并把需求传给下游;CXX_EXTENSIONS OFF关闭gnu++20一类扩展。 - build 与 install 接口:
$<BUILD_INTERFACE:...>只在 build tree 生效,$<INSTALL_INTERFACE:...>只在被安装后被消费方看到;写死绝对路径会让导出的包在别人机器上失效。 - 两段查找:
find_package先试 Module 模式(仓库自带FindFoo.cmake),再试 Config 模式(FooConfig.cmake提供 imported target);只有找不到包时才用FetchContent拉源码,FETCHCONTENT_FULLY_DISCONNECTED可禁止配置期联网。 - 生成器与缓存:单配置生成器(Ninja、Makefiles)用
CMAKE_BUILD_TYPE选配置,多配置生成器(VS、Xcode)用--config;CMakeCache.txt记住编译器与路径,换编译器或移动目录必须--fresh。
2.3 完整枚举
现代 CMake 的属性入口就是这九个 target_* 命令;绕过它们的写法都会失去传播能力。
| 命令 | 写入的属性 | 参与传播 | 典型误用 |
|---|---|---|---|
target_sources | SOURCES、INTERFACE_SOURCES | 是 | 用它加生成文件却不设 GENERATED |
target_include_directories | INCLUDE_DIRECTORIES | 是 | 用 PRIVATE 装公开头文件,下游编译失败 |
target_compile_definitions | COMPILE_DEFINITIONS | 是 | 写 -DFOO,CMake 会自动补前缀 |
target_compile_features | COMPILE_FEATURES | 是 | 手写 -std=c++20 而不用特性名 |
target_compile_options | COMPILE_OPTIONS | 是 | 塞入 -I 路径,绕过依赖图 |
target_link_libraries | LINK_LIBRARIES、INTERFACE_LINK_LIBRARIES | 是 | 不加关键字,退化成旧式全局链接 |
target_link_directories | LINK_DIRECTORIES | 是 | 用目录找库,换机器即失效 |
target_link_options | LINK_OPTIONS | 是 | 把 -L 与 -l 混进链接选项 |
target_precompile_headers | PRECOMPILE_HEADERS | 是 | 把业务头放进 PCH,触发全量重编 |
2.4 三种传播模式
模式决定“谁付编译代价”:写错的直接症状是下游缺头文件、缺宏或链接不到符号。
| 模式 | 自身编译 | 下游编译 | 适用 |
|---|---|---|---|
PRIVATE | 继承 | 不继承 | 仅实现需要的宏、路径与库 |
PUBLIC | 继承 | 继承 | 公开头文件依赖的库与定义 |
INTERFACE | 不继承 | 继承 | header-only 库与纯接口 target |
3 实践
3.1 最小可运行示例
cmake_minimum_required(VERSION 3.23)
project(hello LANGUAGES CXX)
add_library(greet src/greet.cpp)
target_include_directories(greet PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
$<INSTALL_INTERFACE:include>)
target_compile_features(greet PUBLIC cxx_std_20)
add_executable(hello src/main.cpp)
target_link_libraries(hello PRIVATE greet)
install(TARGETS greet EXPORT helloTargets ARCHIVE DESTINATION lib)
install(DIRECTORY include/ DESTINATION include)
install(EXPORT helloTargets NAMESPACE hello:: DESTINATION lib/cmake/hello)
生成器、binaryDir 与 cacheVariables 应写进 CMakePresets.json 的 configurePresets,buildPresets 与 testPresets 通过 configurePreset 继承同一份配置;仓库里不再有“先执行某个长命令”的口头约定:
cmake --preset dev
cmake --build --preset dev -j
cmake --install build/dev --prefix /tmp/hello
追踪一次配置:target_compile_features(greet PUBLIC cxx_std_20) 让 generate 阶段为 greet 与 hello 各写一条 -std=c++20,因为 PUBLIC 把它写进了 INTERFACE_COMPILE_FEATURES。$<BUILD_INTERFACE:...> 在这一阶段被解析为源码树的 include 目录,hello 的编译命令行因此带上 -I.../include;install(EXPORT) 则把同一个 target 导出为 hello::greet,并改用 include 相对前缀。下游写 find_package(hello CONFIG) 加 target_link_libraries(app PRIVATE hello::greet),即继承全部使用要求。用 cmake --build build/dev --verbose 能看到真实的 -std 与 -I。
3.2 常用命令
| 目的 | 命令 | 说明 |
|---|---|---|
| 配置到独立目录 | cmake -S . -B build -G Ninja | out-of-source,源码树不留产物 |
| 用预设配置 | cmake --preset dev | 参数全部来自 CMakePresets.json |
| 构建 | cmake --build build -j | 与生成器解耦的调用方式 |
| 安装到前缀 | cmake --install build --prefix /tmp/p | 默认前缀由 CMAKE_INSTALL_PREFIX 决定 |
| 指定交叉编译 | cmake --preset dev -DCMAKE_TOOLCHAIN_FILE=tc.cmake | 必须在首次 configure 时给 |
| 丢弃缓存重配 | cmake --preset dev --fresh | 换编译器或移动目录后必做 |
| 打印依赖图 | cmake --graphviz=build/graph.dot build | 排查 target 依赖与查找失败 |
3.3 标准流程
- 顶层只放
cmake_minimum_required与project;每个库用add_library加target_include_directories(PUBLIC ...),并用生成器表达式区分 build 与 install 前缀。 - 编译标准用
target_compile_features表达,不手写-std;需要扩展时显式设CXX_EXTENSIONS OFF。 - 第三方依赖用
find_package(... CONFIG REQUIRED)并要求 imported target,缺包就让 configure 失败,不留到链接期。 - 需要安装的库补齐
install(EXPORT)与Config.cmake,并在 CI 里用一个独立消费工程验证。 - 生成器、构建目录与缓存变量写进 presets,CI 与本地跑同一条
cmake --preset。
3.4 选型矩阵
| 项目形态 | 生成器与结构 | 代价 |
|---|---|---|
| 单平台服务 | Ninja + 单配置 + presets | 换平台需新增 preset,不能复用 IDE 工程 |
| 跨平台库并对外发布 | Ninja 与 MSBuild 双跑 + install(EXPORT) | 必须维护 Config 文件与版本兼容 |
| Windows 桌面应用 | Visual Studio 生成器 + 多配置 | 命令行需 --config,与单配置习惯不同 |
| 嵌入式交叉编译 | toolchain file + 厂商生成器 | 工具链文件写错时错误才出现在链接期 |
3.5 决策规则
- 属性应挂在 target 上,目录级命令只允许出现在最外层且必须有注释说明理由。
- 公开头文件所在目录用
PUBLIC或INTERFACE,实现私有的路径与宏用PRIVATE。 - 需要被下游发现的包应导出 imported target,禁止让下游自己拼
-I与-l。 CMAKE_BUILD_TYPE只用于单配置生成器;多配置场景一律用--config。
4 边界
4.1 典型故障
| 症状 | 根因 | 诊断 | 修复 |
|---|---|---|---|
The current CMakeCache.txt directory ... is different | 构建目录被复制或移动 | 看 CMakeCache.txt 里的缓存路径 | 在新位置 --fresh 或删目录重建 |
Target "app" links to "greet" but the target was not found | 名称拼错或漏写 add_subdirectory | --graphviz 看依赖图节点 | 补 add_subdirectory 或修正 target 名 |
Cannot specify include directories for target "fmt::fmt" | 对 imported target 写属性 | 错误里的 target 名带 :: | 在消费侧用 INTERFACE 传播,不改导入目标 |
Could not find a package configuration file provided by "fmt" | 未设置前缀或未装包 | cmake -LAH 看 fmt_DIR | 设 CMAKE_PREFIX_PATH,或接入依赖管理器 |
编译通过但 undefined reference | 只声明 include,没有链接库 | --verbose 看链接命令行 | 补 target_link_libraries(... PRIVATE ...) |
fatal error: greet.h: No such file 只在下游出现 | 头文件目录写成了 PRIVATE | 查 INTERFACE_INCLUDE_DIRECTORIES | 改 PUBLIC,或补 INTERFACE 目标 |
install(EXPORT ...) includes target ... which requires ... not in any export set | 依赖未一起导出 | 读错误里列出的 target | 把依赖也加入同一 export 集,或降为 PRIVATE |
改了 CMakeLists.txt 行为不变 | 缓存变量或旧生成文件仍在 | 对比 cmake -LAH 与文件内容 | --fresh 重配 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
用 include_directories 与 link_directories 全局铺路径 | 目标间依赖不可见,换平台即失效 | target_include_directories 与 imported target |
在 CMakeLists.txt 里写死绝对路径 | 导出的包在别人机器上失效 | $<BUILD_INTERFACE:...> 与相对安装前缀 |
用 file(GLOB ...) 收集源文件 | 新增文件不触发重配,构建偶发漏编 | 显式列出源文件 |
4.3 可观测信号
configure 阶段看 cmake -LAH 的实际变量值与 --graphviz 的依赖图;generate 后看 build.ninja 或 .vcxproj 里每条编译命令的 -std、-I、-D;链接失败时看 --verbose 的完整链接行。安装后用 cmake --install 的文件树与一个独立消费工程验证导出是否自洽。
4.4 安全 / 性能 / 一致性边界
- 一致性:target 名、命名空间与导出集一旦被下游使用即为公开接口,重命名等于破坏兼容。
- 性能:
target_precompile_headers与 Unity Build 加速明显,但会掩盖头文件自包含问题;configure 时间随 target 数量线性增长。 - 安全:
FetchContent会执行第三方 CMake 脚本;应固定GIT_TAG到不可变提交,并审阅其CMakeLists.txt。