📚 课程目录第4章顶层Makefile设计

4、顶层Makefile设计：入口文件、子目录调用、全局变量定义

顶层Makefile是整个构建系统的「大脑」。它不直接编译任何源文件，而是负责调度、协调各个子目录的构建任务。我见过不少团队把顶层Makefile写成「大杂烩」，几百行代码堆在一起，最后谁也改不动。

说白了，顶层Makefile就三件事：定义全局变量、调用子目录、提供入口目标。今天咱们就把这三件事拆开揉碎了讲清楚。

4.1 顶层Makefile的职责边界

先搞清楚顶层Makefile不该做什么：

不编译源文件——那是子目录Makefile的事
不定义局部规则——除非是全局通用的模式规则
不硬编码路径——路径应该通过变量传递

顶层Makefile的核心职责就三条：

职责	说明	典型实现
全局变量定义	编译器、编译选项、输出路径等	`CC := arm-linux-gnueabihf-gcc`
子目录调度	递归或非递归方式调用子目录	`$(MAKE) -C subdir`
入口目标提供	all、clean、distclean等	`.PHONY: all clean`

经验之谈：我早期犯过一个错误——把编译规则也塞进顶层Makefile。结果项目一扩展，顶层文件变得臃肿不堪，每次修改都要小心翼翼。后来我强制自己：顶层只做调度，不做执行。

4.2 全局变量定义的艺术

全局变量是顶层Makefile的「通信协议」。子目录Makefile通过读取这些变量来知道「用什么编译器」「输出到哪里」「有哪些头文件路径」。

我个人习惯把全局变量分成三类：

4.2.1 工具链变量

# 交叉编译工具链
CROSS_COMPILE ?= arm-linux-gnueabihf-
CC := $(CROSS_COMPILE)gcc
CXX := $(CROSS_COMPILE)g++
LD := $(CROSS_COMPILE)ld
AR := $(CROSS_COMPILE)ar
OBJCOPY := $(CROSS_COMPILE)objcopy
SIZE := $(CROSS_COMPILE)size

注意这里用了 ?=。为什么？因为用户可以在命令行覆盖：make CROSS_COMPILE=aarch64-linux-gnu-。我在项目中遇到过客户需要同时编译arm和aarch64版本，这个设计帮了大忙。

4.2.2 路径变量

# 项目根目录
ROOT_DIR := $(shell pwd)

# 输出目录
BUILD_DIR := $(ROOT_DIR)/build
OUTPUT_DIR := $(BUILD_DIR)/output

# 头文件搜索路径
INC_DIRS := $(ROOT_DIR)/include \
            $(ROOT_DIR)/lib/common/include \
            $(ROOT_DIR)/lib/driver/include

# 库文件路径
LIB_DIRS := $(OUTPUT_DIR)/lib

避坑指南：我曾经用相对路径定义 INC_DIRS，结果子目录Makefile用 -I$(INC_DIRS) 时路径全错了。后来统一用 $(shell pwd) 取绝对路径，再也没出过问题。

4.2.3 编译选项变量

# 编译选项
CFLAGS := -Wall -Wextra -O2 -g
CFLAGS += $(addprefix -I, $(INC_DIRS))

# 链接选项
LDFLAGS := -L$(LIB_DIRS)
LDLIBS := -lpthread -lm

# 条件编译
ifeq ($(DEBUG), 1)
    CFLAGS += -DDEBUG -O0
endif

你想想看，这些变量一旦定义好，子目录Makefile只需要 include $(ROOT_DIR)/Makefile.inc 就能拿到全部配置。这就是「一处定义，多处使用」的精髓。

4.3 子目录调用策略

顶层Makefile怎么调用子目录？主流方案有两种：递归Make和非递归Make。我两种都用过，说说我的感受。

4.3.1 递归Make（传统方案）

SUBDIRS := lib/app \
           lib/driver \
           src/main \
           test

.PHONY: all clean $(SUBDIRS)

all: $(SUBDIRS)

$(SUBDIRS):
    $(MAKE) -C $@

clean:
    @for dir in $(SUBDIRS); do \
        $(MAKE) -C $$dir clean; \
    done

递归Make的优点是简单直观。每个子目录独立维护自己的Makefile，互不干扰。但缺点也很明显——依赖追踪困难，构建速度慢。我记得有一次项目有30多个子目录，递归Make一次全量构建要跑3分钟。

4.3.2 非递归Make（现代方案）

# 包含所有子目录的Makefile片段
include $(ROOT_DIR)/lib/app/Makefile.inc
include $(ROOT_DIR)/lib/driver/Makefile.inc
include $(ROOT_DIR)/src/main/Makefile.inc

# 统一编译规则
$(BUILD_DIR)/%.o: %.c
    @mkdir -p $(dir $@)
    $(CC) $(CFLAGS) -c $< -o $@

# 统一链接规则
$(OUTPUT_DIR)/$(TARGET): $(OBJS)
    $(CC) $(LDFLAGS) $^ -o $@ $(LDLIBS)

非递归Make把所有源文件纳入同一个Make进程管理。依赖关系清晰，增量构建快。但要求子目录Makefile片段遵循统一的变量命名规范。

方案	优点	缺点	适用场景
递归Make	简单、隔离性好	构建慢、依赖追踪弱	小型项目、子目录独立性强
非递归Make	构建快、依赖完整	规范要求高、调试复杂	中大型项目、频繁增量构建

注意：无论选哪种方案，顶层Makefile都要提供统一的 all、clean、distclean 目标。这是用户接口，不能变。

4.4 顶层Makefile的完整骨架

下面是我个人常用的顶层Makefile模板，经过多个项目验证，你可以直接拿来改：

# ============================================
# 顶层Makefile - 项目入口
# ============================================

# 工具链
CROSS_COMPILE ?= arm-linux-gnueabihf-
CC := $(CROSS_COMPILE)gcc
CXX := $(CROSS_COMPILE)g++
LD := $(CROSS_COMPILE)ld

# 路径
ROOT_DIR := $(shell pwd)
BUILD_DIR := $(ROOT_DIR)/build
OUTPUT_DIR := $(BUILD_DIR)/output
INC_DIRS := $(ROOT_DIR)/include

# 编译选项
CFLAGS := -Wall -Wextra -O2 -g
CFLAGS += $(addprefix -I, $(INC_DIRS))
LDFLAGS := -L$(OUTPUT_DIR)/lib
LDLIBS := -lpthread -lm

# 子目录列表
SUBDIRS := lib/app \
           lib/driver \
           src/main \
           test

# 目标名称
TARGET := my_project

# 导出变量给子目录
export CC CXX LD CFLAGS LDFLAGS LDLIBS
export ROOT_DIR BUILD_DIR OUTPUT_DIR

# ============================================
# 目标定义
# ============================================

.PHONY: all clean distclean $(SUBDIRS)

all: $(SUBDIRS)
    @echo "Build complete: $(TARGET)"

$(SUBDIRS):
    $(MAKE) -C $@

clean:
    @for dir in $(SUBDIRS); do \
        $(MAKE) -C $$dir clean; \
    done
    @rm -rf $(BUILD_DIR)

distclean: clean
    @rm -rf $(OUTPUT_DIR)

# ============================================
# 帮助信息
# ============================================

help:
    @echo "Usage: make [target]"
    @echo "Targets:"
    @echo "  all        - Build the project (default)"
    @echo "  clean      - Remove build artifacts"
    @echo "  distclean  - Remove all generated files"
    @echo "  help       - Show this help"

关键点：注意 export 那一行。如果不导出变量，子目录Makefile是看不到顶层定义的变量的。我见过有人在这上面卡了一整天——子目录里 $(CC) 总是空的，就是因为忘了export。

4.5 顶层Makefile的SVG结构图

下面这张图展示了顶层Makefile在整个构建系统中的位置和交互关系：

4.6 避坑指南与最佳实践

做了这么多年Makefile，我总结了几条顶层设计的铁律：

变量命名要统一——子目录里用 $(CFLAGS)，顶层就得叫 CFLAGS，别搞出 CFLAGS_TOP 这种奇葩名字。
export要谨慎——只导出子目录真正需要的变量。我见过有人把整个环境都export出去，结果子目录里变量名冲突，排查起来想哭。
提供help目标——这是好习惯。新同事接手项目，敲个 make help 就知道怎么玩了。
保持顶层Makefile简洁——超过200行就该考虑拆分了。可以把变量定义放到 Makefile.inc，顶层只保留调度逻辑。

血的教训：我曾经在顶层Makefile里用 include 直接包含子目录的Makefile，结果子目录里的目标名和顶层冲突了。从那以后我严格区分：顶层用 include 只包含 .inc 文件，子目录的 Makefile 只通过 $(MAKE) -C 调用。

嗯，顶层Makefile的设计就这些。记住它的核心——做调度者，不做执行者。下一层子目录的设计，咱们后面再细聊。