前阵子有个同事把一份快 500 行的 CMakeLists.txt 甩给我,说项目一多根本维护不过来。我扫了一眼,发现里面全是 set(...) 收集源文件、add_subdirectory(...) 一路往下加目录、include_directories(...) 和 add_definitions(...) 到处开全局影响。说白了,他还在用写脚本的思维写 CMake。很多人觉得 CMake 难,不是因为它语法怪,而是因为你把它当成了“文本替换工具”,没有抓住它真正设计的三个核心:目标(Target)、属性(Property)和 API(命令函数)。这三件事一旦想明白,CMake 立刻从“玄学”变成“逻辑清晰的一门工程语言”。
这篇东西我会把这些年在实际项目里积累的理解、踩过的坑、常用函数的具体用法一次讲透。我会用大量可复制的例子,重点是解释清楚“为什么这样做”,而不是只丢给你一堆命令。适合刚开始接触 CMake 的初学者,也适合已经写了半年一年 CMakeLists 但总觉得哪里别扭的开发者——你缺的往往不是命令,而是对 CMake 运行模型的理解。
1. 目标:现代CMake的地基,而不是一串变量
1.1 从“变量收集器”到“目标依赖图”
CMake 从 3.x 开始官方就强烈推荐“target-based”写法。这个理念其实很简单:你不要把编译过程当成“把一堆 .cpp 文件依次喂给编译器”,而是当成“构建一张图”。图的节点是目标(Target),图的边是依赖关系(Dependency)。编译顺序、宏定义传播、头文件搜索路径传播,全部从这张图推导出来。
这条思路一旦建立,你就不会再写出那种几百行堆变量的 CMakeLists。我曾经接手过一个老项目,里面维护着十几个目录级别的 include_directories 和 add_definitions,改一个公共头文件路径能牵连出五六处报错。后来我重构时只做了一件事:把每个模块定义成独立的库目标,然后用 target_link_libraries 连接它们。之后新增模块、调整依赖,都只改两行。
很多人在这一步最大的误区是:觉得“反正小项目,直接用变量多省事”。但变量在目录层级间传播靠的是“作用域继承”,非常隐式。A 目录里 set 了一个变量,B 目录能不能看到完全取决于你们之间的 add_subdirectory 关系和根目录是否用了 CACHE。目标则不同——目标一旦 add_library 定义出来,就是一个独立的对象,你可以跨目录引用它,可以查询它的属性,可以修改它,行为非常明确。
1.2 add_executable / add_library:每一行指令都在定义对象
这是 CMake 里最基础的两个“对象构造函数”:
cmake复制add_executable(my_app main.cpp utils.cpp)
add_library(my_core STATIC core.cpp math.cpp)
add_library(my_header_only INTERFACE)
很多人知道 add_executable 生成可执行文件,add_library 生成库。但注意第三行:INTERFACE。这是个不少老手都容易忽略的关键点——它定义了一个“只有接口、没有实现”的目标,专门用于传播头文件目录、编译宏、编译选项,但不产生任何 .a/.so 文件。头文件库(header-only)项目就靠它。
库类型还有 STATIC(静态库)、SHARED(动态库)、MODULE(运行时加载的插件)。我建议你把这个参数显式写出来,不要省略。缺省值在不同 CMake 版本和不同策略下可能变化,BUILD_SHARED_LIBS 这个全局开关会把它变成 SHARED。显式写清楚,别人读你的脚本时不会产生歧义。
每个目标还可以通过 add_dependencies 指定构建顺序:
cmake复制add_dependencies(my_app generate_header_target)
注意 add_dependencies 解决的是“先后顺序”,而不是“链接关系”。如果你想让 A 依赖 B 的产物并链接 B 的符号,只用 target_link_libraries 就够了,连依赖顺序 CMake 都会自动处理好。
1.3 目标的依赖与链接:target_link_libraries 与 PUBLIC/PRIVATE
target_link_libraries 是使用频率最高的目标级命令,它做了三件事:
- 指定链接时需要的库文件;
- 在编译目标时自动追加链接目录;
- 把关联的“使用要求”(Usage Requirements)传播给依赖者。
关键在第三点。看这个例子:
cmake复制add_library(my_core STATIC core.cpp)
target_include_directories(my_core PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/include)
add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE my_core)
my_app 在编译时,include 目录会被自动加入头文件搜索路径,因为 PUBLIC 表示“我编译时需要,我的使用者编译时也需要”。这比手动 include_directories 高明在哪里?高明在自治——每个目标自己声明“我要求别人给我什么”,而不是靠父目录统一给全部子目录开白名单。
关于 PUBLIC / PRIVATE / INTERFACE 的选择,可以套用一句话:这个配置是给这个目标自身编译用的,还是给依赖它的下游用的,还是两者都要?
| 关键字 | 对目标自身生效 | 对依赖者传递 | 典型场景 |
|---|---|---|---|
| PRIVATE | 是 | 否 | 内部依赖的第三方库头文件路径 |
| PUBLIC | 是 | 是 | 导出头文件需要的外部头文件路径 |
| INTERFACE | 否 | 是 | header-only 库的头文件路径 |
链接顺序是个经典坑。下面的例子在 Linux 下经常报 undefined reference:
cmake复制target_link_libraries(my_app PRIVATE libB.a libA.a)
如果 libB.a 里引用了 libA.a 的符号,这种顺序在旧版 GNU 链接器下会失败(新版 gcc 有 --as-needed 行为差异)。通常调整顺序:
cmake复制target_link_libraries(my_app PRIVATE libA.a libB.a)
更好的做法是用 target_link_libraries 的“名字不带路径”写法——直接传目标名,让 CMake 自己处理库文件路径和依赖顺序:
cmake复制target_link_libraries(my_app PRIVATE my_core another_core)
你不用关心哪个库文件在前面,CMake 会按依赖图排序。这就是“目标思维”的价值。
1.4 别名目标与导入目标:跨目录和依赖库的统一接口
add_library(my_core_alias ALIAS my_core) 可以创建一个别名目标。别名目标有什么用?一是让你在内部统一命名风格,二是避免顶层目标名被外部误用。更重
