本文的实测边界:本机是 Windows + MinGW,g++ 16.2.0 和 ar 可用,多文件编译、生成目标文件、打静态库、链接顺序报错都真跑过。但本机没有安装 CMake,执行 cmake --version 直接报命令不存在,所以所有 CMake 命令、CMakeLists 和预设文件都属于未在本机实测,只按官方语义讲。照抄前请先装好 CMake 跑一遍。
场景很常见:一个三文件的小工具,add.h、add.cpp、main.cpp。你在自己机器上写了这么一条命令,跑得很好:
g++ -std=c++20 -Wall -Wextra main.cpp add.cpp -o app.exe
然后项目挪到了新机器,或者进了 CI。有人把源文件清单漏了一个,有人把库的顺序调了一下,报错五花八门,但共同点是:代码没变,命令变了。这就是「本地能编」的真相——能编的不是项目,是你这台机器上那条恰好正确的命令。
命令行为什么撑不住
先把代价摆出来,才知道工具该解决什么。手工命令行有三个躲不掉的问题。
- 信息不成文。include 路径写在命令里,宏定义写在命令里,
-D后面跟的是什么含义,只有写的人知道。新同事拿到仓库,第一件事是翻文档或者问你,而不是直接构建。 - 依赖顺序是人肉排的。静态库按命令行顺序逐个扫描,前面的库引用后面的库时,后面的库还没进扫描队列,符号就悬空了。
- 换平台要重写。Windows 上
.exe、-lfoo找libfoo.a,Linux 上找libfoo.so,路径分隔符、运行期库路径、编译器名字全不一样。同一份逻辑维护两套命令,迟早两边不一致。
所以构建系统要做的不是「替你敲 g++」,而是把这些信息集中成一份声明,让任何人、任何机器都能从这份声明重新生成正确的命令。CMake 就是这类工具里最主流的一个。
CMake 到底做了什么
很多人以为 CMake 是「更高级的编译器」,其实它自己一个源文件都不编。它做的是三件事:读 CMakeLists.txt,检查环境和依赖,然后生成另一套构建文件(Makefile、Ninja 文件、Visual Studio 工程),最后调用那套工具去编译。所以它的正式定位叫「构建系统生成器」。
这个分工解释了两类奇怪的现象。第一,改一行 CMakeLists 之后必须重新「配置」,因为生成的文件已经过期;第二,配置阶段失败和构建阶段失败是两回事,前者通常是环境问题(找不到编译器、找不到包),后者才是代码或链接问题。排错时先看失败发生在哪一段。
另一个概念是源目录和构建目录:源目录放代码和 CMakeLists,构建目录放生成物。两者分开是基本用法,混在一起会制造一批很难查的怪错误。
target 是 CMake 的中心
现代 CMake 只有一种正确的组织方式:一切属性挂在 target 上。target 就是构建产物,用 add_executable 加可执行文件,用 add_library 加库。不要用全局的 include_directories、link_directories 影响整个目录,那会把依赖关系弄乱。
第三层是理解 CMake 的关键。一个库不只是「一堆 .o 打包」,它还带着「用我的人需要知道的事」。头文件在哪个目录、要不要定义某个宏、要不要再链接别的库,这些叫使用要求(usage requirements)。PUBLIC、PRIVATE、INTERFACE 三个关键字,说的就是这些要求往哪边传。
| 关键字 | 自己构建时用不用 | 链接我的人要不要继承 | 典型场景 |
|---|---|---|---|
PRIVATE | 用 | 不继承 | 只在本目标内部使用的头文件目录、只在实现里用的库 |
PUBLIC | 用 | 继承 | 公开头文件所在目录、接口里出现的类型所依赖的库 |
INTERFACE | 不用 | 继承 | 头文件库(header-only),自己没有源文件,只把要求传出去 |
判断标准只有一句话:这个依赖会不会出现在我公开的头文件里。会,就用 PUBLIC;只在 .cpp 里用,就 PRIVATE;自己没有编译单元、纯粹给别人用,就 INTERFACE。搞错方向的后果不是编译失败,而是「我这个库自己编过了,用我的项目编不过」,报错还报在别人的代码里。
全局目录式写法
include_directories(include) 一写,当前目录下所有目标都能找到头文件。短期省事,长期是灾难:两个库有同名头文件时,谁先谁后变成隐式规则;别人链接你的库,还得自己再写一遍 include 路径。
挂在 target 上
每个目标只拿到自己声明过的路径和依赖。写的时候多几行,换来的是依赖关系可查、可传递、可被工具分析。链接顺序也由 CMake 根据依赖图自动排。
下面这份 CMakeLists 对应本文开头那个三文件项目,写法是现代风格:
cmake_minimum_required(VERSION 3.20)
project(cppdemo LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)
add_library(mathlib STATIC add.cpp)
target_include_directories(mathlib PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
add_executable(app main.cpp)
target_link_libraries(app PRIVATE mathlib)
target_compile_options(app PRIVATE -Wall -Wextra)
target_include_directories(mathlib PUBLIC ...) 的意思是:mathlib 自己编译时能找到 add.h,链接 mathlib 的 app 也自动继承这个路径,所以 app 里 #include "add.h" 不需要再写一遍。真实项目一般把头文件放到 include/ 子目录,这里为了对应前面的目录结构用了源码根目录。完整走查:先用手工命令编一遍
在没装 CMake 的机器上,先把「CMake 会替你做的事」手工做一遍,能看清它到底省了什么。第一步,只编译不链接,产出目标文件:
g++ -std=c++20 -Wall -Wextra -c add.cpp -o add.o
本机实测,退出码 0,没有任何输出。这一步只做编译和汇编,不找 main,也不解析 add 之外的符号。接着把它打成静态库:
ar rcs libadd.a add.o
同样退出码 0,静默。本机 ar 位于 C:\msys64\mingw64\bin\ar.exe。有个小细节:在这台机器的 PowerShell 里直接运行 ar t libadd.a 看不到输出,把 stdout 重定向到文件再读,才能看到成员名 add.o。这不是 ar 坏了,是它的输出没进 PowerShell 的管道,排查脚本时容易被误判成「打包失败」。
然后用库去链接主程序:
g++ -std=c++20 -Wall -Wextra main.cpp -L. -ladd -o app.exe
运行 .\app.exe,本机实测输出:
add(2,3) = 5
mul(2,3) = 6
到这里,CMake 要替你做的三件事已经出现了:-c 是一轮编译,ar 是一次打包,最后那条命令负责链接。-L. -ladd 换成 CMake 的写法,就是 target_link_libraries(app PRIVATE mathlib)。
现在看最值得亲手试的那个坑:静态库的链接顺序。准备两个库,libfoo.a 里的 foo() 调用了 libbar.a 里的 bar()。main2.cpp 只调用 foo()。先把 bar 写在前面:
g++ -std=c++20 main2.cpp -L. -lbar -lfoo -o bad.exe
本机实测的报错(去掉 PowerShell 的包装行,路径简写):
ld.exe: ./libfoo.a(foo.o):foo.cpp:(.text+0x9): undefined reference to `bar()'
collect2.exe: error: ld returned 1 exit status
退出码 1。明明 libbar.a 就在同一个目录,符号也确实存在,链接器却说找不到。原因在扫描模型:链接器按命令行顺序从左到右走,走到 -lbar 时,还没有任何未解析的 bar(),于是整个库被跳过;再走到 -lfoo,foo() 引入了对 bar() 的新需求,可 bar 已经走过去了,没人回头看。把顺序换成 -lfoo -lbar,本机实测运行输出 foo() = 42,退出码 0。
这个顺序问题在 CMake 里基本不会遇到:target_link_libraries 记录的是「谁依赖谁」,生成命令行时会做拓扑排序,必要时甚至重复写库名来满足循环依赖。这是用 CMake 最实际的收益之一。
对应的 CMake 命令(未在本机实测):
cmake -S . -B build -G Ninja
cmake --build build
-S 指定源目录,-B 指定构建目录,-G 选生成器。第一条是配置加生成,第二条才真的编译。Ninja 未安装时可以去掉 -G Ninja,让 CMake 用默认生成器。
构建目录、Debug 与 Release
构建目录独立出来,好处不只是「源码目录干净」。它让同一份代码可以同时存在多个构建:build/debug、build/release、build/asan,互不干扰,切配置不用重编全量。CMakeCache.txt 就住在构建目录里,记住编译器路径、生成器和各种缓存变量。
代价也随之而来:缓存会记住「上一次的环境」。换了编译器、挪了目录、升级了依赖,旧缓存还在,CMake 可能拿着旧路径去干活,报出一串莫名其妙的错误。最省事的处理不是研究缓存字段,而是删掉整个构建目录重新配置。这不是偷懒,是构建系统的常规维护手段。
| 构建类型 | 典型选项 | 用途与代价 |
|---|---|---|
| Debug | -g -O0 | 带符号、不优化,单步调试准确。体积大、运行慢 |
| Release | -O2 -DNDEBUG | 优化后发布,assert 失效。调试时变量会被优化掉 |
| RelWithDebInfo | -O2 -g | 上线排查用,保留符号。体积更大,优化后的行号仍可能跳 |
本机用 g++ 直接对比过体积:同一个两文件程序,-O0 -g 产出 53101 字节,-O2 -DNDEBUG 产出 35119 字节。小工具上无所谓,但在几千个编译单元的项目里,构建时间、产物体积、运行速度都会拉开距离。所以一开始就把两种配置分开,别到上线前才发现「一直编的是 Debug」。
CMake 侧用 CMAKE_BUILD_TYPE 选配置,命令行写 -DCMAKE_BUILD_TYPE=Release。要提醒一句:Visual Studio 这类多配置生成器不认这个变量,它在构建时用 --config Release。同一份 CMakeLists 在两种生成器下行为不同,遇到时先确认生成器是哪一种。
另一个值得早点引入的东西是 CMakePresets。它把「用哪个生成器、哪个构建目录、哪些缓存变量」写进一个 JSON 文件,提交到仓库,所有人用同一条命令。这样 CI 和本地不再是两套命令。
{
"version": 2,
"configurePresets": [
{
"name": "debug",
"generator": "Ninja",
"binaryDir": "${sourceDir}/build/debug",
"cacheVariables": { "CMAKE_BUILD_TYPE": "Debug" }
},
{
"name": "release",
"inherits": "debug",
"binaryDir": "${sourceDir}/build/release",
"cacheVariables": { "CMAKE_BUILD_TYPE": "Release" }
}
],
"buildPresets": [
{ "name": "debug", "configurePreset": "debug" },
{ "name": "release", "configurePreset": "release" }
]
}
用法是 cmake --preset debug 再 cmake --build --preset debug。以上同样未在本机实测。预设文件里的 version 字段必须和安装的 CMake 版本支持的 schema 对上,版本过低会直接拒绝读取;具体哪一版支持哪些字段,装好后对照官方文档确认,别照抄一个过时的版本号。
缓存、增量编译与第三方依赖
增量编译的原理很朴素:每个 .cpp 产出一个 .o,构建工具比较时间戳,只重编变化的部分。被低估的问题是:改了头文件,所有包含它的 .cpp 都得重编。Makefile 系工具靠 -MMD 生成的依赖文件追踪这层关系,CMake 默认会处理,前提是依赖信息真的被记录下来。如果某次构建「改了头文件却没重编」,先用一次全量清理构建验证,别急着怀疑编译器。
构建缓存工具(如 ccache)则是在编译器外面再加一层:把「预处理后的源码 + 编译参数」算成哈希,命中就直接复用上次的目标文件。CMake 里通过 CMAKE_CXX_COMPILER_LAUNCHER 接进去。它对反复切换分支、反复全量构建的场景收益很大,对本来就只编一个文件的小项目意义有限。这一条本机没有安装 ccache,未实测。
第三方依赖有三种接法,选错会带来长期的维护成本。
- find_package:依赖已经在系统里(包管理器、vcpkg、系统库),CMake 只负责找到它并导入目标。写法短,前提是目标机器上确实装好了。
- vcpkg / Conan:把依赖和版本写进清单文件,由包管理器下载、编译、提供工具链文件。
vcpkg.json加CMAKE_TOOLCHAIN_FILE是常见组合,适合依赖多、版本要锁死的项目。 - FetchContent:配置阶段直接把依赖的源码拉下来,当成自己项目的一部分编译。上手最快,代价是构建变慢、依赖的编译选项也由你负责。
find_package(fmt CONFIG REQUIRED)
target_link_libraries(app PRIVATE fmt::fmt)
include(FetchContent)
FetchContent_Declare(fmt
GIT_REPOSITORY https://github.com/fmtlib/fmt.git
GIT_TAG 11.0.2)
FetchContent_MakeAvailable(fmt)
target_link_libraries(app PRIVATE fmt::fmt)
这两段是两种接法的对照,实际项目只选一种,不要同时写。以上均未在本机实测(没有 CMake,也没有网络依赖环境)。真正要注意的不是语法,而是编译器和标准库必须统一:用 MSVC 编的静态库不能直接喂给 MinGW 链接,Debug 版和 Release 版的 CRT 也未必能混。这类错误往往表现为一堆找不到的符号,看起来像代码问题,实际是二进制不兼容。
构建报错:现象、原因、先查什么
构建阶段的报错有个规律:先判断它发生在配置、编译还是链接,再往对应的方向查。下面这张表按这个顺序整理。
| 你看到的现象 | 真实原因 | 第一步查什么 |
|---|---|---|
fatal error: add.h: No such file or directory,本机却正常 | 头文件搜索路径没挂到当前 target,或用了相对源码目录的路径 | 看该 target 的 target_include_directories 和实际文件位置;确认路径不是相对构建目录写的 |
调换库顺序后出现 undefined reference(本文实测) | 静态库按命令行顺序扫描,被依赖的库排在了前面 | 先确认符号确实在库里;再按依赖方向调整顺序,或在 CMake 里改成 target 之间的依赖 |
CMake Error: Could not find CMAKE_CXX_COMPILER | 编译器不在 PATH,或工具链文件指错了位置 | 先在同一个终端执行 g++ --version;确认预设里没有写死一个不存在的路径 |
| 换编译器后出现大量奇怪的链接错误或 ABI 警告 | 构建目录里留着旧编译器的缓存和旧目标文件 | 删掉整个构建目录重新配置,不要试图改缓存里的单个变量 |
| 编过了,运行时提示缺 DLL 或加载失败 | 动态库不在可执行文件的搜索路径里,属于运行期问题 | Windows 查同目录与 PATH,Linux 用 ldd 看依赖;必要时把库复制到产物旁边 |
| 改了头文件,构建却像没看见 | 依赖信息缺失、时间戳异常,或生成文件覆盖了源文件 | 先全量清理构建一次;再看依赖文件是否生成、时钟是否正常 |
undefined reference to vtable for X | 类的第一个非纯虚函数(常见是析构)只声明没定义 | 查该类的虚析构或首个虚函数是否有实现,别去找构造函数 |
表里最容易误判的是最后一条:vtable 报错看起来像「虚表坏了」,其实是链接器在提醒你「这个类缺少某个虚函数的定义」。虚表由第一个非纯虚函数的定义所在编译单元生成,析构函数通常就是这个角色。
边界与代价
CMake 不是免费的,它的成本主要在这几处。
- 多一层语言。CMakeLists 本身是一门脚本语言,有变量作用域、有函数、有历史包袱。写复杂逻辑(条件编译、平台分支、代码生成)时,调试成本不比写 C++ 低。
- 生成器差异。Make、Ninja、Visual Studio 的行为不完全一致,多配置与单配置生成器的变量语义不同,跨平台团队会持续被这类差异绊住。
- 封装过度。项目一大,常见有人写一堆
.cmake模块把所有细节包起来,结果是新人看不懂、老人也记不住。好的封装应该只藏重复,不藏语义。 - 小项目可能不需要它。三五个文件、只在一台机器上跑,一个 Makefile 或一条脚本就够了。引入 CMake 的收益来自「多人、多机、多配置」,没有这些前提,收益有限。
只要项目会进 CI、会有第二个人接手、会依赖第三方库,构建脚本就不该停留在某个人终端历史里的那条命令。决定项目好不好维护的,是依赖关系有没有被显式写出来。
当天能验证的练习
- 建好
add.h、add.cpp、main.cpp,用g++ -c add.cpp -o add.o生成目标文件,再用ar rcs libadd.a add.o打包,最后用-L. -ladd链接。全程记录退出码。 - 再做两个库
libfoo.a、libbar.a,让 foo 依赖 bar,分别用-lbar -lfoo和-lfoo -lbar链接,把两次结果抄下来。这个实验五分钟,能记一辈子。 - 同一个程序分别用
-O0 -g和-O2 -DNDEBUG编译,用文件管理器或Get-Item看体积差(本机实测是 53101 与 35119 字节,你的数字会不同)。 - 装好 CMake 后(本机未安装),把上面的 CMakeLists 保存到项目根目录,执行
cmake -S . -B build和cmake --build build,再故意删掉target_include_directories那一行,看报错长什么样。 - 在 CMake 里把
mathlib的 include 目录从PUBLIC改成PRIVATE,重新构建,观察app是否开始报找不到add.h。
小结
三句话收尾:构建系统管的不是编译本身,而是把「源文件、路径、库、选项」这些隐含信息变成一份可传递的声明;现代 CMake 的一切都挂在 target 上,PUBLIC/PRIVATE/INTERFACE 决定使用要求往哪边传;静态库的链接顺序是真实存在的历史包袱,CMake 用依赖图替你兜住,但手工链接时仍然会踩。
构建解决的是「怎么把代码变成程序」。程序跑起来之后,第一件要面对的事就是读写文件:日志写进去没有、CSV 换台机器为什么多出空行、进程被 kill 之后文件里为什么是空的。下一篇从这些现象讲文件与 I/O,把缓冲、换行、编码这几层拆开。