1. 先用一个场景搞清楚Makefile到底解决什么问题1.1 手动编译的痛你一定经历过假设你正在写一个C语言项目文件不算多也就main.c、utils.c、data.c加上几个头文件。第一版程序只有一个文件的时候编译就是一条命令的事gcc main.c -o app但文件一多事情就变味了。每改完一个文件你要么重新敲一遍那条越来越长的gcc命令把所有源文件都列上去要么用上下箭头在历史记录里翻找。这还没完等你把项目分成了src、include、build几个目录甚至加上了第三方库的链接参数那条命令能长到终端自动换行gcc -Wall -Iinclude -Isrc -Llib -lmylib src/main.c src/utils.c src/data.c -o app每次编译把十几个文件全部重新编一遍小项目还能忍文件过百、过千之后一次全量编译可能要几分钟。中间改了一行代码还要等这么长时间人是会疯的。Makefile就是用来解决这件事的。它本质上是一个带依赖关系的批处理脚本。你告诉make最终要生成什么东西目标这个东西依赖哪些文件以及有了这些文件之后怎么把它造出来命令。make会自己去检查文件的时间戳哪些文件比目标新说明改过了只重新编译这些文件相关的那部分其余的直接跳过。1.2 从命令集合到工程工具理解make的工作原理我第一次接触Makefile的时候以为它就是把编译命令存成一个文件省得每次手敲。这个理解不能说错但严重低估了它。Makefile里真正值钱的是依赖关系命令反而是次要的。make的工作逻辑说白了就两步检查依赖执行规则。每条规则的结构是这样的目标: 依赖 命令当你在终端里输入makemake会找到文件中定义的第一条规则检查这条规则的目标文件是否存在。如果存在再检查它的每一个依赖文件是不是比目标文件更新。只要有一个依赖比目标新就说明源文件被改过了目标已经过期然后执行规则里的命令去重新生成目标。这个逻辑用一句话总结目标过期了就重建它。刚开始接触的人容易被目标这两个字带偏。目标不一定非得是编译出来的可执行文件它可以是一个中间产物比如.o文件也可以是一个纯粹的标签比如clean甚至可以是一个在真实文件系统里不存在的名字。这些假目标make里叫伪目标后面我会详细讲这是新手容易踩坑的地方。1.3 最小化认知模型目标、依赖、命令我权衡了很久觉得用一个生活化的类比来解释会比较容易理解Makefile的规则就像一份菜谱的最终成品。目标是一道菜依赖是做这道菜需要的原材料命令是烹饪步骤。你可以做一次拍黄瓜也可以先做一份腌黄瓜半成品再拿半成品去做凉拌黄瓜——这正好对应了编译阶段里的源文件-目标文件-可执行文件。C语言项目里最典型的链路是这样的main.c utils.h - main.o utils.c utils.h - utils.o main.o utils.o - app第一条规则生成main.o它的依赖是main.c和utils.h第二条规则生成utils.o第三条规则把两个.o文件链接成最终的可执行文件app。当你改了utils.c只有第二条规则会触发main.c不会重新编译main.o也不会重新链接——除非你动了utils.h或者main.c本身。这套依赖时间戳的机制就是make几十年来一直没被淘汰的根本原因。它不用人操心哪些文件要重编make自己心里有数。2. 半小时上手从零写一个能跑的Makefile2.1 最简单的单文件示例这一版的目标就一个字跑通。我建议所有新手第一步都从单文件开始不要一上来就写什么复杂变量、函数、自动依赖生成不然学的是语法不是逻辑。先建一个目录放一个main.c#include stdio.h int main(void) { printf(Hello Makefile\n); return 0; }在同一个目录下创建一个文件名字叫Makefile注意M大写内容如下app: main.c gcc main.c -o app终端里直接执行make$ make gcc main.c -o app目录下就多出一个app可执行文件。这个Makefile里app是目标main.c是依赖gcc main.c -o app是命令。命令前面那个空格必须是一个Tab字符不是几个空格这是Makefile语法里最让人高血压的地方下面我会专门说。此刻再看一眼目录你会发现make没有额外做什么高深操作。但如果你再执行一次make结果就不一样了$ make make: app is up to date.make检查了app的时间戳发现它比main.c新目标没有过期所以什么都不干。这就是增量编译的雏形。注意第一次执行make前目录里没有app这个文件。目标不存在make认为目标需要被生成直接执行命令。这是另一个常见认知误区——不是文件过期了才执行命令而是文件不存在或者比依赖旧两者都触发重建。2.2 引入变量和自动变量摆脱重复劳动单文件版本跑通之后你很快会碰到第一个让人烦躁的点main.c改个名或者加几个源文件Makefile里要改好几处地方。这时候就需要变量了。变量在Makefile里的写法和shell有点像但不用加$赋值的时候不用CC gcc CFLAGS -Wall -Iinclude app: main.c utils.c $(CC) $(CFLAGS) main.c utils.c -o app有了CC和CFLAGS换编译器只要改一行比如改成clang。加编译参数也只动CFLAGS。这是Makefile里最基础的抽象也是DRYDont Repeat Yourself原则在构建脚本里的体现。再进一步你会发现命令里把目标名和依赖名写死依然很笨。make提供了一组自动变量来解决这个问题$代表当前规则的目标名$^代表当前规则的所有依赖名$代表当前规则的第一个依赖名上面的规则可以改成app: main.c utils.c $(CC) $(CFLAGS) $^ -o $$^自动展开成main.c utils.c$自动展开成app。以后加源文件只需要改依赖那一行命令不用动。一个特别容易踩的细节我多说一句自动变量只能在命令部分使用不能在依赖部分用。你写$: $^这种规则头make是不会按你想的那样展开的。依赖部分要用别的写法后面讲模式规则的时候会提到。2.3 伪目标clean、all、install这些约定写了几次Makefile之后大家都会约定俗成地加上几个标签式目标。最常见的几个是all默认构建全部内容clean清理编译产物install把程序安装到系统目录注意这些目标和真实的文件没有任何对应关系。比如说clean你期望的行为是调用它就把.o文件和可执行文件删掉而不是创建一个叫clean的文件。但make不这么想它看到clean没有依赖且不存在同名文件执行一次命令之后还是会去检查clean这个目标是否比依赖新。实际操作中真是有人被这个坑过目录里恰好放了一个名为clean的文件或者某次编译意外生成了clean之后再运行make cleanmake只会在终端提示$ make clean make: clean is up to date.命令根本不执行。解决办法就是声明伪目标.PHONY: clean all install clean: rm -f *.o app.PHONY告诉make这几个目标不要拿文件系统去比较每次都老老实实执行命令。我见过不少新写的Makefile忽略这一行建议养成习惯凡是纯标签式的目标都挂在.PHONY下面。2.4 增量编译为什么make不会重复劳动讲到这里终于可以认真说说增量编译这件事了。它不只是一个效率优化技巧而是make存在的真正理由。考虑一个多文件项目它的编译链路是这样的每个.c文件先编译成.o。因为每个.o只依赖自己的.c和相关的头文件所以改动一个.c文件其他.o不受影响。最后把所有的.o链接成可执行文件所以只要有任何.o更新了链接这一步还得走一遍。用Makefile表达出来就是app: main.o utils.o data.o gcc main.o utils.o data.o -o app main.o: main.c defs.h gcc -c main.c -o main.o utils.o: utils.c utils.h defs.h gcc -c utils.c -o utils.o data.o: data.c data.h gcc -c data.c -o data.o clean: rm -f *.o app现在你改的是utils.cmake发现utils.o的依赖里utils.c比utils.o新于是重新编译utils.o。而main.c没动过main.o的依赖都比它旧不重编。链接这一步因为main.o、data.o虽然没变但utils.o是新的所以还是要重新执行链接命令生成新的app。这个流程你手动来做可能会偷懒直接gcc所有的.c文件重新编译全部。文件少的时候无所谓文件的编译时间分布不均的时候这种全量编译就很亏了。比如一个项目里有个巨大的模板头文件include它的源文件编译要30秒而你只改了一个平凡的小文件却要等那30秒白白过去。make的只做必要的事这一特性是整个构建系统的安身立命之本。你心里一定要有这个模型make不是帮你敲命令的工具是一个帮你省时间的依赖管理工具。3. 应对真实项目依赖、模式规则与函数3.1 多文件项目的依赖关系管理上一节最后那个多文件Makefile第一次看会觉得优雅第二次看就会觉得这几个.o的规则长得也太像了复制粘贴的痕迹过于明显。如果说变量的引入是为了消除命令里的重复那模式规则就是为了消除规则里的重复。模式规则的核心是百分号%。你可以把它理解成一个通配符它匹配文件名的一部分。比如%.o: %.c $(CC) $(CFLAGS) -c $ -o $这条规则的含义是任何一个.o文件都由同名的.c文件编译而来。这样上面的main.o、utils.o、data.o三条规则就可以合并成这一条不用再为每个文件单独写。但问题来了头文件的依赖怎么处理刚才的例子里面main.o依赖main.c和defs.h。如果只用模式规则%.o: %.c那make只知道main.o依赖main.c不知道它还依赖defs.h。这样当你改了defs.hmake不会重新编译main.o链接出来的程序可能用着旧的目标文件出现各种让人摸不着头脑的崩溃问题。这是一个极其经典的世界性难题还专门有个名字叫header dependency problem。业界常用的处理方案我列一下在Makefile里手工列出每个.o的头文件依赖。简单直接但头文件一多就维护不下去。利用编译器的-MM选项自动生成依赖。gcc/clang都可以在编译时顺便输出一个.d文件里面包含该.c文件实际include的头文件列表再把这个.d文件include进Makefile。不管头文件依赖每次都全量编译。省心但慢只适合玩具项目。方案2是实操中最常见的做法思路是给编译命令加上-MMD参数%.o: %.c $(CC) $(CFLAGS) -MMD -c $ -o $这样每个.o文件旁边会多出一个同名的.d文件。然后你在Makefile末尾加上一句-include $(OBJS:.o.d)先别管OBJS长什么样后面讲函数的时候会捋清楚。这个-include会把.d文件的内容本质是xxx.o: xxx.h这样的依赖规则合并进Makefile让make自动获得头文件层面的依赖关系。这是我在实操里认为最值得养成习惯的一个技巧。3.2 常用函数patsubst、wildcard、foreachMakefile里内置了不少函数语法上像这样$(函数名 参数)。我把日常用得最多、几乎每份正经Makefile里都会出现的几个拿出来讲讲。第一个是wildcard用来扩展通配符。一个典型的用法是把src目录下的所有.c文件都找出来SRCS : $(wildcard src/*.c)不加这个函数的话Makefile里的*.c是没法自动展开成文件列表的——make默认不会帮你把源文件列出来。第二个是patsubst作用是替换字符串模式。最常见的用途是把.c文件列表转换成.o文件列表OBJS : $(patsubst %.c, %.o, $(SRCS))这句的意思是把SRCS里所有%.c格式的文件名替换成%.o。其实还有一个更简便的写法我也经常用OBJS : $(SRCS:.c.o)效果和patsubst一样属于一种缩写语法。两种写法你选一个习惯的就行。第三个是foreach用来循环拼接。说实话foreach在日常小项目里用得不多但一旦涉及多目录、多模块它几乎是唯一的选择MODULES : core ui net SRCS : $(foreach dir, $(MODULES), $(wildcard $(dir)/*.c))效果是把core、ui、net三个目录下的所有.c文件拼成一个总列表。用这些函数整理一下上面的内容一个中等规模项目的Makefile核心框架大概长这样CC : gcc CFLAGS : -Wall -MMD -Iinclude SRCS : $(wildcard src/*.c) OBJS : $(patsubst src/%.c, build/%.o, $(SRCS)) DEPS : $(OBJS:.o.d) app: $(OBJS) $(CC) $^ -o $ build/%.o: src/%.c $(CC) $(CFLAGS) -c $ -o $ -include $(DEPS) .PHONY: clean clean: rm -rf build app注意build/%.o: src/%.c这种写法它把输出文件放在了build子目录源文件保持在src目录。前提是build目录要存在否则编译命令会报没有那个文件或目录。3.3 目录管理与mkdir的时机问题上面那个示例隐含了一个问题生成的可执行文件、中间.o文件如果都堆在根目录会显得很乱。把它们放进子目录是工程化的第一步但make不会自动创建目录你需要先mkdir。写法上有两种选择一种是在命令里加mkdir -p build另一种是利用make的先执行依赖规则的特性$(OBJS): | build build: mkdir -p build注意这里管道符|后面跟的是order-only依赖表示build这个依赖只影响执行顺序不影响是否过期的判断。意思就是make会先确保build目录存在但不会因为某个.o比build新就重复触发。说实话这个操作我在实际项目中经常看到有人用但对新手来说不好理解。我更推荐简单粗暴一点在clean之后手动mkdir或者直接在所有规则顶上先放一句$(shell mkdir -p build)。关于$(shell ...)它是Makefile里调用shell命令的方法。好处是简单直接坏处是每次解析Makefile都会执行一次不要在里面放昂贵操作。我自己的习惯是只放mkdir这种幂等且轻量的命令。3.4 头文件依赖一个容易翻车的细节上面讲模式规则时我提到过-MMD和-include $(DEPS)的组合。这里展开讲讲它为什么是必要的以及不这么做会怎么翻车。假如你的Makefile只写了%.o: %.c $(CC) $(CFLAGS) -c $ -o $编译main.o的时候它include了defs.h。有一天你改了defs.h里的一个宏定义然后makemake会怎么处理它检查main.o的依赖只有main.c。main.c没改过main.o没过期。它不会重新编译main.o。链接时用的main.o还是旧宏定义编译出来的程序行为完全不可预期。轻则打了半天日志发现改了没生效重则出现各种崩随机变量。而且这个问题非常隐蔽因为你不一定记得自己动过头文件。等到你想起去排查往往已经浪费了不少时间。-MMD的优雅之处在于它把对头文件的实际跟踪交给了编译器自己。编译器最清楚main.c里include了哪些头文件让它把这些信息写进.d文件再让make去读取是真正意义上的自动依赖管理。# 生成的.d文件内容示例 main.o: main.c include/defs.h include/common.hmake看到这一行依赖规则就知道main.o依赖哪些头文件。你再清理的时候记得把.d文件也删掉养成这个习惯。4. 高频报错排查让错误不再劝退新手4.1 make: *** 没有指明目标并且找不到 makefile ——从源头上解决这个报错可以算得上新手劝退第一名也是各大搜索平台上关于make的常见提问。完整报错信息分两行make: *** 没有指明目标并且找不到 makefile。 停止。 make: *** No targets specified and no makefile found. Stop.或者你会看到类似的make: 进入目录 /path/to/project make: *** 没有指明目标并且找不到 makefile。 停止。原因只有两种而且都比较直接当前目录下确实没有Makefile或makefile这个文件。文件存在但名字不对比如写成了Makefile.txt、makefile.txt、makeFile。排查顺序我建议照这个走用ls -l看看当前目录有什么文件。不要盲目自信很多编辑器默认新建文件的类型可能是纯文本保存的时候自动加了.txt后缀。Windows用户特别容易遇到因为你从记事本、某些IDE的默认模板里新建文件时后缀名是隐藏的。确认文件名是大写M的Makefile还是小写m的makefile。Linux下两个文件是不同文件make的查找顺序是GNUmakefile、Makefile、makefile优先用Makefile。我自己只用Makefile全项目统一省得任何混淆。如果你在别的目录下记得cd到项目目录或者用make -C /path/to/project指定目录。还有一种变体是你有Makefile但里面写的第一个目标不存在。比如你是想执行make run但Makefile里没有名为run的规则报错就不太一样make: *** No rule to make target run. Stop.翻译过来是没有规则能生成run。这个和第一种的区别在于make已经找到了Makefile只是找不到目标。听到这里你就明白了凡是让你找Makefile的报错先往文件存在性上查基本一查一个准。报错信息经常是英文的很多人看见英文就慌其实翻译成白话就是make也不知道该干什么。它进来一看当前目录没有Makefile那它连第一个规则都读不到自然只能喊你让我干活但活在哪里4.2 missing separator ——标题和命令之间必须是Tab这个报错也很经典所有Makefile新手基本都会碰上一次Makefile:2: *** missing separator. Stop.或者更直白一点Makefile:2: *** recipe commences before first target. Stop.原因都是同一件事规则里的命令没有用Tab开头。Makefile的语法规定规则头目标:依赖和命令之间命令行的第一个字符必须是Tab字符不是空格不是四个空格不是Visual Studio Code自动插入的那种四空格等价缩进。为什么会有这么别扭的设计说白了就是历史遗留。make在上世纪七十年代设计出来当时的编辑器里Tab就是个普通字符程序员也习惯用Tab缩进。今天很多现代编辑器默认把Tab转换成空格反而让Makefile学习者悔不当初。解决方案有两个在编辑器里设置插入空格时保留Tab或者直接针对Makefile文件类型关闭tab自动转空格。报错了之后把命令行开头那几个空格删掉然后按一下Tab键。注意Makefile允许命令前面有多个Tab只要第一个字符是Tab就行。另外我补充一种极端情况规则里如果写了命令但命令那一行是空白的或者只有空格make也会报错。命令行可以留空但不建议这么干可读性太差了。排查技巧在终端里用cat -A Makefile查看文件内容Tab字符会显示成^I空格不会被转换成^I。这样一眼就能看出来哪一行用的是空格哪一行用的是Tab。4.3 其他高频排查场景速查除了上面两个出镜率最高的我整理一个高频报错排查表都是我平时答疑或者在真实项目里见过的场景报错信息可能原因排查方向make: Nothing to be done for all目标依赖不存在或目标已经最新检查目标下有没有依赖文件如确认需要重建可以make -B强制全部重建make: xxx is up to date目标比所有依赖都新确实无需重建试试touch某个源文件或者删掉目标文件再makeerror: file path xxx does not exist编译命令里引用的文件路径有误检查路径大小写、目录层级linker input file not found链接时找不到.o文件看看是不是编译阶段没生成.o还是OBJS变量没正确赋值multiple definition of main多个源文件里都定义了main函数确认只有一个入口文件或者用了条件编译undefined reference to xxx链接时找不到函数实现查函数名拼写检查是否漏加链接库参数permission denied可执行文件没执行权限检查umask和目录权限必要时chmod xclang: error: no such file or directory编译环境路径配置有误查CFLAGS、CPPFLAGS里有没有写错include路径每次排查Makefile问题我的建议始终是先把报错信息完整地看一遍不急着改文件。报错里通常带着文件名和行号比如Makefile:12它明确告诉你是第12行有问题。绝大多数问题其实不值一提只是第一次见的时候会慌。再补充一个很实用的技巧如果编译命令太复杂你懒得手工一遍遍试可以用make -n。它会把make接下来要执行的命令打印出来但不真正执行。这样你可以快速确认make的心意是什么排查思路会清晰很多。5. 一些值得收藏的实操经验调试、工具与生态5.1 调试技巧make -n、make -d 和make --debug上一节结尾提到了make -n这个我在实战里用得非常频繁。它的全名是dry run只打印命令不执行。每当我想确认make到底准备干什么的时候就先跑一下-n看看输出对不对。比如$ make -n gcc -MMD -c src/main.c -o build/main.o gcc -MMD -c src/utils.c -o build/utils.o gcc build/main.o build/utils.o -o app完美这就是我预期的行为。如果输出里多了一条或者缺了一条那问题多半出在依赖关系上。再看一个参数make -d全称是debug会输出极其啰嗦的调试日志包括make认为哪些文件存在、哪些文件过期、它是怎么决定要不要执行命令的。这个日志巨长新手第一次看会被吓到。它适合的情况是你已经确认make -n的输出不对但不知道make为什么会有这个判断思路这时候用make -d看它的决策过程。实际操作中我建议对着make -d的输出搜索几个关键词Must remake target表示make决定重建某个目标Considering target表示make在评估某个目标的依赖。还有一个实用参数是make -p它会把Makefile解析之后的所有变量、规则、内置函数全部打印出来适合确认某个变量的值到底是什么。一般来说先用-n再用-p最后才考虑-d。最后补一个参数make -B这个在某些场景下救过我它无视时间戳强制把所有目标都当成过期全部重新构建。适合你确认Makefile逻辑没问题只是想全量重编的时候。5.2 自动生成Makefile的工具autotools与CMake总有一部分人写Makefile是被逼的他们真正想要的是一个能自动生成Makefile的东西。业界历史悠久的一套是autotoolsautoconf/automake/autoheader你只需要写一个configure.ac和Makefile.am然后跑几条命令就能生成一套标准的Makefile和configure脚本。但说实话autotools的曲线很陡模板文件写起来不比Makefile简单多少而且生成的代码量巨大理解成本高。我更推荐的入门路径是CMake。它本身不是make但大多数项目里最终都会生成Makefile文件或者Ninja的构建文件。CMake的语法比Makefile更高级一点跨平台特性也好很多。它的核心思路是你写一份CMakeLists.txt描述项目的目标、源文件、依赖库cmake程序根据这份描述自动生成适合当前平台的构建文件。对比一下用CMake生成一个可执行文件只需要几行cmake_minimum_required(VERSION 3.16) project(MyApp C) add_executable(app src/main.c src/utils.c src/data.c ) target_include_directories(app PRIVATE include)然后执行mkdir build cd build cmake .. make这个流程比手工写Makefile要省事得多而且CMake生成的构建系统能处理跨平台、多编译器、依赖库查找等一堆麻烦事。我可给的直接建议是你只想在C/C项目里快速搞定构建不想折腾直接学CMake你想理解构建的本质是什么或者你的工作环境必须手写Makefile比如嵌入式开发的某些场景那本文学到的Makefile语法就派上用场了大型项目里Makefile和CMake经常是共存的CMake生成MakefileMakefile只是幕后干活的那一个。时代变了很多但make这套依赖时间戳的核心思想被CMake、Ninja这些新一代工具继承了个遍。你把Makefile学明白了理解其他构建工具也会快很多。5.3 写Makefile的一些通用规范与习惯最后分享几个我自己写Makefile时的习惯和规范。这些不一定都是官方要求的但长期来看能让自己以及接手你代码的同事少吃苦头。第一个习惯目标之间要分层。我会定义一个all目标作为默认构建入口避免直接把第一个可执行文件当成默认目标。这样任何人执行make行为是可预期的。对应的clean目标要把所有中间产物清理干净.d文件别忘了。第二个习惯变量名起得有意义。CC、CFLAGS这种约定俗成的别乱改自定义变量如SRCS、OBJS、DEPS放在文件顶部集中管理加注释说明用途。不要像某些反面教材一样在文件中间突然冒出个赋值。第三个习惯尽量用自动变量。命令部分写$、$^少写死目标名和依赖名这样小改依赖列表的时候命令部分往往不用动。第四个习惯给伪目标都挂上.PHONY。善用声明避免和同名文件撞车。第五个习惯不要把Makefile当成万能胶。如果项目的构建逻辑越来越复杂开始出现大段shell脚本、循环、条件判断嵌套的时候是时候考虑换CMake或者更现代化的构建系统了。Makefile擅长的是依赖管理不是一门通用编程语言。从个人经验来说Makefile这个技能属于那种写了才知道哪些坑在哪里的东西。光看文档不实际编译几次永远记不住Tab和空格那点事。你只需要亲手写一个两三文件的小项目把变量的用法、模式规则、伪目标、自动变量这几个核心概念过一遍之后再看任何项目的Makefile都不会觉得是无字天书了。我目前带过的团队里不少新人上手时都在报错处理上卡过壳。这类问题没有捷径多敲几次把错误收集起来慢慢就会形成自己的排查直觉。说到底构建工具的本质只是让重复劳动变少一点把时间留给真正需要人来做的创造性工作。你可以把它当作一个起点后面无论接触Ninja、Bazel还是其他构建系统底层的这套依赖追踪思路都不会过时。