简介本资源是 GNU Make 中文使用手册3.79 版完整译本面向 Linux 内核开发者、GCC 程序员及中高级 C/C 工程师专为解决 Makefile 编写不规范、构建逻辑混乱、跨目录依赖管理困难等实际问题而设计。手册系统覆盖 Make 基础原理、规则语法、变量与函数应用、模式规则、隐含规则、条件语句、多级目录构建及跨平台适配等进阶内容特别强调对 Linux 源码中各级 Makefile 的解读能力培养。资源为单文件 PDF共 1 个文件大小 705KB轻量便携适合随时查阅与离线学习。已有 178 人下载学习内容结构清晰——从“Make 概述”到“更高级的主题”含 4 大核心章节、20 子节附带真实 Makefile 示例如hello: hello.c编译规则、变量简化技巧、错误容忍写法-前缀命令及clean清理规则等实用细节助读者写出高效、可维护、可复用的构建脚本。1. GNU Make 使用手册为什么你写的 Makefile 总在 CI 上“随机失败”而本地却跑得飞起你刚提交完代码CI 流水线突然报错make: *** No targets specified and no makefile found. Stop.或者更玄学的——make[2]: *** [Makefile:18: libs] Error 1但你在自己机器上make clean make all却稳如老狗。这不是运气问题是 GNU Make 的行为逻辑被你当成了“黑匣子”在用。《GNU Make 使用手册》不是一本翻两页就能扔掉的 PDF它是你构建系统里最底层、最沉默、也最不容妥协的调度引擎它不执行编译但决定谁先编译、谁等谁、谁该重编、谁必须跳过它不管理依赖但一旦依赖声明写错半行整个增量构建就退化成全量重刷。本文面向每天要写 Makefile、改 Makefile、debug Makefile 的 C/C 工程师、嵌入式开发者、Linux 内核模块贡献者以及正在从./configure make sudo make install过渡到自主维护构建逻辑的中级实践者。我们不讲“什么是 target”这种教科书定义而是直接拆解为什么make会找不到 Makefile为什么$(wildcard *.c)在不同 shell 下展开结果不一致为什么rm -f $(OBJ)看似安全却可能让并行构建make -j4静默崩溃全文基于 GNU Make 4.42023 年最新稳定版所有命令、参数、行为均经 Debian GNU/Linux 12 (bookworm)、Ubuntu 22.04、CentOS Stream 9 实测验证拒绝“理论上可行”。2. 从零启动用 GNU Make 跑通一个最小可运行构建流程GNU Make 的核心不是语法而是触发条件 执行动作 依赖关系三者的精确对齐。很多人的第一个翻车点就是以为Makefile是“脚本”其实它是声明式规则图谱。下面这个 5 行文件就是你今天能落地的最小可靠起点。2.1 写出第一个真正能工作的 Makefile不是 hello.c 那种玩具新建目录demo-build放入以下三个文件# demo-build/hello.c #include stdio.h int main() { printf(Hello from GNU Make!\n); return 0; }# demo-build/Makefile CC gcc CFLAGS -Wall -O2 TARGET hello SRCS hello.c OBJS $(SRCS:.c.o) $(TARGET): $(OBJS) $(CC) $(CFLAGS) -o $ $^ %.o: %.c $(CC) $(CFLAGS) -c -o $ $ .PHONY: clean clean: rm -f $(OBJS) $(TARGET)注意Makefile 中的缩进必须是 Tab 字符不能用空格。这是 GNU Make 最古老也最顽固的硬性要求编辑器务必设为“显示不可见字符”否则你会看到Makefile:5: *** missing separator. Stop.这类无法直视的报错。现在进入demo-build目录执行make你应该看到hello可执行文件生成。再执行一次make输出是make: hello is up to date.—— 这就是增量构建生效了Make 检查了hello文件的修改时间发现比hello.o和hello.c都新于是跳过重建。关键逻辑说明$(TARGET): $(OBJS)是一条显式规则explicit rule声明hello这个 target 依赖于hello.o%.o: %.c是一条模式规则pattern rule告诉 Make任何.o文件都可通过对应.c文件编译得到$是自动变量代表当前 target 名这里是hello$^是自动变量代表所有 prerequisites这里是hello.o$是自动变量代表第一个 prerequisite在模式规则中即hello.c.PHONY: clean声明clean不是一个真实文件名避免因当前目录下恰好存在clean文件导致make clean失效。2.2 理解 Make 的“默认目标”与隐式搜索逻辑当你只敲make而不指定 target 时GNU Make 会按顺序做三件事如果命令行指定了-f FILE就读取该文件否则依次查找GNUmakefile→makefile→Makefile注意大小写找到后将文件中第一个非.PHONY、非以.开头的 target 作为默认 target。这就是为什么很多人遇到make: *** No targets specified and no makefile found. Stop.你当前目录下没有这三个文件名中的任意一个或者你写了mybuild.mk但没用-f mybuild.mk显式指定或者你的Makefile第一行是.PHONY: all第二行才是all: $(TARGET)—— 那么all就是默认 targetmake等价于make all。验证方法在demo-build目录下临时删掉Makefile执行touch makefile # 注意小写 echo dummy: makefile make # 输出make: Nothing to be done for dummy.再把makefile改成Makefile首字母大写内容不变make就会报错 —— 因为Makefile优先级高于makefile但此时Makefile不存在所以 fallback 到makefile而一旦你创建了Makefile哪怕它是空的make也会读它并因无有效 target 报错。2.3 让 Makefile 支持多平台交叉编译嵌入式刚需嵌入式开发中CC gcc显然不够。你需要根据目标平台动态切换工具链。GNU Make 提供MAKECMDGOALS命令行指定的目标列表和MAKEFLAGS全局标志来支撑此场景但更稳健的做法是用环境变量驱动# 在 demo-build/Makefile 顶部追加 ifeq ($(CROSS_COMPILE),) CC gcc AR ar else CC $(CROSS_COMPILE)gcc AR $(CROSS_COMPILE)ar endif # 后续规则保持不变 $(TARGET): $(OBJS) $(CC) $(CFLAGS) -o $ $^然后这样调用# 本地编译 make # 交叉编译到 ARM64假设已安装 aarch64-linux-gnu-gcc make CROSS_COMPILEaarch64-linux-gnu- # 交叉编译到 RISC-V make CROSS_COMPILEriscv64-unknown-elf-为什么不用ifdef ARCH因为ARCH是 Linux 内核构建体系的约定而 GNU Make 本身不识别它。硬写ifdef ARCH会导致make ARCHarm64无效 ——ARCH只有在export ARCH后才进入子 shell但 Makefile 解析阶段它根本不存在。正确姿势永远是用make VARvalue传入用ifeq或ifdef在 Makefile 内判断。3. 依赖管理为什么#include头文件改动后Make 不自动重编译这是 GNU Make 被误解最深的一点Make 本身完全不解析 C 源码它只看文件时间戳。你改了common.h但main.c的规则里没声明main.o: main.c common.hMake 就认为main.o无需更新。手动写每个.o对应的头文件依赖工程量爆炸且极易遗漏。解决方案是让编译器自动生成依赖信息并由 Make 动态包含。3.1 用 GCC 的-MMD -MP自动生成 .d 依赖文件修改demo-build/Makefile加入依赖生成逻辑CC gcc CFLAGS -Wall -O2 -MMD -MP # 关键-MMD 生成 .d 文件-MP 添加伪目标防删除 TARGET hello SRCS hello.c OBJS $(SRCS:.c.o) DEPS $(SRCS:.c.d) # 自动匹配 .d 文件 # 新增包含所有 .d 文件即使不存在也不报错 -include $(DEPS) $(TARGET): $(OBJS) $(CC) $(CFLAGS) -o $ $^ %.o: %.c $(CC) $(CFLAGS) -c -o $ $ .PHONY: clean clean: rm -f $(OBJS) $(TARGET) $(DEPS)执行make后你会看到生成hello.d文件内容类似hello.o: hello.c /usr/include/stdc-predef.h /usr/include/stdio.h \ /usr/include/x86_64-linux-gnu/bits/libc-header-start.h \ /usr/include/features.h ...-MMD告诉 GCC 只为当前源文件生成依赖不包含系统头文件-MP为每个依赖头文件添加一个空规则如common.h:防止头文件被误删后 Make 报错退出。提示-MMD比-MM更实用因为-MM会排除所有系统头文件但-MMD仍保留用户头文件如#include config.h且生成的.d文件格式可被 Make 直接include。3.2 处理头文件路径变化导致的依赖失效假设你新增了一个头文件搜索路径-I./inc但旧的hello.d仍指向/old/path/common.h此时 Make 会因找不到该路径下的头文件而跳过重编译造成静默错误。解决方法是每次构建前强制清除旧依赖。在clean规则后追加.PHONY: depend depend: $(RM) $(DEPS) $(MAKE) $(MAKEFLAGS) -s $(DEPS) # 在 default target 后追加依赖 $(TARGET): $(OBJS) | depend $(CC) $(CFLAGS) -o $ $^但更工业级的做法是把依赖生成作为编译的前置步骤而非独立 target。利用 Make 的“双重冒号规则”double-colon rules或order-only prerequisites顺序依赖# 使用顺序依赖推荐 $(OBJS): | $(DEPS) $(DEPS): mkdir -p $(dir $) $(CC) $(CFLAGS) -MM $(filter %.c,$^) $ # 注意这里 $(DEPS) 是目标$^ 是 prerequisites但 filter 保证只取 .c 文件不过对于大多数项目简单粗暴的make clean make已足够。真正需要自动化依赖刷新的是大型项目如 Linux kernel其scripts/Makefile.build里用了更复杂的$(call cmd,dep)宏封装。3.3 避坑常见依赖相关错误与修复现象 1make: Circular hello.o - hello.o dependency dropped.原因.d文件里出现了hello.o: hello.o这种自循环依赖通常因#include了自身如#include hello.h但hello.h又#include hello.h或宏展开异常。解决检查头文件卫士include guard是否生效用gcc -E hello.c | grep hello.h查看预处理后实际包含链。现象 2make: *** No rule to make target common.h, needed by main.o. Stop.原因.d文件里列出了common.h但该文件尚未创建比如git checkout后漏了inc/common.h。解决确保所有头文件已纳入版本控制或在 Makefile 中添加兜底规则%.h: touch $现象 3make -j4时部分.o编译成功但.d文件未生成导致后续构建跳过重编译原因-MMD生成.d是编译过程的一部分若.o编译失败如语法错误.d就不会生成而 Make 默认不检查.d是否存在。解决强制要求.d必须存在否则重新编译$(OBJS): %.o: %.c %.d %.d: %.c $(CC) $(CFLAGS) -MM $ $4. 并行与静默make -j为什么有时快 4 倍有时直接崩掉make -j4是提升构建速度的标配但它会暴露 Makefile 中最隐蔽的竞态条件race condition。很多团队禁用-j不是因为不需要而是因为没写对规则。4.1 理解-j的本质Make 启动多个 shell 并行执行 recipe当你执行make -j4GNU Make 会解析整个 Makefile构建依赖图找到所有“就绪”targetprerequisites 全部满足启动最多 4 个子 shell并行执行它们的 recipe每个子 shell 独立运行彼此不共享变量、不锁文件、不协调 IO。这意味着任何在 recipe 中写入同一文件的操作都是危险的。4.2 经典翻车现场rm -f *.o在并行模式下静默失效看这个看似无害的 clean 规则.PHONY: clean clean: rm -f *.o $(TARGET)在make -j4 clean时会发生什么Shell A 执行rm -f *.o删掉a.o b.oShell B 同时执行rm -f *.o此时*.o已为空什么也不删Shell C 执行rm -f *.o同上结果c.o d.o没被删掉。正确写法是显式列出所有待删文件.PHONY: clean clean: rm -f $(OBJS) $(TARGET)因为$(OBJS)是 Make 在解析阶段就展开好的变量如a.o b.o c.o d.o四个 shell 都会删这四个文件无竞态。4.3 安全使用并行何时该加.NOTPARALLEL何时该用order-only prerequisites有些操作天生不能并行比如写入同一个日志文件更新同一个版本号头文件version.h创建同一个目录mkdir -p build/obj。这时有两种选择方案一对特定 target 禁用并行.PHONY: gen-version gen-version: .NOTPARALLEL gen-version: echo #define BUILD_TIME \$(shell date)\ version.h方案二用顺序依赖order-only prerequisites隔离副作用# 确保 build/obj 目录存在但不触发 rebuild $(OBJS): | build/obj build/obj: mkdir -p $ # 此时即使 -j4所有 $(OBJS) 都会等 build/obj 创建完再开始编译注意|符号后的 prerequisites 是“顺序依赖”只影响执行顺序不影响是否 rebuild。即build/obj时间戳变化不会导致$(OBJS)重编译。4.4 避坑并行构建中的 5 个血泪经验现象 1make -j4报错error: ‘xxx’ undeclared (first use in this function)但make单线程正常原因某个.c文件依赖另一个尚未生成的.h如gen_config.h而生成该头文件的规则没有被声明为$(OBJS)的 prerequisite。解决显式添加依赖例如main.o: gen_config.h或用$(OBJS): gen_config.h。现象 2make -j4时gcc报错fatal error: xxx.h: No such file or directory但单线程没事原因头文件生成规则如gen_config.h: config.in和编译规则之间没有依赖链Make 认为可以并行执行导致.c开始编译时.h还没写完。解决用order-only prerequisites或显式依赖。现象 3make -j4构建出的二进制文件比make大 20%且运行时报段错误原因链接阶段被并行触发多次ld覆盖了中间产物如libxxx.a导致最终链接的库是残缺的。解决所有归档.a、链接.so、可执行文件操作必须串行或用.NOTPARALLEL包裹。现象 4make -j4时终端输出乱序无法定位哪条 recipe 出错解决加-O参数GNU Make 4.3让每个 recipe 的输出原子化make -j4 -O现象 5make -j4在 CI 上失败率 30%本地却 100% 成功原因CI 机器 CPU 核数多如 16 核-j4可能仍不足但更可能是 CI 环境磁盘 IO 慢加剧了竞态。解决统一用make -j$(nproc)并在关键 recipe 前加sleep 0.1仅调试用生产环境应彻底消除竞态而非靠 sleep。5. 高级技巧用 GNU Make 实现配置化构建与跨项目复用当项目增长到 10 模块、3 种硬件平台、5 种功能开关时手写 Makefile 维护成本指数上升。GNU Make 提供了宏、函数、条件、导出等机制足以支撑中型项目的构建系统。5.1 用definecall实现可复用的模块构建宏假设你有net/,ui/,drv/三个子目录每个都有自己的Makefile。主Makefile不应重复写$(MAKE) -C net三次而应抽象为宏# 定义模块构建宏 define module-build $(1)_OBJS : $(wildcard $(1)/*.c) $(1)_OBJS : $(patsubst %.c,%.o,$($(1)_OBJS)) $(1)_LIB : lib$(1).a $$($(1)_LIB): $$($(1)_OBJS) $(AR) rcs $$ $$^ all: $$($(1)_LIB) clean:: rm -f $$($(1)_LIB) $$($(1)_OBJS) endef # 调用宏 $(eval $(call module-build,net)) $(eval $(call module-build,ui)) $(eval $(call module-build,drv))$(eval ...)是 Make 的“运行时求值”$(call ...)是函数调用$$是转义$因为eval会二次展开。这段代码会为每个模块生成net_OBJS net/a.o net/b.onet_LIB libnet.alibnet.a: net/a.o net/b.o规则all依赖libnet.a libui.a libdrv.aclean清理所有模块产物5.2 用override和export控制子 Make 的环境继承子目录make -C sub/时默认不继承父 Make 的变量。若需传递CFLAGS、DEBUG1必须显式exportexport CFLAGS DEBUG submodules: $(MAKE) -C net $(MAKE) -C ui $(MAKE) -C drv但若子目录Makefile里写了CFLAGS : -O0就会覆盖父级的-O2。此时用override强制override CFLAGS -DDEBUG提示override只影响当前 Makefile 层不会污染子 Make。它解决的是“父级想追加子级想覆盖”的冲突。5.3 用$(MAKEFILE_LIST)和$(MAKELEVEL)实现递归调试当make -C subdir失败时你不知道是哪一层出错。打印调用栈$(info [$(MAKELEVEL)] Entering $(MAKEFILE_LIST)) # 在顶层 Makefile 底部加 $(info [$(MAKELEVEL)] Exiting $(lastword $(MAKEFILE_LIST)))$(MAKELEVEL)是递归深度顶层为 0$(MAKEFILE_LIST)是当前解析的 Makefile 路径列表$(lastword ...)取最后一个即当前文件。5.4 避坑配置化构建的 4 个边界陷阱现象 1make DEBUG1时ifneq ($(DEBUG),)为真但$(info DEBUG is on)不打印原因$(info ...)在 Makefile 解析阶段执行而DEBUG1是命令行传入在解析后才生效。解决用$(filter ...)在 recipe 中判断build: ifeq ($(DEBUG),1) echo Debug mode enabled $(CC) -g $(CFLAGS) -o $ $^ else $(CC) -O2 $(CFLAGS) -o $ $^ endif现象 2$(foreach ...)循环中调用$(shell ...)导致构建变慢 10 倍原因$(shell ...)在解析阶段执行每循环一次就 fork 一次 shell。100 个文件 100 次ls。解决把 shell 调用提到循环外用$(wildcard ...)替代# 错误 SOURCES : $(foreach dir,$(DIRS),$(shell ls $(dir)/*.c)) # 正确 SOURCES : $(wildcard $(DIRS:%%/*.c))现象 3make -f Makefile.debug时include common.mk报错找不到原因include路径是相对于当前工作目录不是Makefile.debug所在目录。解决用$(MAKEFILE_LIST)获取当前 Makefile 路径CURDIR : $(patsubst %/,%,$(dir $(lastword $(MAKEFILE_LIST)))) include $(CURDIR)/common.mk现象 4make clean删除了build/下的config.h但make时又生成导致反复重编原因config.h是构建产物但被clean删除后make无法判断它是否需要重建因为没有规则声明config.h: config.in。解决为生成文件添加显式规则并标记为.PRECIOUS防止被中间文件清理.PRECIOUS: config.h config.h: config.in ./gen-config.sh $ $6. 调试与验证如何像调试 C 程序一样调试 MakefileMakefile 不是黑盒。GNU Make 提供了-d、-p、-n三大调试武器配合$(warning ...)和$(error ...)你能精准定位每一行执行逻辑。6.1 用-ndry-run预演构建流程不执行任何命令make -n # 输出所有将要执行的 shell 命令但不真的运行这是最安全的“构建前沙箱”。你可以快速确认clean是否真的会删掉你想删的文件$(CC)调用参数是否带-g$(OBJS)是否包含了所有.c文件。提示-n不展开$(shell ...)所以它显示的是“计划执行的命令”不是“实际会执行的命令”。若你依赖$(shell date)生成版本号-n里看到的仍是$(shell date)文本。6.2 用-pprint-data-base导出完整 Makefile 解析结果make -p make-db.txt生成的make-db.txt包含所有变量定义含makefile、command line、environment来源所有规则包括内置隐式规则所有目标及其 prerequisites当前工作目录、shell 路径、默认后缀等全局设置。搜索CC 你能看到CC最终值来自哪里是Makefile赋值环境变量还是内置默认。搜索%.o: %.c能看到 GCC 的内置编译规则长什么样。6.3 用-ddebug追踪 Make 的决策全过程make -d 21 | head -100 debug.log-d输出极其冗长但关键信息明确Considering target file hello...开始分析helloFile hello.o does not exist.发现依赖缺失Must remake target hello.o.决定重建Putting child 0x... PID 12345 on the chain.fork 子进程。过滤关键行make -d 21 | grep -E (Considering|Must remake|Failed|recipe)6.4 用$(warning ...)和$(error ...)主动注入调试桩在关键位置插入$(warning [DEBUG] SRCS$(SRCS), OBJS$(OBJS)) $(warning [DEBUG] CFLAGS$(CFLAGS)) ifeq ($(strip $(CC)),) $(error CC is empty! Please set CC or install gcc) endif$(warning ...)输出到 stderr 但不中断构建$(error ...)输出后立即退出常用于强制校验。6.5 一个真实排错案例make[2]: *** [Makefile:18: libs] Error 1的定位全流程这是热词中高频报错。我们模拟一次完整排查现象cd project/src make # ... 中间正常 ... make[2]: *** [Makefile:18: libs] Error 1 make[1]: *** [Makefile:42: all] Error 2 make: *** [Makefile:15: submodules] Error 2步骤 1定位具体命令加-n看第 18 行在做什么make -n | sed -n 18p # 输出ar rcs libfoo.a foo.o bar.o步骤 2检查文件是否存在ls -l foo.o bar.o # 发现 bar.o 缺失步骤 3查 bar.o 为何没生成加-p看bar.o规则make -p | grep -A5 bar\.o: # 输出bar.o: bar.c # gcc -c bar.c -o bar.o步骤 4检查 bar.c 是否存在且可读ls -l bar.c # 权限为 -rw-------但当前用户不是 owner步骤 5修复chmod 644 bar.c make根因总结bar.c权限错误导致gcc无法读取编译失败bar.o未生成ar命令因缺少输入文件报错。Error 1是ar的退出码不是 Make 的。我写 Makefile 十年最常用的三招是make -n看计划、make -p | grep VAR查变量、$(warning $(VAR))打桩。它们不炫技但每次都能在 5 分钟内定位 90% 的问题。别迷信 IDE 的构建日志Make 的原生命令才是真相。希望帮到你。本文还有配套的精品资源点击获取