1 / 4概念
Toolchain: Make and CMake
Make 与 CMake 解决同一个问题:把“哪个文件依赖哪个文件”写成可执行的图。区别在于 Make 直接执行这张图,CMake 先把 target 与属性求值成图,再交给 Ninja 或 Make 执行。读完能判断一条规则为什么不触发、一个 target 为什么把 -I 传给了错误的消费者。
1 概念
1.1 一句话定义
Make 是按时间戳执行的“目标—先决条件—配方”规则系统;CMake 是构建系统生成器,用 target、属性与可见性描述依赖,再生成 Ninja、Unix Makefiles、Xcode 或 Visual Studio 工程。两者都不解析 C 语义。
1.2 它解决什么问题
- 增量构建:只重编受影响的文件,而不是每次全量编译。
- 依赖传播:头文件改动、库的 include 目录与链接参数应自动传给消费者,而不是靠人记。
- 跨平台生成:同一份描述在 Linux 生成 Ninja、在 macOS 生成 Xcode、在 Windows 生成 Visual Studio 工程。
- 安装与导出:库的头文件、二进制与包配置一起安装,下游一行
find_package就能用。
代价是抽象层变厚:Make 的错误在运行期出现,CMake 的错误在配置期出现,两者都不告诉你 C 代码哪里错。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 编译选项的语义与四阶段模型 | c-build-model |
| 宏与条件编译 | c-preprocessor |
| 符号解析与装载 | c-linking-and-loading |
| 测试、sanitizer 与调试 | c-testing-and-debugging |
| 库命名、soname 与 pkg-config | c-packaging |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| 目标 | Make 的产出节点,通常是文件 | 不是 CMake 的 target |
| 先决条件 | 目标依赖的文件或目标 | 不是配方里的命令参数 |
| 配方 | 生成目标的 shell 命令 | 必须以 tab 缩进 |
| 模式规则 | %.o: %.c 形式的规则模板 | 不是匹配现有文件的通配符 |
| 伪目标 | .PHONY 声明、不对应文件的目标 | 不是普通文件目标 |
| 自动变量 | 由规则自动填充的 $@、$< 等 | 不是全局变量 |
| 生成器 | CMake 选择的后端 | 不是编译器 |
| preset | CMakePresets.json 里的命名配置 | 不是 CMakeLists.txt 的一部分 |
| usage requirement | target 向消费者传播的 include、定义与链接项 | 不是普通编译选项 |
2 机制
2.1 心智模型
Make 执行图,CMake 生成图。 Make 在运行时比较目标与先决条件的 mtime,决定是否执行配方;CMake 在配置期读取 CMakeLists.txt,把 target、属性与可见性求值成一张图,再写成一个具体生成器的工程文件。因此 Make 的问题多半是“规则没匹配上”,CMake 的问题多半是“属性传错了范围”。
2.2 机制拆解
- Make 变量:
=递归展开,:=立即展开,?=仅在未定义时赋值,+=追加且保留原变量的展开方式;override防止命令行覆盖,export把变量传给子进程。CFLAGS管编译,CPPFLAGS管预处理,LDFLAGS管链接器选项,LDLIBS管库,四者不要混用。 - 规则:显式规则、模式规则、静态模式规则与隐式规则链共同决定“怎么从
.c得到.o”。配方每行是一个独立 shell,行首@静默、-忽略错误、+即使-n也执行;$$转义为字面$。 - 依赖文件:
-MMD -MP让编译器在生成.o时写出.d,-include $(DEPS)把它读进 Make。-M输出到 stdout,-MM忽略系统头,-MP为每个头文件加一条空规则,避免删头后报No rule to make target。 - 并行与特殊目标:
make -j$(nproc)按 DAG 并行;.PHONY声明all、clean、test,.DELETE_ON_ERROR在配方失败时删除半成品,.ONESHELL让整段配方在同一个 shell 里执行。 - CMake target:target 是属性与依赖的载体,名字全局唯一;
add_library可建 STATIC、SHARED、MODULE、OBJECT、INTERFACE、IMPORTED 与 ALIAS,add_executable建可执行目标,add_custom_target建总是执行的命令目标。 - 属性与可见性:
PRIVATE只影响自身编译,PUBLIC影响自身并传播给链接者,INTERFACE只传播不编译。target_include_directories、target_compile_definitions、target_compile_options、target_link_libraries都遵循这三种范围。 - 生成器与 preset:Unix Makefiles、Ninja、Ninja Multi-Config、Xcode 与 Visual Studio 是可选后端;单配置生成器靠
CMAKE_BUILD_TYPE选配置,多配置生成器靠cmake --build build --config Release。CMakePresets.json的configurePresets、buildPresets把参数固化成名字;-DCMAKE_EXPORT_COMPILE_COMMANDS=ON生成compile_commands.json,供 clangd 与 clang-tidy 使用。 - install 与 export:
install(TARGETS app RUNTIME DESTINATION bin)装可执行文件,install(TARGETS foo EXPORT fooTargets)加install(EXPORT fooTargets NAMESPACE foo:: DESTINATION lib/cmake/foo)生成包配置,消费者用find_package(foo CONFIG REQUIRED)取回 imported target。
2.3 完整枚举
GNU Make 的自动变量共 8 个,覆盖目标、先决条件与模式匹配三类信息:
| 变量 | 含义 | 典型用途 |
|---|---|---|
$@ | 当前目标名 | 链接输出 -o $@ |
$% | 归档成员名 | .a 成员的规则 |
$< | 第一个先决条件 | -c $< |
$? | 比目标新的先决条件 | 只处理改动过的输入 |
$^ | 全部先决条件,去重 | 链接对象列表 |
$+ | 全部先决条件,保留重复 | 需要重复库顺序时 |
$* | 模式规则匹配的词干 | %.o: %.c 中是文件名 |
$| | order-only 先决条件 | 保证目录存在但不触发重编 |
8 个基本自动变量都带 D 与 F 变体,分别取目录与文件名,例如 $(@D)、$(@F);变体不增加新的语义类别。
3 实践
3.1 最小示例与追踪
同一项目给两份实现,源码树是 include/mathx.h、src/mathx.c、src/main.c。
CC ?= cc
CFLAGS ?= -std=c17 -O2 -g -Wall -Wextra
CPPFLAGS += -MMD -MP -Iinclude
LDLIBS ?=
OBJS := build/main.o build/mathx.o
app: $(OBJS)
$(CC) $(LDFLAGS) $^ -o $@ $(LDLIBS)
build/%.o: src/%.c
@mkdir -p $(@D)
$(CC) $(CPPFLAGS) $(CFLAGS) -c $< -o $@
-include $(OBJS:.o=.d)
.PHONY: clean
clean:
rm -rf build app
cmake_minimum_required(VERSION 3.25)
project(mathx LANGUAGES C)
add_library(mathx STATIC src/mathx.c)
target_include_directories(mathx PUBLIC include)
target_compile_features(mathx PUBLIC c_std_17)
target_compile_options(mathx PRIVATE -Wall -Wextra)
add_executable(app src/main.c)
target_link_libraries(app PRIVATE mathx)
{"version": 6,
"configurePresets": [{"name": "dev", "generator": "Ninja",
"binaryDir": "${sourceDir}/build/dev",
"cacheVariables": {"CMAKE_BUILD_TYPE": "Debug",
"CMAKE_EXPORT_COMPILE_COMMANDS": "ON"}}],
"buildPresets": [{"name": "dev", "configurePreset": "dev"}]}
make # 首次构建
make # Nothing to be done for 'app'
touch include/mathx.h && make # 两个 .o 都重编
cmake --preset dev
cmake --build --preset dev
./build/dev/app
追踪:首次 make 先编 build/mathx.o 与 build/main.o,再链接;第二次没有文件比目标新,打印 Nothing to be done。touch 头文件后,-MMD 生成的 .d 里都有 include/mathx.h,两条模式规则因此都被触发。若删掉 -include $(OBJS:.o=.d),同一场景只会重链、不会重编,症状是改了结构体后旧目标文件仍按旧布局读写。CMake 侧,mathx 的 PUBLIC include 让 app 自动得到 -Iinclude,PRIVATE 的 -Wall 不会污染 app;build/dev/compile_commands.json 可直接给 clangd。
3.2 选型矩阵
| 场景 | 首选 | 备选 | 理由 |
|---|---|---|---|
| 单人小项目、零依赖 | Make | 直接 shell 脚本 | 一条命令完成构建,规则可读 |
| 有下游消费者的库 | CMake 加 install/export | Meson | 导出 imported target,消费者一行 find_package |
| 大型 monorepo | CMake 加 Ninja | Bazel | 增量与并行更好,支持 target 级依赖 |
| 嵌入式交叉编译 | CMake toolchain file | Make 加变量覆盖 | 工具链与 sysroot 集中声明 |
| 需要编译数据库 | CMake | Bear 包装 Make | 供 clangd 与 clang-tidy |
3.3 决策规则
- 头文件依赖应由编译器自动生成,不要手写
.d或靠人记;漏依赖的构建会产出与源码不符的目标文件。 - Make 的配方行必须以 tab 开头;空格缩进的报错是
missing separator。 - 不要用
file(GLOB)收集源码;新增文件不会触发重新配置,CONFIGURE_DEPENDS能缓解但会拖慢每次构建。 - 安装路径用
GNUInstallDirs的CMAKE_INSTALL_LIBDIR、CMAKE_INSTALL_INCLUDEDIR,不要硬编码lib与include。 - 库的依赖能声明为
PUBLIC就不要留到消费者手动补;这是undefined reference最常见的来源。
4 边界
4.1 典型故障
| 症状 | 根因 | 诊断 | 修复 |
|---|---|---|---|
make: *** No rule to make target 'build/main.o' | 源文件不在 src/,或模式规则不匹配 | make -p 查已注册规则,make -d 看查找过程 | 修正目录或规则,确认 %.o: %.c 两侧路径一致 |
| 改了头文件却不重编 | 未生成或未包含 .d 文件 | make -n 看不到编译行,ls build/*.d 为空 | 加 -MMD -MP 与 -include |
make 每次都全量重编 | 目标被误标 .PHONY,或先决条件是目录 | make -d 搜索 “is newer than” | 去掉误标的 phony,把目录依赖改成 order-only |
| 消费者编译找不到头文件 | target_include_directories 用了 PRIVATE | cmake --build build --verbose 看编译行有无 -I | 改为 PUBLIC 或 INTERFACE |
消费者链接报 undefined reference | 库的依赖没有传播给链接者 | ninja -v 看最终链接行缺哪个 -l | 给库加 PUBLIC 的 target_link_libraries |
新增 .c 后 CMake 不编译 | file(GLOB) 的结果被配置期缓存 | 重新配置后才出现该文件 | 显式列源文件,或给 glob 加 CONFIGURE_DEPENDS |
cmake --preset 报 Could not read presets | JSON 语法错,或 version 与字段不匹配 | cmake --list-presets,python3 -m json.tool | 修正 JSON 与 version 字段 |
find_package(foo CONFIG) 找不到 | 没导出包配置,或 CMAKE_PREFIX_PATH 未指向安装前缀 | 查安装树有无 lib/cmake/foo/fooConfig.cmake | 补 install(EXPORT),设置前缀或 foo_DIR |
4.2 可观测信号
Make 侧先看它准备执行什么:make -n 打印命令而不执行,make -p 输出完整规则与变量数据库,make -d 打印 mtime 比较与规则搜索过程。CMake 侧先看配置阶段:cmake --trace-expand 打印每条命令的展开结果,--log-level=DEBUG 给出查找细节,--build --verbose 打印真实编译与链接行。CMakeCache.txt 记录生成器与缓存变量,compile_commands.json 记录每个 TU 的完整命令行。
4.3 安全 / 性能 / 一致性边界
- 时间戳不是内容哈希:NFS、时钟漂移与
touch都会让 Make 误判;Ninja 同样基于 mtime,只是记录更精确。 - 并行安全:
make -j不会自动串行化共享资源的配方;两个目标同时写同一个生成文件会得到损坏产物,应拆成显式依赖。 - 配置期与生成期:CMake 的
if()、foreach()在配置期求值,$<TARGET_FILE:...>这类生成器表达式在生成期求值;把两者混用是“配置时变量为空”的常见原因。 - 环境不入库:preset 只固化参数,不固化编译器版本、环境变量与 sysroot;CI 应在 preset 之外显式固定工具链。