做过几年C/C开发的人多少都跟Makefile打过交道。它可能是你最早接触的构建工具也可能是你最想删掉重写的文件之一。刚入门时一堆目标、冒号、Tab键、变量看起来像某种古老的神秘语法可一旦理解它背后的逻辑你会发现Makefile无非是一套“谁变了就重新编译谁”的规则说明书。它不聪明但足够可靠几十年过去依然是无数项目自动构建的默认底座。这篇文章不打算做成学院派教程我从实际使用角度把它拆开讲清楚Makefile到底解决了什么问题、最基本的写法长什么样、怎么用CMake等工具生成一份像样的Makefile以及那个几乎所有人都会撞上的报错——make没有指明目标并且找不到makefile到底是怎么发生的怎么在一分钟之内解决。无论你是刚起步的初学者还是写了不少代码但一直没系统梳理过构建过程的开发者这篇内容应该都能让你少走几步弯路。1. Makefile的本质一套基于时间戳的构建规则1.1 从手动编译到自动化构建先想一个最简单的场景。你写了一个main.c想把它变成可执行程序第一反应是在终端敲gcc main.c -o app没问题一条命令搞定。但代码量上来之后事情就变了。你可能有十几个源文件每一次重新编译都要敲一长串命令。更难受的是你明明只改了一个文件却要把所有文件重新编译一遍小项目还好大项目光是编译等待时间就够喝杯咖啡的了。我最早接触的“准构建工具”是一段Shell脚本把编译命令按顺序写进去需要全量重建时执行一次。脚本能解决“命令太长、记不住”的问题但它有一个致命缺陷不智能。它无法判断哪些文件需要重编每次都是全量编译。项目一旦上了规模这种全量编译的效率低到让人抓狂。Makefile的出现就是来解决这两个问题的第一把编译链接的命令固化下来不用手动敲第二通过比较文件的时间戳只重新编译真正发生变化的部分。前者带来一致性后者带来效率。这个思路在今天看来朴素但在当时甚至现在都是构建系统最核心的命题。1.2 核心概念目标、依赖、时间戳Makefile的运行逻辑本质上是围绕“目标”展开的规则匹配。一条规则长这样目标: 依赖文件 命令所谓目标通常是你要生成的文件比如一个.o目标文件或者最终的可执行程序。依赖文件是生成这个目标所需的原料比如源文件和头文件。命令则是实际执行的编译、链接或处理操作。Make在运行时的决策逻辑只有一句话如果某个依赖文件比目标文件更新或者目标文件根本不存在就执行命令重新生成目标否则什么都不做。这个“比一比时间戳”的机制就是增量构建的根基。举个生活中的类比把目标想象成一份外卖订单依赖是食材命令是炒菜过程。只有当食材比外卖更新鲜比如刚买回来的菜你才有必要重新炒一遍如果食材是昨天买的菜也早炒好了那就直接端上桌不用再开火。理解了这一点再看Makefile就不会觉得它神秘。它其实是一堆“如果……就……”的条件规则而决定条件的依据不是代码内容而是文件的时间戳。这里要特别注意Make并不会真正去看文件内容有没有变化它只认时间戳。所以如果某个依赖文件的内容没变、但时间被touch命令改新了Make会照样重新执行编译命令。这个特性有时很讨厌但有时也能用来强制重建后面我会专门讲touch的妙用。1.3 为什么Makefile至今没有被淘汰你可能会问现在有了CMake、Ninja、Bazel这些更现代化的构建工具为什么还要学Makefile答案分两层。第一层Makefile是很多现代构建系统的底层依托。CMake默认生成的构建文件就是Makefile你运行cmake之后真正干活、真正执行增量编译的仍然是make。Ninja虽然不用Makefile但它的核心设计思路——声明依赖关系、按需重建——跟Make是一脉相承的。所以理解了Makefile再学其他构建工具会轻松很多。第二层Makefile本身在特定场景下依然无可替代。比如嵌入式开发、内核模块编译、一些小而快的命令行工具直接写一份Makefile比引入一套庞大的构建框架要清爽得多。它不需要额外的依赖只要系统里有make命令就能跑这种“零依赖”的特性在服务器、CI环境里非常吃香。当然Makefile的短板也很明显语法古老、调试困难、跨平台支持差。Windows下默认没有make得装GNU Make或者用nmake路径分隔符、Shell命令的差异也让人头疼。所以实际工程里很少看到大型项目直接裸写Makefile大家都倾向于用CMake等工具生成。但这不影响把Makefile本身学好因为它能帮你理解构建过程的底层逻辑。2. 写一个能跑的Makefile基础语法与核心技巧2.1 最简Makefile的三要素先看一个最基础的Makefile长什么样。假设项目只有两个文件main.c和utils.c头文件是utils.happ: main.o utils.o gcc -o app main.o utils.o main.o: main.c utils.h gcc -c main.c utils.o: utils.c utils.h gcc -c utils.c clean: rm -f app *.o这个例子麻雀虽小五脏俱全。第一条规则app: main.o utils.o告诉我们可执行文件app依赖两个目标文件下面两条规则分别是两个.o文件的生成方式最后一条clean不是生成文件而是用来删除编译产物的。这里有个极其重要的细节Makefile里的命令行前面必须是Tab键不能用空格代替。我见过无数新手包括我自己第一次写的时候在这里栽跟头终端弹出missing separator错误其实就是因为空格和Tab搞混了。如果你的编辑器默认把Tab转成空格请务必关掉这个设置或者直接在终端里用vim写Makefile。另一个细节是文件名的默认规则。make默认会找当前目录下名为Makefile的文件注意大小写M其次是makefile。如果两者都不存在它才会报那个经典的“找不到makefile”错误。所以如果你新建的文件叫makefile.txt或者叫MakeFile那make是找不到的。2.2 变量与自动变量别写重复代码上面那个例子虽然能跑但有个问题编译器、编译选项、文件名都是硬编码的。如果换了编译器或者加了编译参数你得改好几处。这时候就该用变量了。CC gcc CFLAGS -Wall -g app: main.o utils.o $(CC) $(CFLAGS) -o app main.o utils.o main.o: main.c utils.h $(CC) $(CFLAGS) -c main.c utils.o: utils.c utils.h $(CC) $(CFLAGS) -c utils.cCC和CFLAGS是Makefile里约定俗成的变量名前者表示C编译器后者表示编译选项。用$(CC)和$(CFLAGS)进行引用。你还可以用CPPFLAGS表示预处理选项用LDFLAGS表示链接选项。这些不是语法强制要求但遵循惯例会让你的Makefile更容易被其他人读懂。真正让Makefile摆脱重复劳动的是自动变量。自动变量的意思是在规则内部不用自己起名直接用Make预定义好的符号来代指目标、依赖等。最常用的有三个$当前规则的目标文件名$^当前规则的所有依赖文件列表去重$当前规则的第一个依赖文件用自动变量改写上面的规则app: main.o utils.o $(CC) $(CFLAGS) -o $ $^ main.o: main.c utils.h $(CC) $(CFLAGS) -c $ utils.o: utils.c utils.h $(CC) $(CFLAGS) -c $这样写的好处是规则的目标和依赖如果有调整命令部分往往不用动。你会发现很多开源项目的Makefile里到处是$和$^学会了这几个符号阅读别人的Makefile会顺畅很多。2.3 伪目标、默认目标与常见语法坑再回头看看刚才的clean。它不是一个真实存在的文件名它只是告诉Make去执行一条清理命令。如果恰好当前目录里有一个叫clean的文件make就会认为“目标已经存在且没有依赖不需要执行任何操作”然后clean规则就失效了这一点特别坑。解决办法是声明伪目标告诉Make这个目标不对应任何真实文件.PHONY: clean clean: rm -f app *.o.PHONY声明了clean之后不管目录里有没有同名文件make都会老老实实执行命令。建议把所有不生成文件的“动作型目标”都声明为.PHONY包括clean、install、test等这是经验之谈。另一个概念是默认目标。当你直接在终端运行make不带任何参数时它会选择Makefile里第一条规则的目标作为默认目标。所以一个约定俗成的习惯是把最终要生成的文件比如app写在第一个规则的位置。如果你希望用户执行make就拿到一个名为all的结果也可以显式写all: app把all放在第一行。这算是一个约定很多项目你敲make其实就是执行all。这里再说一个我踩过的坑规则里同一行的依赖顺序会影响$的取值。$只取第一个依赖而不是所有依赖所以如果你在引用$时把依赖顺序写错了编译就可能出错。要想引用全部依赖就用$^。这两个自动变量容易混但用熟了就不容易出错了。3. 生成Makefile的几条路径手写与自动生成3.1 手写Makefile的适用场景先做个判断什么样的情况下适合手写Makefile。我的建议是项目规模小源文件数量在个位到二三十个之间依赖关系简单不太需要复杂的条件检测只在固定平台、固定工具链下编译不想引入额外的构建系统依赖符合这些条件手写反而比用CMake更直接。比如我维护的一些小工具和算法demo就是一份简单的Makefile十来行搞定没有任何额外学习成本。但如果项目开始出现多个子目录、需要检测系统库是否存在、需要生成不同平台的不同版本手写Makefile就会变得极其痛苦。这种时候还坚持手写你写的维护成本会远高于编译本身节省的时间。3.2 用CMake生成Makefile的完整流程在Linux/macOS环境下用CMake生成Makefile是再常见不过的操作了。流程很简单先写一份CMakeLists.txt然后在终端执行cmake . -G Unix Makefiles make-G Unix Makefiles表示让CMake生成Makefile格式的构建文件。实际上Linux下cmake默认就是生成Makefile所以这段参数可以省略但显式写出来能帮助你理解CMake和Makefile之间的关系。来说说CMakeLists.txt最基础的写法。一个单可执行文件的C项目三行就够cmake_minimum_required(VERSION 3.10) project(demo) add_executable(app main.c utils.c utils.h)然后cmake .再make它就会生成Makefile并自动编译出一个app可执行文件。CMake的一大优势是它会自动处理很多Makefile里的琐碎细节比如头文件依赖。手写Makefile时如果你有一个头文件改了make不一定能感知到需要重编哪些.o因为你必须在规则里手动列出头文件依赖而CMake会扫描源文件包含的头文件并自动生成依赖关系这能省下一大批维护工作。那CMake生成的Makefile长什么样你可以打开看它往往几百上千行里面有一堆变量、函数调用、规则模板。直接读它确实令人头大但你要明白那是工具自动生成的一般不需要手工去改。使用CMake时还可以配置构建类型比如cmake . -DCMAKE_BUILD_TYPERelease make这样生成的就是带优化选项的Release版本。而Debug版本则带调试信息两者对应不同的编译选项CMake会在Makefile里自动处理好。3.3 还有哪些生成Makefile的方式除了CMake另外两类生成方式也需要知道。第一类是autotools体系也就是autoconfautomake。你会在很多Linux经典开源项目里看到configure脚本、Makefile.am、Makefile.in这些文件。标准流程是./configure makeconfigure会根据当前系统的实际情况生成Makefile从而适配不同Unix环境的差异。这种方式的优点是可移植性极强老牌开源项目普遍使用缺点是学习曲线陡写Makefile.am的复杂程度不比直接写Makefile低我建议普通开发者只需会用./configure make不一定要深入去写。第二类是Ninja。Ninja不是生成Makefile而是另一种比Make更快的构建后端被大量用于Chromium、Android等大型项目中。如果你用CMake也可以让它生成Ninja格式的构建文件cmake -G Ninja . ninjaNinja的设计哲学是“尽可能快地执行增量构建”它和Make的核心思路一致但在并行调度和无需重编判断上更激进。对普通开发者来说知道cmake -G Ninja这条命令就够用了不必深究内部实现。还有一个偏门但好用的技巧如果你想在IDE里折腾比如Visual Studio或Xcode也可以用CMake生成对应格式的工程文件。cmake -G Visual Studio 17 2022、cmake -G Xcode不过这是另一个话题了。4. 高频报错实录make没有指明目标并且找不到makefile4.1 报错产生的完整原因现在来专门聊聊搜索热度很高的一个报错make: *** No targets specified and no makefile found. Stop.中文说法就是“make没有指明目标并且找不到makefile”。这个报错信息虽然只有一句话但包含了两个关键信息一是make没有找到可用的Makefile文件二是因此也就没有目标可用。它为什么会发生最常见的原因是你在一个根本没有Makefile的目录里跑了make命令。比如刚clone下来一个代码仓库还没执行配套的生成命令或者单纯就是跑错目录了。这个报错本身不是代码错误而是使用环境问题。还有几种容易混淆的变种make: Nothing to be done for app找得到Makefile和目标但目标已经最新无需执行。注意这不算错误。make: *** No rule to make target foo.o, needed by app. Stop.有Makefile也定义了目标但生成某个依赖文件的规则缺失常见于规则里写了错误的文件名。make: *** missing separator. Stop.语法错误常见于命令前用了空格而不是Tab。初学者最容易把第一种“No targets specified and no makefile found”和“Nothing to be done”搞混注意看关键词就行。4.2 排查与解决步骤一分钟定位问题遇到这个报错我的排查顺序如下第一确认当前目录。运行pwd看你在哪儿是不是该项目的根目录。好多人会在build子目录或源码子目录里执行make结果找不到对应的Makefile。如果项目是用CMake组织的很多项目需要先cmake ..生成Makefile再执行make。第二确认Makefile文件是否存在。运行ls -la看有没有Makefile或makefile文件。注意看大小写Linux下是严格区分大小写的。Makefile和makefile是两个不同文件如果你只创建了makefile而make默认优先找Makefile其实它还是会退而选择makefile的因为内置查找顺序是GNUmakefile、Makefile、makefile。所以这个大小写问题一般不会导致找不到但如果你的文件名是MAKEFILE或者MakeFile那就会报错。第三如果确认有Makefile但仍然报错检查文件是否为空或者文件名是否正确。可以运行file Makefile看看系统识别出的文件类型是什么。如果显示是ASCII text那没问题如果是空文件自然会“找不到目标”。第四如果项目比较大很可能是Makefile是通过其他工具生成的而不是仓库里自带的。比如有的项目先用./autogen.sh、./configure、cmake等命令生成Makefile再执行make构建。你需要查看项目README里的构建说明把生成那一步补上。第五实在不行可以用find命令找一下系统里有没有Makefile的模板find /usr/share -name Makefile* 2/dev/null | head看看系统自带的例子但我不太建议在这个报错上花太多时间只要理解它只是在说“目录下没有make能用的构建文件”问题就解决一半了。4.3 其他高频Makefile报错速查表我在实际开发过程中积累了一些高频报错整理成表格方便快速对照报错信息含义常见原因解决方法No targets specified and no makefile found没有Makefile且没有指定目标目录不对、文件不存在、未执行生成命令切换到项目根目录创建Makefile执行cmake等生成步骤missing separator缺少分隔符命令前用了空格而不是Tab把命令行的缩进改为Tab注意编辑器设置No rule to make target xxx.o没有生成xxx.o的规则依赖文件名拼写错误、缺少对应规则检查文件名和规则写法Nothing to be done for all目标已最新没有任何文件需要更新说明构建已完成属于正常提示undefined reference to main链接时找不到main函数源文件列表漏了包含main.c的文件检查Makefile里的源文件是否完整recipe for target ... failed命令执行失败编译器报错、目录不存在、权限不足看具体编译错误输出可能是代码或配置问题Circular dependency dropped出现循环依赖规则里目标和依赖互相引用检查依赖关系避免A依赖B同时B依赖Awarning: overriding recipe for target重复定义了同一目标命令多处写同一目标合并规则避免重复定义命令这其中有几个值得展开。比如undefined reference to main别急着改Makefile先确认是哪个文件定义main然后检查源文件列表是否遗漏。还有一个我强烈建议的错误排查习惯在Makefile的编译命令行里加上-Wall -Wextra这能让你在编译期先看到大量警告而不是在运行时才追trace尤其是未定义引用这类链接错误编译期警告往往能提前暴露线索。5. 工程化使用与调试技巧让Makefile真正顺手5.1 多目录项目的Makefile组织前面讲的基础Makefile都是单目录场景实际项目往往有多个子目录。一个常见的布局是project/ ├── src/ │ ├── main.c │ └── utils.c ├── include/ │ └── utils.h ├── build/ └── Makefile多目录下有两种组织方式。第一种是递归Make也就是每个子目录都有自己的Makefile根Makefile用$(MAKE) -C src来调用子目录的make。这种方式的优点是模块清晰每个目录自己管自己缺点是构建时需要在目录间反复跳转并行效率有时会受限。第二种是单Makefile集中管理所有源文件变量里把路径写清楚SRCS : src/main.c src/utils.c OBJS : $(SRCS:.c.o) app: $(OBJS) gcc -o $ $^ %.o: %.c include/utils.h gcc -Iinclude -c $ -o $这里使用了一个模式规则%.o: %.c表示“任何.o文件都由对应的.c文件生成”。模式规则是Makefile里很有用的高级特性能大幅减少重复规则。$(SRCS:.c.o)是一种变量替换写法意思是把SRCS里每个.c结尾的字符串替换成.o结尾从而得到目标文件列表。一行就能搞定全部源文件到目标文件的映射这就是工程化写法与教学写法的区别。5.2 加速构建增量编译与并行参数Makefile的增量编译机制天然优于全量编译脚本但如果你在规则里写死了所有源文件都参与编译改名或调整文件后容易出问题。我强烈建议在依赖关系上多花心思编译器通常可以帮你自动生成头文件依赖。一个常见做法是让编译器输出依赖文件比如gcc的-MMD选项CFLAGS -Wall -MMD -Iinclude app: $(OBJS) gcc -o $ $^ %.o: %.c gcc $(CFLAGS) -c $ -o $ -include $(OBJS:.o.d)-MMD会在编译每个.c文件时生成对应的.d依赖描述文件里面记录了源文件包含的所有头文件列表。然后通过-include $(OBJS:.o.d)把这些依赖文件引入当前Makefile。这样哪怕你改了头文件make也能准确知道哪些.o需要重编再也不用手动维护头文件依赖列表了。这个写法我强烈推荐无论项目大小用了都说好。并行构建是另一个能直接压榨时间的参数。make -j4表示最多同时跑4个编译任务-j$(nproc)表示用满所有CPU核心。注意并行构建时多目录递归Make可能会有竞态问题如果你用了递归式组织建议把-j参数传给每一层的make并且确保子目录之间有明确的依赖顺序。5.3 调试Makefile的几个实用命令Makefile调试是一门容易被忽略但价值巨大的学问。我最常用的是这几个make -n干跑模式只打印命令但不真正执行。适合观察make的决策过程尤其在排查“为什么又重编了”的时候。make -p打印makefile的完整内部数据库包括所有变量、隐含规则、目标依赖。信息量巨大可以用grep过滤关键内容。make --debugb打印基本调试信息会具体显示每个目标是否重建以及原因。排查依赖问题比-n更详细。make --trace打印每条命令的来源文件适合追踪某个变量或规则到底是在哪被定义的。举个例子怀疑某个文件的依赖没生效我会运行make -n app看输出的命令是否包含了预期的编译动作。如果不执行再手动删除目标文件重跑或者直接touch main.c make -n app通过干跑模式能看到make对时间戳的判断是否合理。这招在排查“改了代码却不重新编译”这种诡异问题时特别管用。还有一个小技巧make默认在出错时会停下如果你希望某个命令执行失败但继续构建可以在命令行开头加-前缀比如-rm -f *.o。这在清理文件时很实用因为文件不存在时rm会返回非零值加了-就能避免make误报错误。不过不要滥用正常编译命令失败就应该立即终止工程构建。结尾一点经验之谈写了这么多最后聊几句我自己的体会。Makefile不是一门“学完就忘”的语言它更像是你手艺活里的一套趁手工具。真正影响构建体验的往往不是语法本身而是对依赖关系的理解——什么时候该重编、什么时候不该重编、头文件改动如何传导到目标文件。搞懂这些你不仅会用Makefile用CMake、Ninja时也会更有底气因为它们解决问题的思路是相通的。如果你正处在“看到make报错就慌”的阶段我给你的建议是不要怕。Makefile的报错信息虽然古老但大多直白按着“文件存在吗、目录对吗、规则匹配吗”的顺序排查大部分问题都能在几分钟内解决。记住把命令行的Tab键问题当作第一嫌疑把-MMD自动依赖当作第一优化手段把make -n当作第一调试工具这三样加在一起足够应付绝大多数日常开发场景了。
Makefile入门到实战：增量编译原理与常见报错排查
做过几年C/C开发的人多少都跟Makefile打过交道。它可能是你最早接触的构建工具也可能是你最想删掉重写的文件之一。刚入门时一堆目标、冒号、Tab键、变量看起来像某种古老的神秘语法可一旦理解它背后的逻辑你会发现Makefile无非是一套“谁变了就重新编译谁”的规则说明书。它不聪明但足够可靠几十年过去依然是无数项目自动构建的默认底座。这篇文章不打算做成学院派教程我从实际使用角度把它拆开讲清楚Makefile到底解决了什么问题、最基本的写法长什么样、怎么用CMake等工具生成一份像样的Makefile以及那个几乎所有人都会撞上的报错——make没有指明目标并且找不到makefile到底是怎么发生的怎么在一分钟之内解决。无论你是刚起步的初学者还是写了不少代码但一直没系统梳理过构建过程的开发者这篇内容应该都能让你少走几步弯路。1. Makefile的本质一套基于时间戳的构建规则1.1 从手动编译到自动化构建先想一个最简单的场景。你写了一个main.c想把它变成可执行程序第一反应是在终端敲gcc main.c -o app没问题一条命令搞定。但代码量上来之后事情就变了。你可能有十几个源文件每一次重新编译都要敲一长串命令。更难受的是你明明只改了一个文件却要把所有文件重新编译一遍小项目还好大项目光是编译等待时间就够喝杯咖啡的了。我最早接触的“准构建工具”是一段Shell脚本把编译命令按顺序写进去需要全量重建时执行一次。脚本能解决“命令太长、记不住”的问题但它有一个致命缺陷不智能。它无法判断哪些文件需要重编每次都是全量编译。项目一旦上了规模这种全量编译的效率低到让人抓狂。Makefile的出现就是来解决这两个问题的第一把编译链接的命令固化下来不用手动敲第二通过比较文件的时间戳只重新编译真正发生变化的部分。前者带来一致性后者带来效率。这个思路在今天看来朴素但在当时甚至现在都是构建系统最核心的命题。1.2 核心概念目标、依赖、时间戳Makefile的运行逻辑本质上是围绕“目标”展开的规则匹配。一条规则长这样目标: 依赖文件 命令所谓目标通常是你要生成的文件比如一个.o目标文件或者最终的可执行程序。依赖文件是生成这个目标所需的原料比如源文件和头文件。命令则是实际执行的编译、链接或处理操作。Make在运行时的决策逻辑只有一句话如果某个依赖文件比目标文件更新或者目标文件根本不存在就执行命令重新生成目标否则什么都不做。这个“比一比时间戳”的机制就是增量构建的根基。举个生活中的类比把目标想象成一份外卖订单依赖是食材命令是炒菜过程。只有当食材比外卖更新鲜比如刚买回来的菜你才有必要重新炒一遍如果食材是昨天买的菜也早炒好了那就直接端上桌不用再开火。理解了这一点再看Makefile就不会觉得它神秘。它其实是一堆“如果……就……”的条件规则而决定条件的依据不是代码内容而是文件的时间戳。这里要特别注意Make并不会真正去看文件内容有没有变化它只认时间戳。所以如果某个依赖文件的内容没变、但时间被touch命令改新了Make会照样重新执行编译命令。这个特性有时很讨厌但有时也能用来强制重建后面我会专门讲touch的妙用。1.3 为什么Makefile至今没有被淘汰你可能会问现在有了CMake、Ninja、Bazel这些更现代化的构建工具为什么还要学Makefile答案分两层。第一层Makefile是很多现代构建系统的底层依托。CMake默认生成的构建文件就是Makefile你运行cmake之后真正干活、真正执行增量编译的仍然是make。Ninja虽然不用Makefile但它的核心设计思路——声明依赖关系、按需重建——跟Make是一脉相承的。所以理解了Makefile再学其他构建工具会轻松很多。第二层Makefile本身在特定场景下依然无可替代。比如嵌入式开发、内核模块编译、一些小而快的命令行工具直接写一份Makefile比引入一套庞大的构建框架要清爽得多。它不需要额外的依赖只要系统里有make命令就能跑这种“零依赖”的特性在服务器、CI环境里非常吃香。当然Makefile的短板也很明显语法古老、调试困难、跨平台支持差。Windows下默认没有make得装GNU Make或者用nmake路径分隔符、Shell命令的差异也让人头疼。所以实际工程里很少看到大型项目直接裸写Makefile大家都倾向于用CMake等工具生成。但这不影响把Makefile本身学好因为它能帮你理解构建过程的底层逻辑。2. 写一个能跑的Makefile基础语法与核心技巧2.1 最简Makefile的三要素先看一个最基础的Makefile长什么样。假设项目只有两个文件main.c和utils.c头文件是utils.happ: main.o utils.o gcc -o app main.o utils.o main.o: main.c utils.h gcc -c main.c utils.o: utils.c utils.h gcc -c utils.c clean: rm -f app *.o这个例子麻雀虽小五脏俱全。第一条规则app: main.o utils.o告诉我们可执行文件app依赖两个目标文件下面两条规则分别是两个.o文件的生成方式最后一条clean不是生成文件而是用来删除编译产物的。这里有个极其重要的细节Makefile里的命令行前面必须是Tab键不能用空格代替。我见过无数新手包括我自己第一次写的时候在这里栽跟头终端弹出missing separator错误其实就是因为空格和Tab搞混了。如果你的编辑器默认把Tab转成空格请务必关掉这个设置或者直接在终端里用vim写Makefile。另一个细节是文件名的默认规则。make默认会找当前目录下名为Makefile的文件注意大小写M其次是makefile。如果两者都不存在它才会报那个经典的“找不到makefile”错误。所以如果你新建的文件叫makefile.txt或者叫MakeFile那make是找不到的。2.2 变量与自动变量别写重复代码上面那个例子虽然能跑但有个问题编译器、编译选项、文件名都是硬编码的。如果换了编译器或者加了编译参数你得改好几处。这时候就该用变量了。CC gcc CFLAGS -Wall -g app: main.o utils.o $(CC) $(CFLAGS) -o app main.o utils.o main.o: main.c utils.h $(CC) $(CFLAGS) -c main.c utils.o: utils.c utils.h $(CC) $(CFLAGS) -c utils.cCC和CFLAGS是Makefile里约定俗成的变量名前者表示C编译器后者表示编译选项。用$(CC)和$(CFLAGS)进行引用。你还可以用CPPFLAGS表示预处理选项用LDFLAGS表示链接选项。这些不是语法强制要求但遵循惯例会让你的Makefile更容易被其他人读懂。真正让Makefile摆脱重复劳动的是自动变量。自动变量的意思是在规则内部不用自己起名直接用Make预定义好的符号来代指目标、依赖等。最常用的有三个$当前规则的目标文件名$^当前规则的所有依赖文件列表去重$当前规则的第一个依赖文件用自动变量改写上面的规则app: main.o utils.o $(CC) $(CFLAGS) -o $ $^ main.o: main.c utils.h $(CC) $(CFLAGS) -c $ utils.o: utils.c utils.h $(CC) $(CFLAGS) -c $这样写的好处是规则的目标和依赖如果有调整命令部分往往不用动。你会发现很多开源项目的Makefile里到处是$和$^学会了这几个符号阅读别人的Makefile会顺畅很多。2.3 伪目标、默认目标与常见语法坑再回头看看刚才的clean。它不是一个真实存在的文件名它只是告诉Make去执行一条清理命令。如果恰好当前目录里有一个叫clean的文件make就会认为“目标已经存在且没有依赖不需要执行任何操作”然后clean规则就失效了这一点特别坑。解决办法是声明伪目标告诉Make这个目标不对应任何真实文件.PHONY: clean clean: rm -f app *.o.PHONY声明了clean之后不管目录里有没有同名文件make都会老老实实执行命令。建议把所有不生成文件的“动作型目标”都声明为.PHONY包括clean、install、test等这是经验之谈。另一个概念是默认目标。当你直接在终端运行make不带任何参数时它会选择Makefile里第一条规则的目标作为默认目标。所以一个约定俗成的习惯是把最终要生成的文件比如app写在第一个规则的位置。如果你希望用户执行make就拿到一个名为all的结果也可以显式写all: app把all放在第一行。这算是一个约定很多项目你敲make其实就是执行all。这里再说一个我踩过的坑规则里同一行的依赖顺序会影响$的取值。$只取第一个依赖而不是所有依赖所以如果你在引用$时把依赖顺序写错了编译就可能出错。要想引用全部依赖就用$^。这两个自动变量容易混但用熟了就不容易出错了。3. 生成Makefile的几条路径手写与自动生成3.1 手写Makefile的适用场景先做个判断什么样的情况下适合手写Makefile。我的建议是项目规模小源文件数量在个位到二三十个之间依赖关系简单不太需要复杂的条件检测只在固定平台、固定工具链下编译不想引入额外的构建系统依赖符合这些条件手写反而比用CMake更直接。比如我维护的一些小工具和算法demo就是一份简单的Makefile十来行搞定没有任何额外学习成本。但如果项目开始出现多个子目录、需要检测系统库是否存在、需要生成不同平台的不同版本手写Makefile就会变得极其痛苦。这种时候还坚持手写你写的维护成本会远高于编译本身节省的时间。3.2 用CMake生成Makefile的完整流程在Linux/macOS环境下用CMake生成Makefile是再常见不过的操作了。流程很简单先写一份CMakeLists.txt然后在终端执行cmake . -G Unix Makefiles make-G Unix Makefiles表示让CMake生成Makefile格式的构建文件。实际上Linux下cmake默认就是生成Makefile所以这段参数可以省略但显式写出来能帮助你理解CMake和Makefile之间的关系。来说说CMakeLists.txt最基础的写法。一个单可执行文件的C项目三行就够cmake_minimum_required(VERSION 3.10) project(demo) add_executable(app main.c utils.c utils.h)然后cmake .再make它就会生成Makefile并自动编译出一个app可执行文件。CMake的一大优势是它会自动处理很多Makefile里的琐碎细节比如头文件依赖。手写Makefile时如果你有一个头文件改了make不一定能感知到需要重编哪些.o因为你必须在规则里手动列出头文件依赖而CMake会扫描源文件包含的头文件并自动生成依赖关系这能省下一大批维护工作。那CMake生成的Makefile长什么样你可以打开看它往往几百上千行里面有一堆变量、函数调用、规则模板。直接读它确实令人头大但你要明白那是工具自动生成的一般不需要手工去改。使用CMake时还可以配置构建类型比如cmake . -DCMAKE_BUILD_TYPERelease make这样生成的就是带优化选项的Release版本。而Debug版本则带调试信息两者对应不同的编译选项CMake会在Makefile里自动处理好。3.3 还有哪些生成Makefile的方式除了CMake另外两类生成方式也需要知道。第一类是autotools体系也就是autoconfautomake。你会在很多Linux经典开源项目里看到configure脚本、Makefile.am、Makefile.in这些文件。标准流程是./configure makeconfigure会根据当前系统的实际情况生成Makefile从而适配不同Unix环境的差异。这种方式的优点是可移植性极强老牌开源项目普遍使用缺点是学习曲线陡写Makefile.am的复杂程度不比直接写Makefile低我建议普通开发者只需会用./configure make不一定要深入去写。第二类是Ninja。Ninja不是生成Makefile而是另一种比Make更快的构建后端被大量用于Chromium、Android等大型项目中。如果你用CMake也可以让它生成Ninja格式的构建文件cmake -G Ninja . ninjaNinja的设计哲学是“尽可能快地执行增量构建”它和Make的核心思路一致但在并行调度和无需重编判断上更激进。对普通开发者来说知道cmake -G Ninja这条命令就够用了不必深究内部实现。还有一个偏门但好用的技巧如果你想在IDE里折腾比如Visual Studio或Xcode也可以用CMake生成对应格式的工程文件。cmake -G Visual Studio 17 2022、cmake -G Xcode不过这是另一个话题了。4. 高频报错实录make没有指明目标并且找不到makefile4.1 报错产生的完整原因现在来专门聊聊搜索热度很高的一个报错make: *** No targets specified and no makefile found. Stop.中文说法就是“make没有指明目标并且找不到makefile”。这个报错信息虽然只有一句话但包含了两个关键信息一是make没有找到可用的Makefile文件二是因此也就没有目标可用。它为什么会发生最常见的原因是你在一个根本没有Makefile的目录里跑了make命令。比如刚clone下来一个代码仓库还没执行配套的生成命令或者单纯就是跑错目录了。这个报错本身不是代码错误而是使用环境问题。还有几种容易混淆的变种make: Nothing to be done for app找得到Makefile和目标但目标已经最新无需执行。注意这不算错误。make: *** No rule to make target foo.o, needed by app. Stop.有Makefile也定义了目标但生成某个依赖文件的规则缺失常见于规则里写了错误的文件名。make: *** missing separator. Stop.语法错误常见于命令前用了空格而不是Tab。初学者最容易把第一种“No targets specified and no makefile found”和“Nothing to be done”搞混注意看关键词就行。4.2 排查与解决步骤一分钟定位问题遇到这个报错我的排查顺序如下第一确认当前目录。运行pwd看你在哪儿是不是该项目的根目录。好多人会在build子目录或源码子目录里执行make结果找不到对应的Makefile。如果项目是用CMake组织的很多项目需要先cmake ..生成Makefile再执行make。第二确认Makefile文件是否存在。运行ls -la看有没有Makefile或makefile文件。注意看大小写Linux下是严格区分大小写的。Makefile和makefile是两个不同文件如果你只创建了makefile而make默认优先找Makefile其实它还是会退而选择makefile的因为内置查找顺序是GNUmakefile、Makefile、makefile。所以这个大小写问题一般不会导致找不到但如果你的文件名是MAKEFILE或者MakeFile那就会报错。第三如果确认有Makefile但仍然报错检查文件是否为空或者文件名是否正确。可以运行file Makefile看看系统识别出的文件类型是什么。如果显示是ASCII text那没问题如果是空文件自然会“找不到目标”。第四如果项目比较大很可能是Makefile是通过其他工具生成的而不是仓库里自带的。比如有的项目先用./autogen.sh、./configure、cmake等命令生成Makefile再执行make构建。你需要查看项目README里的构建说明把生成那一步补上。第五实在不行可以用find命令找一下系统里有没有Makefile的模板find /usr/share -name Makefile* 2/dev/null | head看看系统自带的例子但我不太建议在这个报错上花太多时间只要理解它只是在说“目录下没有make能用的构建文件”问题就解决一半了。4.3 其他高频Makefile报错速查表我在实际开发过程中积累了一些高频报错整理成表格方便快速对照报错信息含义常见原因解决方法No targets specified and no makefile found没有Makefile且没有指定目标目录不对、文件不存在、未执行生成命令切换到项目根目录创建Makefile执行cmake等生成步骤missing separator缺少分隔符命令前用了空格而不是Tab把命令行的缩进改为Tab注意编辑器设置No rule to make target xxx.o没有生成xxx.o的规则依赖文件名拼写错误、缺少对应规则检查文件名和规则写法Nothing to be done for all目标已最新没有任何文件需要更新说明构建已完成属于正常提示undefined reference to main链接时找不到main函数源文件列表漏了包含main.c的文件检查Makefile里的源文件是否完整recipe for target ... failed命令执行失败编译器报错、目录不存在、权限不足看具体编译错误输出可能是代码或配置问题Circular dependency dropped出现循环依赖规则里目标和依赖互相引用检查依赖关系避免A依赖B同时B依赖Awarning: overriding recipe for target重复定义了同一目标命令多处写同一目标合并规则避免重复定义命令这其中有几个值得展开。比如undefined reference to main别急着改Makefile先确认是哪个文件定义main然后检查源文件列表是否遗漏。还有一个我强烈建议的错误排查习惯在Makefile的编译命令行里加上-Wall -Wextra这能让你在编译期先看到大量警告而不是在运行时才追trace尤其是未定义引用这类链接错误编译期警告往往能提前暴露线索。5. 工程化使用与调试技巧让Makefile真正顺手5.1 多目录项目的Makefile组织前面讲的基础Makefile都是单目录场景实际项目往往有多个子目录。一个常见的布局是project/ ├── src/ │ ├── main.c │ └── utils.c ├── include/ │ └── utils.h ├── build/ └── Makefile多目录下有两种组织方式。第一种是递归Make也就是每个子目录都有自己的Makefile根Makefile用$(MAKE) -C src来调用子目录的make。这种方式的优点是模块清晰每个目录自己管自己缺点是构建时需要在目录间反复跳转并行效率有时会受限。第二种是单Makefile集中管理所有源文件变量里把路径写清楚SRCS : src/main.c src/utils.c OBJS : $(SRCS:.c.o) app: $(OBJS) gcc -o $ $^ %.o: %.c include/utils.h gcc -Iinclude -c $ -o $这里使用了一个模式规则%.o: %.c表示“任何.o文件都由对应的.c文件生成”。模式规则是Makefile里很有用的高级特性能大幅减少重复规则。$(SRCS:.c.o)是一种变量替换写法意思是把SRCS里每个.c结尾的字符串替换成.o结尾从而得到目标文件列表。一行就能搞定全部源文件到目标文件的映射这就是工程化写法与教学写法的区别。5.2 加速构建增量编译与并行参数Makefile的增量编译机制天然优于全量编译脚本但如果你在规则里写死了所有源文件都参与编译改名或调整文件后容易出问题。我强烈建议在依赖关系上多花心思编译器通常可以帮你自动生成头文件依赖。一个常见做法是让编译器输出依赖文件比如gcc的-MMD选项CFLAGS -Wall -MMD -Iinclude app: $(OBJS) gcc -o $ $^ %.o: %.c gcc $(CFLAGS) -c $ -o $ -include $(OBJS:.o.d)-MMD会在编译每个.c文件时生成对应的.d依赖描述文件里面记录了源文件包含的所有头文件列表。然后通过-include $(OBJS:.o.d)把这些依赖文件引入当前Makefile。这样哪怕你改了头文件make也能准确知道哪些.o需要重编再也不用手动维护头文件依赖列表了。这个写法我强烈推荐无论项目大小用了都说好。并行构建是另一个能直接压榨时间的参数。make -j4表示最多同时跑4个编译任务-j$(nproc)表示用满所有CPU核心。注意并行构建时多目录递归Make可能会有竞态问题如果你用了递归式组织建议把-j参数传给每一层的make并且确保子目录之间有明确的依赖顺序。5.3 调试Makefile的几个实用命令Makefile调试是一门容易被忽略但价值巨大的学问。我最常用的是这几个make -n干跑模式只打印命令但不真正执行。适合观察make的决策过程尤其在排查“为什么又重编了”的时候。make -p打印makefile的完整内部数据库包括所有变量、隐含规则、目标依赖。信息量巨大可以用grep过滤关键内容。make --debugb打印基本调试信息会具体显示每个目标是否重建以及原因。排查依赖问题比-n更详细。make --trace打印每条命令的来源文件适合追踪某个变量或规则到底是在哪被定义的。举个例子怀疑某个文件的依赖没生效我会运行make -n app看输出的命令是否包含了预期的编译动作。如果不执行再手动删除目标文件重跑或者直接touch main.c make -n app通过干跑模式能看到make对时间戳的判断是否合理。这招在排查“改了代码却不重新编译”这种诡异问题时特别管用。还有一个小技巧make默认在出错时会停下如果你希望某个命令执行失败但继续构建可以在命令行开头加-前缀比如-rm -f *.o。这在清理文件时很实用因为文件不存在时rm会返回非零值加了-就能避免make误报错误。不过不要滥用正常编译命令失败就应该立即终止工程构建。结尾一点经验之谈写了这么多最后聊几句我自己的体会。Makefile不是一门“学完就忘”的语言它更像是你手艺活里的一套趁手工具。真正影响构建体验的往往不是语法本身而是对依赖关系的理解——什么时候该重编、什么时候不该重编、头文件改动如何传导到目标文件。搞懂这些你不仅会用Makefile用CMake、Ninja时也会更有底气因为它们解决问题的思路是相通的。如果你正处在“看到make报错就慌”的阶段我给你的建议是不要怕。Makefile的报错信息虽然古老但大多直白按着“文件存在吗、目录对吗、规则匹配吗”的顺序排查大部分问题都能在几分钟内解决。记住把命令行的Tab键问题当作第一嫌疑把-MMD自动依赖当作第一优化手段把make -n当作第一调试工具这三样加在一起足够应付绝大多数日常开发场景了。
