通用Makefile编译脚本：模板设计、常见报错与CMake选型

做过几年 C/C 开发的人大概都经历过这样一个阶段项目里的编译命令从一两条 gcc 渐渐膨胀成十几条每次加一个源文件都要手动改脚本稍不留神就会漏掉某个文件链接时冒出一堆 undefined reference。我开始捣鼓 makefile 便捷编译脚本就是被这种重复劳动逼的。如果你现在还在拿一长串 gcc 命令硬扛日常编译或者已经被 makefile 的语法坑到怀疑人生这篇内容大概率能帮到你。我会从为什么会需要编译脚本讲起给出一个可以直接抄走的通用 makefile 模板然后重点分享我在 Linux 和 Vitis 环境下实际踩过的几个编译报错以及完整的排查思路。1. 被一长串 gcc 命令逼出来的编译脚本需求1.1 从一长串 gcc 命令说起几年前我刚接手一个 Linux 下的 C 项目时编译方式是打开一个 build.sh里面是一大段 gcc 命令大概长这样gcc -g -Wall -I./include -I./lib/foo/include \ src/main.c src/parser.c src/utils.c \ lib/foo/src/foo.c lib/foo/src/bar.c \ -L./lib/foo -lfoo -lm -lpthread \ -o bin/app看起来还能看懂问题是只要新增一个 .c 文件就得手动往这行里加改了某个公共头文件整个工程都得重新编要切换 debug 和 release 模式又要去改 -O2、-g 这些参数。最让人崩溃的是某个老模块被移除后命令里的源文件列表和实际目录对不上链接时会给你来几个 undefined reference而你还得在一长串 gcc 参数里人肉定位问题。我被这种状态折磨了大概两周决定改用 makefile 来做编译脚本。原因很简单make 本身就是一个专门管理目标、依赖和命令的工具它的核心能力不是帮你少打几个字而是帮你把什么东西依赖什么、什么东西变了之后应该重编这件事搞清楚。而这恰恰是 C/C 项目编译最头疼的部分。1.2 Makefile 到底帮你解决了什么先看一个最朴素的 makefileapp: main.c utils.c gcc -o app main.c utils.c当你在终端执行 make它会检查目标 app 是否存在再对比它和依赖文件 main.c、utils.c 的修改时间。如果 app 不存在或者任何一个 .c 文件比 app 新就执行规则里的 gcc 命令重新生成 app如果 app 已经是最新状态就提示 nothing to be done。这就是 make 的根本逻辑以文件时间戳为核心自动判断哪些工作需要重做。对几十个源文件的项目来说这种增量编译带来的时间节省非常可观。我跑一次全量编译可能要五分钟改动一个文件后用 make 只需要十几秒这是便捷的第一层含义。第二层含义是自动化。借助 makefile 里的变量、函数和模式规则你可以把收集源文件、生成目标文件、链接成品这些重复动作交给 make 去做而不是每次手动罗列文件名。1.3 我对便捷编译脚本的四个硬性要求设计自己的通用 makefile 编译脚本时我给它定了几个硬性要求后面所有调整都围绕这些要求展开新同事拿到代码后执行 make就能编译出可执行文件不需要额外读文档新增源文件不需要修改 makefile通过通配符自动收集支持 debug 和 release 两种模式用一个变量切换支持清理中间文件、运行程序等常见操作并有 help 提示。后来的脚本基本达到了这些要求。下面我把通用模板的设计和踩坑过程完整拆开讲包括可以直接抄走的部分以及我在 Vitis 工程和纯 Linux 环境下实际遇到的三类报错。2. 通用 Makefile 的骨架变量、目标与模式规则2.1 把所有可变参数收敛为变量写 makefile 的第一个习惯不要到处散落路径和参数把所有可能变化的东西都收敛成变量。我常用模板的开头长这样TARGET : app CC : gcc CFLAGS : -Wall -Werror -g -O2 CPPFLAGS : -I./include LDFLAGS : -L./lib LDLIBS : -lm -lpthread SRCDIR : src OBJDIR : build BINDIR : bin这里有几个细节值得说明。TARGET 是最终可执行文件名CC 是编译器CFLAGS 是编译选项CPPFLAGS 一般放头文件搜索路径LDFLAGS 放库搜索路径LDLIBS 放具体要链接的库。这些变量名不是随便起的它们是 make 内置约定的一部分。虽然你完全可以自定义名字但用标准命名有个好处make 的很多隐式规则会自动引用它们你的 makefile 会和内置规则配合得更好。SRCDIR、OBJDIR、BINDIR 则把源码、中间文件、最终产物分开。我见过太多项目把所有 .o 文件堆在 src 目录里最后想清理都不知道哪些文件是构建产生的。分开之后执行 rm -rf build bin 就能干净收场。2.2 第一个目标与常用目标怎么排make 默认执行 makefile 里出现的第一个目标所以通常会把 all 放在最前面让它依赖最终产物all: $(BINDIR)/$(TARGET) $(BINDIR)/$(TARGET): $(OBJS) mkdir -p $(BINDIR) $(CC) $(CFLAGS) $^ -o $ $(LDFLAGS) $(LDLIBS) clean: rm -rf $(OBJDIR) $(BINDIR)注意链接命令里的 前缀它表示执行命令时不在终端回显这条命令本身只显示结果让输出干净一些。而 mkdir -p 的作用是确保 bin 目录存在避免因为目录缺失导致链接失败。clean 规则很简单但有个常见坑如果当前目录恰好存在一个叫 clean 的文件makefile 里的 clean 规则会被 make 当成重建这个文件来对待于是执行 make clean 时会提示 nothing to be done。解决方案是显式声明伪目标.PHONY: all clean我见过不少新人在这个上面卡很久明明写了 clean 规则make clean 却不干活十有八九就是忘了 .PHONY。2.3 wildcard、patsubst 和模式规则是怎么让脚本自动化的要让 makefile便捷关键一步是自动收集源文件而不是手动一个文件一个文件地列。我常用这样几行SRCS : $(wildcard $(SRCDIR)/*.c) OBJS : $(patsubst $(SRCDIR)/%.c,$(OBJDIR)/%.o,$(SRCS)) $(OBJDIR)/%.o: $(SRCDIR)/%.c mkdir -p $(OBJDIR) $(CC) $(CPPFLAGS) $(CFLAGS) -c $ -o $上面用到两个常用函数wildcard把 src 目录下所有 .c 文件展开成列表。新文件加进去后不用改 makefile它会自动出现在 SRCS 里patsubst把 src/main.c 这样的路径替换成 build/main.o从而得到目标文件列表 OBJS。模式规则%.o: %.c则代替了手动为每个 .c 文件写规则的做法。里面的自动变量需要记一下$ 表示当前目标文件比如 build/main.o$ 表示第一个依赖文件比如 src/main.c$^ 表示全部依赖文件链接时常用到。还有一件非常重要的事规则里的命令缩进必须使用 Tab 键不能用空格。我第一次写 makefile 时在这个地方栽过跟头编辑器把 Tab 自动替换成了四个空格make 直接报 missing separator怎么看语法都对就是跑不起来。如果你想系统补充语法陈皓那篇《跟我一起写Makefile》虽然年代久远但核心概念到现在依然适用GNU make 官方手册则是查函数用法最权威的地方遇到不认识的函数先去那里查效率高得多。3. 让 Makefile 真正好维护的五个细节3.1 .PHONY 与伪目标前面已经提到 .PHONY值得再展开一次。用 .PHONY 声明的目标不会检查同名文件是否存在每次执行都会运行规则里的命令。除了 clean我还习惯把不需要产出文件的操作都声明为伪目标.PHONY: all clean run install help run: $(BINDIR)/$(TARGET) ./$(BINDIR)/$(TARGET) help: echo make 编译项目 echo make clean 清理中间文件 echo make run 编译并运行run 目标依赖最终产物所以直接执行 make run 会先编译再运行省去手动两步操作。help 目标则用来打印使用说明新同事不用问人看输出就知道有哪些命令。我习惯把 help 放在显眼位置作为默认的入门指引。3.2 头文件依赖自动生成MMD 与 -include前面说过make 靠时间戳判断是否重编但这里有个大坑如果规则里没有声明头文件依赖那么头文件改动后对应 .o 文件不会重新编译。最初我的模板里只写了%.o: %.c后来一个同事改了公共头文件项目里出现了非常诡异的现象——有些文件用了新接口有些还在用旧的链接时一片 undefined reference。排查了很久才意识到是头文件依赖缺失。解决方案是让编译器自动生成头文件依赖关系在 CFLAGS 里加两个参数CFLAGS -MMD -MP -include $(OBJS:.o.d)-MMD 会在编译每个 .c 文件时生成同名 .d 文件里面记录了这个源文件包含的头文件列表-MP 则生成一些空规则避免头文件被删除时 make 报错。-include 会在下一次执行 make 时把这些依赖规则加载进来。这样做之后头文件一改所有依赖它的 .o 都会自动重编完全不用手动维护依赖清单。这个技巧几乎是我向所有同事推荐名单里的第一名它把 makefile 从半自动变成了真自动。3.3 子目录分层构建时别用裸 make当项目里有多个独立模块时一个 makefile 管理所有文件会越来越难维护。我现在的做法是分两层每个子模块目录放自己的 makefile负责生成静态库 libxxx.a顶层 makefile 递归调用这些子模块最后统一链接。递归调用的方式要特别注意libs: for dir in $(SUBDIRS); do \ $(MAKE) -C $$dir || exit 1; \ done这里必须用 $(MAKE) 而不是裸的 make。因为 $(MAKE) 会自动带上当前命令行的参数比如 -jN 并发参数保证子 make 和父 make 的行为一致。如果写成裸 make在并行构建时子模块可能不会按照预期并发甚至可能丢失一些环境变量。3.4 Debug 与 Release 的切换不掉进参数地狱我习惯在 makefile 顶部留一个构建模式变量方便切换BUILD_MODE ? release ifeq ($(BUILD_MODE),debug) CFLAGS -g -O0 -DDEBUG else CFLAGS -O2 -DNDEBUG endif? 表示如果用户在命令行没有覆盖就使用默认值。需要 debug 版本时执行make BUILD_MODEdebug如果不想让 debug 和 release 的产物互相覆盖可以把中间目录也区分开OBJDIR : build/$(BUILD_MODE) BINDIR : bin/$(BUILD_MODE)这样做的好处是在 debug 和 release 之间来回切换时不需要每次都 clean两个版本的 .o 文件互不干扰编译速度会快很多。3.5 同名文件的坑Makefile 与 makefilemake 默认在当前目录按顺序寻找 GNUmakefile、makefile、Makefile 三个候选文件名这就带来一个小坑在 Linux 下makefile 和 Makefile 是两个完全不同的文件。有一次同事在目录里同时放了 Makefile 和 makefile修改新文件后运行 make 却没有任何反应检查很久才发现 make 优先匹配的是 makefile走的是旧规则。这个坑非常隐蔽因为 ls 列目录时两个文件都能看到名称差异又小很难引起注意。我的建议是项目里只保留一个 Makefile并且用版本控制忽略另一个候选名从源头上避免这种无意识踩坑。4. 踩坑实录三种高频报错的完整排查链路4.1 没有目标、找不到 Makefile新手最常见的报错make: *** No targets specified and no makefile found. Stop.这句话拆开看有两层意思一是 make 在当前目录没有找到任何候选的 makefile 文件二是也没有通过命令行参数指定目标。常见原因包括当前目录压根没有 Makefile或者文件名拼错你在子目录里执行 make但 makefile 在项目根目录刻意执行了 make app但 makefile 里定义的目标叫 all不叫 app执行 make 时没有把 Makefile 文件加入版本控制别人拉代码后根本没有这个文件。排查步骤很简单先 ls -la Makefile 确认文件存在再确认文件名是 Makefile 而不是 makefile最后用 grep 查看目标名是否匹配。这类问题容易解决真正让我困扰更久的是下面这种多级 make 环境下冒出的报错。4.2 Vitis 报错 make[2]: *** [makefile:18: libs] Error 1 的排查那段时间我在 Xilinx Vitis 环境里集成第三方库构建时总看到这个输出make[2]: *** [makefile:18: libs] Error 1第一次见到时我被 make[2] 这个编号弄得很懵。后来才搞清楚make[2] 表示当前正在执行的是第三层 make编号从 make[0] 或 make[1] 开始也就是说这个 make 是被上一层的 make 递归调起来的。报错里的 makefile:18 指的是这个子 makefile 的第 18 行libs 是当时正在构建的目标名。这类报错里真正有用的信息其实在 Error 1 之前。Error 1 只说明某个命令返回了退出码 1然后 make 就停止了。要找到原因必须继续往上翻完整构建日志直到看见第一条真正的错误信息。我在那次排查中把构建输出重定向到文件然后用 grep 过滤make -j$(nproc) build.log 21 grep -n error build.log筛选后的日志里出现了这样一行gcc: error: lib/foo.a: No such file or directory也就是说libs 目标试图链接的静态库根本没有被构建出来或者库文件名和实际产物不一致。继续查子模块发现子模块生成的是 libfoo.a而顶层 makefile 里写的是 libfoo.so两边对不上链接时自然找不到文件。修正库名后make[2] 的报错就消失了。提示Error 1 只是结果不是原因。排查多级 make 报错时一定要跳过Error 1往前看找到第一个真正报错的位置。Vitis 这类多级构建环境尤其如此每一层 make 都可能只把最后一行的退出码透传上来。4.3 链接顺序引发的 undefined reference另一个高频问题链接时提示一堆 undefined reference但肉眼查看库文件确实存在于指定目录。这种情况八成和链接顺序有关。静态库链接器的处理原则是只提取能解析当前未定义符号的目标文件并且按从左到右的顺序扫描。如果你的库写在源文件之前扫描到库时还没有未解析的符号表那这个库里的目标文件不会被提取等到扫描完源文件发现未定义符号时链接器已经扫过库的位置不会自动回头。所以有这两种写法# 错误示范库在源文件前面 $(CC) -lfoo src/main.c -o app # 正确写法源文件在前面库跟在后面 $(CC) src/main.c -lfoo -o app我在通用 makefile 里把 LDLIBS 放在命令末尾就是为了天然满足这个顺序要求$(CC) $(CFLAGS) $^ -o $ $(LDFLAGS) $(LDLIBS)如果遇到两个库互相依赖的循环场景同一个库可能需要重复出现LDLIBS : -lfoo -lbar -lfoo这种写法看着别扭但在老项目的遗留代码里确实有效知道怎么回事就好。4.4 三板斧make -n、make -d、打印变量遇到 make 行为不符合预期我常用的排查工具是这三个。第一板斧是 make -n它只打印将要执行的命令不会真的执行。用来确认 make 将要运行哪些命令最合适能快速发现变量没传进去、目标名写错这类问题。第二板斧是 make -d它输出大量调试信息展示 make 做了哪些判断。信息量很大一般我会配合 grep 使用只看自己关心的部分。第三板斧最直接在 makefile 里加一个打印变量的目标print-vars: echo OBJS $(OBJS) echo CFLAGS $(CFLAGS)然后执行 make print-vars一眼就能看出文件列表有没有收集全、编译选项是否如预期。这三板斧组合下来大部分make 为什么不按我想的跑的问题都能定位。我甚至在几个日常用的 makefile 里常驻了 print-vars 目标想查变量时随时执行。5. Makefile 与 CMake 的选型判断什么时候别硬扛5.1 Makefile 与 CMake 的本质差异很多被 Makefile 折腾过的人转头就想用 CMake。先把两者的区别说到底。Makefile 是规则驱动你告诉 make目标文件依赖哪些文件、怎么从依赖生成目标增量判断交给 make。CMake 是目标驱动你告诉 CMake我要构建一个可执行文件 app它由哪些源文件组成需要链接哪些库CMake 会自己探测编译器、平台差异然后为当前平台生成对应的构建文件。在 Linux 上它生成的往往就是 Makefile。所以准确的表达是Makefile 是构建脚本本身CMake 是构建脚本生成器两者不在同一层。这个差异决定了它们的使用方式完全不同维度MakefileCMake本质构建规则本身生成构建规则的工具语法风格目标、依赖、命令声明目标、源文件、依赖跨平台依赖本机 make 实现生成对应平台构建文件依赖探测手动维护或 .d 文件find_package 自动探测增量编译原生时间戳机制委托给生成的构建文件上手门槛语法简单但坑多概念先学一遍后续更省心5.2 什么场景继续用 Makefile我个人的判断标准很清楚项目代码量在几条命令能说清楚的范围直接用 Makefile别引入多余工具团队所有人都熟悉 make项目只跑 Linux没有跨平台需求做嵌入式固件、内核模块这类底层开发交叉编译工具链本身就集成 make 流程只需要简单的编译、清理、安装没必要为 CMake 付出学习和配置成本。在这些场景下一个好用的 makefile 编译脚本就是最顺手的工具。它没有额外依赖系统里本来就带 make可读性也不错。Vitis 里的嵌入式工程就是这样Xilinx 的工具链默认生成 make 流程我们只需要在外部包一层自己的脚本切换配置就够用了。5.3 什么场景应该切 CMake反过来遇到下面这些情况我会建议尽早切 CMake项目需要跨 Windows、Linux、macOS 构建甚至还要交叉编译到多个嵌入式平台依赖的第三方库很多需要用 find_package 自动探测库和版本有复杂的编译选项矩阵多种构建类型、多个编译器自由组合团队成员对 make 不熟但对 CMake 的声明式写法更容易理解除了编译还需要安装、打包、测试等更多自动化流程。CMake 生成 Makefile 之后你依然可以用 make 命令构建产物。所以从 Makefile 迁到 CMake并不是彻底换掉 make而是换了一层配置工具。5.4 我的建议配置层与构建层分开看从我实际操作项目的体会来说Makefile 和 CMake 不是非得二选一。我更倾向于这么组合中小型自研模块、内部工具维护一个精简 Makefile满足编译、清理、运行三个目标简单直接面向交付、跨平台、依赖复杂的产品级项目用 CMake 做配置层生成 Makefile 或 Ninja 构建文件构建时照常用 make 或 ninja 执行嵌入式 Vitis 工程以 Vitis 生成的 make 流程为主只在外部包一层统一脚本方便团队切换配置。也就是说Makefile 不是过时的老古董CMake 也不是银弹你需要的是把编译这件事管好的能力而 Makefile 恰好是这个能力最底层的抓手。对我来说写好一个通用 makefile 编译脚本比学会更多花哨的构建工具更能解决日常 80% 的编译焦虑。最后再分享一个小技巧我习惯把 help 目标放在 makefile 顶部、all 之前这样任何人在项目里直接执行 make第一眼看到的是可用命令清单而不是一串看不懂的编译输出。记住便捷不是越复杂越好而是让人拿到手就能直接用这个原则对我写任何构建脚本都适用。