makefile

Makefile 技能

创建和维护 GNU Make 构建自动化的指南。

快速导航

主题	参考
规则、先决条件、目标	syntax.md
变量类型与赋值	variables.md
内置函数	functions.md
特殊目标与伪目标	targets.md
配方执行、并行	recipes.md
隐式规则与模式规则	implicit.md
常见实用模式	patterns.md

---

核心概念

规则结构

target: prerequisites
        recipe

关键： 配方行必须以 TAB 字符开头。

文件目标与伪目标

# File target - creates/updates a file
build/app.o: src/app.c
        $(CC) -c $< -o $@

# Phony target - action, not a file
.PHONY: clean test install

clean:
        rm -rf build/

变量赋值

运算符	名称	展开时机
:=	简单	定义时一次
?=	条件	若尚未设置
=	递归	每次使用时（延迟绑定）
+=	追加	添加到现有值

CC := gcc              # Immediate
CFLAGS ?= -O2          # Default, overridable
DEBUG = $(VERBOSE)     # Late binding
CFLAGS += -Wall        # Append

自动变量

变量	含义
$@	目标
$<	第一个先决条件
$^	所有先决条件（去重）
$?	比目标更新的先决条件
$*	模式规则中的词干

---

基本模式

自文档化帮助

.DEFAULT_GOAL := help

help: ## Show available targets
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
		awk 'BEGIN {FS = ":.*?## "}; {printf "  %-15s %s\n", $$1, $$2}'

install: ## Install dependencies
	uv sync

test: ## Run tests
	uv run pytest

平台检测

UNAME_S := $(shell uname -s)

ifeq ($(UNAME_S),Darwin)
    OPEN := open
else ifeq ($(UNAME_S),Linux)
    OPEN := xdg-open
endif

构建目录

BUILDDIR := build
SOURCES := $(wildcard src/*.c)
OBJECTS := $(patsubst src/%.c,$(BUILDDIR)/%.o,$(SOURCES))

$(BUILDDIR)/%.o: src/%.c | $(BUILDDIR)
	$(CC) -c $< -o $@

$(BUILDDIR):
	mkdir -p $@

环境变量导出

export PYTHONPATH := $(PWD)/src
export DATABASE_URL

test:
	pytest tests/  # sees exported variables

---

常用目标

质量检查

.PHONY: lint format check test

lint: ## Run linters
	ruff check .
	mypy src/

format: ## Format code
	ruff format .

check: format lint test ## All quality checks

清理

.PHONY: clean clean-all

clean: ## Remove build artifacts
	rm -rf build/ dist/ *.egg-info
	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true

clean-all: clean ## Remove all generated files
	rm -rf .venv .pytest_cache .mypy_cache

Docker 集成

IMAGE := myapp
VERSION := $(shell git describe --tags --always)

docker-build: ## Build Docker image
	docker build -t $(IMAGE):$(VERSION) .

docker-run: ## Run container
	docker run -d -p 8000:8000 $(IMAGE):$(VERSION)

---

配方执行

每一行 = 独立的 Shell

# Won't work - cd lost between lines
bad:
	cd subdir
	pwd           # Still in original dir!

# Correct - combine commands
good:
	cd subdir && pwd

# Or use line continuation
also-good:
	cd subdir && \
	pwd && \
	make

静默与错误处理

target:
	@echo "@ suppresses command echo"
	-rm -f maybe.txt    # - ignores errors

并行执行

make -j4              # 4 parallel jobs
make -j4 lint test    # Run lint and test in parallel

---

输出规范

一行输入，一行输出。 避免 echo 刷屏。

# ❌ Too chatty
start:
	@echo "Starting services..."
	docker compose up -d
	@echo "Waiting..."
	@sleep 3
	@echo "Done!"

# ✅ Concise
start: ## Start services
	@echo "Starting at http://localhost:8000 ..."
	@docker compose up -d
	@echo "Logs: docker compose logs -f"

---

条件语句

DEBUG ?= 0

ifeq ($(DEBUG),1)
    CFLAGS += -g -O0
else
    CFLAGS += -O2
endif

ifdef CI
    TEST_FLAGS := --ci
endif

---

包含文件

# Required include (error if missing)
include config.mk

# Optional include (silent if missing)
-include local.mk
-include .env

---

常见陷阱

陷阱	问题	解决方案
配方中的空格	配方需要 TAB	使用实际的 TAB 字符
缺少 .PHONY	若存在 test 文件，make test 会失败	声明 .PHONY: test
配方中的 cd	每一行都是新的 Shell	使用 cd dir && command
= 与 := 混淆	意外的延迟展开	默认使用 :=
未导出的变量	子进程看不到变量	export VAR
make 中的复杂 Shell	难以维护	移到外部脚本

---

快速参考

# Makefile Template
.DEFAULT_GOAL := help
SHELL := /bin/bash
.SHELLFLAGS := -ec

.PHONY: help install test lint format clean

help: ## Show this help
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
		awk 'BEGIN {FS = ":.*?## "}; {printf "  %-15s %s\n", $$1, $$2}'

install: ## Install dependencies
	uv sync --extra dev

test: ## Run tests
	uv run pytest tests/ -v

lint: ## Run linters
	uv run ruff check .

format: ## Format code
	uv run ruff format .

clean: ## Clean artifacts
	rm -rf build/ dist/ .pytest_cache

---

链接

• 文档

另请参阅

• patterns.md - 扩展模式与配方