本文的实测边界:本机是 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。有人把源文件清单漏了一个,有人把库的顺序调了一下,报错五花八门,但共同点是:代码没变,命令变了。这就是「本地能编」的真相——能编的不是项目,是你这台机器上那条恰好正确的命令。

一条 g++ 命令里其实藏了七类信息:编译器是谁、语言标准、源文件清单、头文件搜索路径、库搜索路径与库名、预处理宏、优化与调试等级。项目一大,这七类信息就从「敲一行」变成「维护一份只有作者看得懂的脚本」,换个人接手就开始还债。

命令行为什么撑不住

先把代价摆出来,才知道工具该解决什么。手工命令行有三个躲不掉的问题。

  • 信息不成文。include 路径写在命令里,宏定义写在命令里,-D 后面跟的是什么含义,只有写的人知道。新同事拿到仓库,第一件事是翻文档或者问你,而不是直接构建。
  • 依赖顺序是人肉排的。静态库按命令行顺序逐个扫描,前面的库引用后面的库时,后面的库还没进扫描队列,符号就悬空了。
  • 换平台要重写。Windows 上 .exe、-lfoo 找 libfoo.a,Linux 上找 libfoo.so,路径分隔符、运行期库路径、编译器名字全不一样。同一份逻辑维护两套命令,迟早两边不一致。

所以构建系统要做的不是「替你敲 g++」,而是把这些信息集中成一份声明,让任何人、任何机器都能从这份声明重新生成正确的命令。CMake 就是这类工具里最主流的一个。

CMake 到底做了什么

很多人以为 CMake 是「更高级的编译器」,其实它自己一个源文件都不编。它做的是三件事:读 CMakeLists.txt,检查环境和依赖,然后生成另一套构建文件(Makefile、Ninja 文件、Visual Studio 工程),最后调用那套工具去编译。所以它的正式定位叫「构建系统生成器」。

一次 CMake 构建的三个阶段
配置:读 CMakeLists.txt,找编译器,检查依赖,写 CMakeCache.txt
生成:按选定的生成器产出 Makefile 或 build.ninja
构建:调用 make 或 ninja,真正编译、汇编、链接

这个分工解释了两类奇怪的现象。第一,改一行 CMakeLists 之后必须重新「配置」,因为生成的文件已经过期;第二,配置阶段失败和构建阶段失败是两回事,前者通常是环境问题(找不到编译器、找不到包),后者才是代码或链接问题。排错时先看失败发生在哪一段。

另一个概念是源目录和构建目录:源目录放代码和 CMakeLists,构建目录放生成物。两者分开是基本用法,混在一起会制造一批很难查的怪错误。

target 是 CMake 的中心

现代 CMake 只有一种正确的组织方式:一切属性挂在 target 上。target 就是构建产物,用 add_executable 加可执行文件,用 add_library 加库。不要用全局的 include_directories、link_directories 影响整个目录,那会把依赖关系弄乱。

目标层:add_executable / add_library,声明「要产出什么」
属性层:这个目标用什么源文件、什么标准、什么宏、什么优化等级
使用要求层:别人链接我这个目标时,需要额外拿到哪些 include 路径、宏和依赖

第三层是理解 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)
以上 CMakeLists 未在本机实测(本机没有 CMake)。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,把缓冲、换行、编码这几层拆开。