Real-World Makefiles

Four complete, tested Makefiles to adapt for your own projects: a C program with tests and install, a Python task runner, a data pipeline, and Terraform and Docker wrappers.

By The Dark DebuggerUpdated 26 min read

This is the capstone of the Make path. Instead of new features, it puts the earlier articles together into four complete Makefiles of the kinds you'll actually write: a C project with debug and release builds, tests and install; a Python project's command menu; a data pipeline with real intermediate files; and a wrapper around Terraform and Docker. Each one is shown in full, run, and then walked through. It assumes the whole path so far, especially Make as a Task Runner, Multi-Directory Projects and Parallel Builds, Dependency Generation, and Debugging.

What every one of these Makefiles has in common

Before the projects, the habits they share. These are the lines I now put in almost every Makefile, and each one is there because leaving it out caused a bug earlier in this path:

  • .DELETE_ON_ERROR: so a failed recipe can't leave a half-written target that looks up to date on the next run.
  • .DEFAULT_GOAL set explicitly, so reordering rules or adding an include can't change what a bare make does.
  • Every task name in .PHONY, and every real output a real target, so Make can skip work.
  • A help target built from ## comments, so the Makefile documents itself.
  • Variables with ?= defaults for anything a person or CI might override (BUILD, PREFIX, ENV), and a clear $(error) for values that make no sense.
  • Outputs under one directory (build/), so clean is one rm -rf.

Project 1: a C program with tests and install

csvstat prints the count, minimum, maximum and mean of a numeric CSV column. It has a small library (csv.c, stats.c), a program (main.c), and unit tests, laid out the way most C projects are:

.
├── Makefile
├── data
│   └── orders.csv
├── include
│   ├── csv.h
│   └── stats.h
├── src
│   ├── csv.c
│   ├── main.c
│   └── stats.c
└── tests
    └── test_stats.c
# csvstat: summary statistics for one numeric column of a CSV file.
#   make [BUILD=release|debug]    build build/$(BUILD)/csvstat
#   make check                    build and run the unit tests
#   make install [PREFIX=/usr/local] [DESTDIR=]
.DELETE_ON_ERROR:
.DEFAULT_GOAL := all
 
BUILD   ?= release
PREFIX  ?= /usr/local
DESTDIR ?=
 
WARNINGS := -Wall -Wextra -std=c11
CPPFLAGS += -Iinclude
ifeq ($(BUILD),release)
  CFLAGS   ?= -O2
  CPPFLAGS += -DNDEBUG
else ifeq ($(BUILD),debug)
  CFLAGS ?= -O0 -g
else
  $(error BUILD must be 'release' or 'debug', not '$(BUILD)')
endif
 
OUT      := build/$(BUILD)
LIB_OBJS := $(OUT)/csv.o $(OUT)/stats.o
LIB      := $(OUT)/libcsvstat.a
BIN      := $(OUT)/csvstat
TEST_BIN := $(OUT)/test_stats
DEPS     := $(LIB_OBJS:.o=.d) $(OUT)/main.d $(OUT)/test_stats.d
 
.PHONY: all check install uninstall clean help
 
all: $(BIN) ## Build the csvstat program
 
check: $(TEST_BIN) ## Build and run the unit tests
	./$(TEST_BIN)
 
$(BIN): $(OUT)/main.o $(LIB)
	$(CC) $(LDFLAGS) $^ -o $@
 
$(TEST_BIN): $(OUT)/test_stats.o $(LIB)
	$(CC) $(LDFLAGS) $^ -o $@
 
$(LIB): $(LIB_OBJS)
	$(AR) rcs $@ $^
 
$(OUT)/%.o: src/%.c | $(OUT)
	$(CC) $(CPPFLAGS) $(WARNINGS) $(CFLAGS) -MMD -MP -c $< -o $@
 
$(OUT)/%.o: tests/%.c | $(OUT)
	$(CC) $(CPPFLAGS) $(WARNINGS) $(CFLAGS) -MMD -MP -c $< -o $@
 
# The tests are built on assert(), so never compile them with NDEBUG.
$(OUT)/test_stats.o: CPPFLAGS += -UNDEBUG
 
$(OUT):
	mkdir -p $@
 
install: $(BIN) $(LIB) ## Install into $(DESTDIR)$(PREFIX)
	install -d $(DESTDIR)$(PREFIX)/bin $(DESTDIR)$(PREFIX)/lib $(DESTDIR)$(PREFIX)/include
	install -m 755 $(BIN) $(DESTDIR)$(PREFIX)/bin/csvstat
	install -m 644 $(LIB) $(DESTDIR)$(PREFIX)/lib/libcsvstat.a
	install -m 644 include/csv.h include/stats.h $(DESTDIR)$(PREFIX)/include/
 
uninstall: ## Remove everything install put in place
	rm -f $(DESTDIR)$(PREFIX)/bin/csvstat $(DESTDIR)$(PREFIX)/lib/libcsvstat.a
	rm -f $(DESTDIR)$(PREFIX)/include/csv.h $(DESTDIR)$(PREFIX)/include/stats.h
 
clean: ## Delete all build output
	rm -rf build
 
help: ## Show this help
	@grep -hE '^[a-zA-Z_-]+:.*## ' $(MAKEFILE_LIST) | \
		awk 'BEGIN {FS = ":.*## "} {printf "  %-10s %s\n", $$1, $$2}'
 
-include $(DEPS)

Running it

make help
make
make check
./build/release/csvstat 3 < data/orders.csv
  all        Build the csvstat program
  check      Build and run the unit tests
  install    Install into $(DESTDIR)$(PREFIX)
  uninstall  Remove everything install put in place
  clean      Delete all build output
  help       Show this help
mkdir -p build/release
cc -Iinclude -DNDEBUG -Wall -Wextra -std=c11 -O2 -MMD -MP -c src/main.c -o build/release/main.o
cc -Iinclude -DNDEBUG -Wall -Wextra -std=c11 -O2 -MMD -MP -c src/csv.c -o build/release/csv.o
cc -Iinclude -DNDEBUG -Wall -Wextra -std=c11 -O2 -MMD -MP -c src/stats.c -o build/release/stats.o
ar rcs build/release/libcsvstat.a build/release/csv.o build/release/stats.o
cc  build/release/main.o build/release/libcsvstat.a -o build/release/csvstat
cc -Iinclude -DNDEBUG -UNDEBUG -Wall -Wextra -std=c11 -O2 -MMD -MP -c tests/test_stats.c -o build/release/test_stats.o
cc  build/release/test_stats.o build/release/libcsvstat.a -o build/release/test_stats
./build/release/test_stats
test_stats: all tests passed
count 5  min 15.00  max 310.00  mean 118.13

(The help shows $(DESTDIR)$(PREFIX) literally because the ## text is copied as written.) A debug build lives in its own tree, so switching back and forth never mixes objects:

make BUILD=debug check
mkdir -p build/debug
cc -Iinclude -UNDEBUG -Wall -Wextra -std=c11 -O0 -g -MMD -MP -c tests/test_stats.c -o build/debug/test_stats.o
cc -Iinclude -Wall -Wextra -std=c11 -O0 -g -MMD -MP -c src/csv.c -o build/debug/csv.o
cc -Iinclude -Wall -Wextra -std=c11 -O0 -g -MMD -MP -c src/stats.c -o build/debug/stats.o
ar rcs build/debug/libcsvstat.a build/debug/csv.o build/debug/stats.o
cc  build/debug/test_stats.o build/debug/libcsvstat.a -o build/debug/test_stats
./build/debug/test_stats
test_stats: all tests passed

A header change rebuilds exactly the objects that include it, thanks to -MMD -MP:

touch include/stats.h
make
cc -Iinclude -DNDEBUG -Wall -Wextra -std=c11 -O2 -MMD -MP -c src/main.c -o build/release/main.o
cc -Iinclude -DNDEBUG -Wall -Wextra -std=c11 -O2 -MMD -MP -c src/stats.c -o build/release/stats.o
ar rcs build/release/libcsvstat.a build/release/csv.o build/release/stats.o
cc  build/release/main.o build/release/libcsvstat.a -o build/release/csvstat

And packaging works the way distribution tools expect:

make install PREFIX=/usr DESTDIR=pkgroot
tree --noreport pkgroot
install -d pkgroot/usr/bin pkgroot/usr/lib pkgroot/usr/include
install -m 755 build/release/csvstat pkgroot/usr/bin/csvstat
install -m 644 build/release/libcsvstat.a pkgroot/usr/lib/libcsvstat.a
install -m 644 include/csv.h include/stats.h pkgroot/usr/include/
pkgroot
└── usr
    ├── bin
    │   └── csvstat
    ├── include
    │   ├── csv.h
    │   └── stats.h
    └── lib
        └── libcsvstat.a

From a clean tree, a parallel build of everything plus the tests is safe because the graph is complete:

make clean
make -j4 all check
rm -rf build
mkdir -p build/release
cc -Iinclude -DNDEBUG -Wall -Wextra -std=c11 -O2 -MMD -MP -c src/main.c -o build/release/main.o
cc -Iinclude -DNDEBUG -Wall -Wextra -std=c11 -O2 -MMD -MP -c src/csv.c -o build/release/csv.o
cc -Iinclude -DNDEBUG -Wall -Wextra -std=c11 -O2 -MMD -MP -c src/stats.c -o build/release/stats.o
cc -Iinclude -DNDEBUG -UNDEBUG -Wall -Wextra -std=c11 -O2 -MMD -MP -c tests/test_stats.c -o build/release/test_stats.o
ar rcs build/release/libcsvstat.a build/release/csv.o build/release/stats.o
cc  build/release/test_stats.o build/release/libcsvstat.a -o build/release/test_stats
cc  build/release/main.o build/release/libcsvstat.a -o build/release/csvstat
./build/release/test_stats
test_stats: all tests passed

Walkthrough

  • BUILD selects a configuration and an output tree (build/release, build/debug), the pattern from Conditionals and Portable Makefiles. CFLAGS ?= inside each branch means a packager's own CFLAGS still wins, while WARNINGS is kept separate so overriding CFLAGS doesn't silently turn warnings off.
  • The library is a real archive that both the program and the tests link against, so the tests exercise the same objects you ship.
  • Two pattern rules produce $(OUT)/%.o, one from src/ and one from tests/. Make tries them in order and uses the first whose source file exists.
  • $(OUT)/test_stats.o: CPPFLAGS += -UNDEBUG is a target-specific variable: it applies only while building that one object. This line exists because of the most instructive bug I hit while testing this article; it's the first entry in Common mistakes.
  • install depends on the files it installs, not on all, so make install builds only what it needs, and uses DESTDIR/PREFIX exactly as described in Multi-Directory Projects.

Project 2: a Python project's task runner

logsum summarizes web server access logs; its Makefile is the command menu that Make as a Task Runner builds step by step. This version adds formatting and linting targets around ruff, and treats ruff as optional where that is safe and required where it isn't.

# logsum: summarize web server access logs.
SHELL       := bash
.SHELLFLAGS := -eu -o pipefail -c
.DELETE_ON_ERROR:
.DEFAULT_GOAL := help
 
PYTHON ?= python3
VENV   ?= .venv
PY     := $(VENV)/bin/python
RUFF   ?= $(shell command -v ruff)
SRC    := logsum tests
 
.PHONY: help venv test lint fmt fmt-check ci clean
 
help: ## Show this help
	@grep -hE '^[a-zA-Z_-]+:.*## ' $(MAKEFILE_LIST) | \
		awk 'BEGIN {FS = ":.*## "} {printf "  %-10s %s\n", $$1, $$2}'
 
venv: $(VENV)/.stamp ## Create the virtual environment
 
$(VENV)/.stamp: requirements.txt
	rm -rf $(VENV)
	$(PYTHON) -m venv --without-pip $(VENV)
	touch $@
 
test: venv ## Run the unit tests
	$(PY) -m unittest discover -s tests -v 2>&1 | tee test-report.txt
 
lint: venv ## Syntax-check everything, then run ruff if it is installed
	$(PY) -m compileall -q $(SRC)
	$(if $(RUFF),$(RUFF) check $(SRC),@echo "lint: ruff not installed, skipped style checks")
 
fmt: ## Reformat the code with ruff
	$(if $(RUFF),,$(error 'make fmt' needs ruff: https://docs.astral.sh/ruff/installation/))
	$(RUFF) format $(SRC)
 
fmt-check: ## Fail if any file needs reformatting (for CI)
	$(if $(RUFF),,$(error 'make fmt-check' needs ruff: https://docs.astral.sh/ruff/installation/))
	$(RUFF) format --check $(SRC)
 
ci: lint test ## Everything CI runs
 
clean: ## Delete the venv, caches and reports
	rm -rf $(VENV) test-report.txt
	find . -name __pycache__ -type d -prune -exec rm -rf {} +

Running it

make
make test
  help       Show this help
  venv       Create the virtual environment
  test       Run the unit tests
  lint       Syntax-check everything, then run ruff if it is installed
  fmt        Reformat the code with ruff
  fmt-check  Fail if any file needs reformatting (for CI)
  ci         Everything CI runs
  clean      Delete the venv, caches and reports
rm -rf .venv
python3 -m venv --without-pip .venv
touch .venv/.stamp
.venv/bin/python -m unittest discover -s tests -v 2>&1 | tee test-report.txt
test_bad_line (test_parse.ParseTest.test_bad_line) ... ok
test_good_line (test_parse.ParseTest.test_good_line) ... ok
test_counts (test_parse.SummaryTest.test_counts) ... ok
 
----------------------------------------------------------------------
Ran 3 tests in 0.000s
 
OK

The test machine didn't have ruff, which shows the two kinds of tool check side by side:

make lint
make fmt
.venv/bin/python -m compileall -q logsum tests
lint: ruff not installed, skipped style checks
Makefile:34: *** 'make fmt' needs ruff: https://docs.astral.sh/ruff/installation/.  Stop.

The venv is rebuilt only when requirements.txt changes:

make venv
touch requirements.txt
make venv
make: Nothing to be done for 'venv'.
rm -rf .venv
python3 -m venv --without-pip .venv
touch .venv/.stamp

Walkthrough

  • Bash strict mode (SHELL and .SHELLFLAGS) is what makes ... | tee test-report.txt fail the build when a test fails; without pipefail, tee's success would hide it.
  • The venv is a stamp-file target depending on requirements.txt. --without-pip is there because logsum uses only the standard library and the machine I tested on lacks Ubuntu's python3.12-venv package. In a project with dependencies, the recipe gains $(VENV)/bin/pip install -r requirements.txt before the touch, and tools such as ruff and pytest come from the venv (RUFF ?= $(VENV)/bin/ruff) instead of the PATH.
  • Optional versus required tools. lint degrades gracefully, because a syntax check is still useful without ruff. fmt refuses to run, because "formatted nothing" must never look like success. Note the different tools: $(if ...) choosing between two recipe lines at run time, and $(error) stopping before anything runs.
  • ci is just a list of prerequisites. CI and developers run the same targets, in the same order, with the same flags.

Project 3: a data pipeline with real intermediate files

Make is at its best when outputs are files made from other files. A shop drops one CSV of orders per day into data/raw/; we want a validated copy of each, per-customer daily totals, and one report in two formats:

data/raw/DAY.csv  ->  build/clean/DAY.csv  ->  build/daily/DAY.tsv  ->  build/report.txt
                       (validated, paid only)   (totals per customer)      build/report.html
.
├── Makefile
├── data
│   └── raw
│       ├── 2026-11-03.csv
│       ├── 2026-11-04.csv
│       └── 2026-11-05.csv
└── scripts
    ├── clean.awk
    └── report.py

One day's export, with a malformed row:

order_id,customer,total,status
1204,initech,310.00,paid
1205,acme,87.25,paid
1206,globex,n/a,paid

scripts/clean.awk keeps the header and paid orders, and reports malformed rows with their file and line number:

# Keep the header and paid orders with a numeric total.
# Malformed rows are reported on stderr with their file and line number.
BEGIN { FS = OFS = "," }
FNR == 1 { print; next }
NF != 4 || $3 !~ /^[0-9]+(\.[0-9]+)?$/ {
    printf "%s:%d: rejected: %s\n", FILENAME, FNR, $0 > "/dev/stderr"
    next
}
$4 == "paid" { print }

scripts/report.py (about 30 lines of standard-library Python) reads the daily files and writes report.txt and report.html. The Makefile:

# Daily order exports -> cleaned CSVs -> per-day totals -> one report.
.DELETE_ON_ERROR:
.SECONDARY:
 
RAW   := $(sort $(wildcard data/raw/*.csv))
DAYS  := $(notdir $(RAW:.csv=))
DAILY := $(DAYS:%=build/daily/%.tsv)
 
.PHONY: all clean
all: build/report.txt build/report.html
 
# 1. Validate: keep paid orders with a numeric total.
build/clean/%.csv: data/raw/%.csv scripts/clean.awk
	@mkdir -p $(@D)
	awk -f scripts/clean.awk $< > $@
 
# 2. Aggregate: one line per customer per day.
build/daily/%.tsv: build/clean/%.csv
	@mkdir -p $(@D)
	awk -F, 'NR > 1 { n[$$2]++; t[$$2] += $$3 } END { for (c in n) printf "%s\t%d\t%.2f\n", c, n[c], t[c] }' $< | sort > $@
 
# 3. Report: one script run writes both files.
build/report.txt build/report.html &: $(DAILY) scripts/report.py
	python3 scripts/report.py build/report $(DAILY)
 
clean:
	rm -rf build

Running it

make -j4
awk -f scripts/clean.awk data/raw/2026-11-03.csv > build/clean/2026-11-03.csv
awk -f scripts/clean.awk data/raw/2026-11-04.csv > build/clean/2026-11-04.csv
awk -f scripts/clean.awk data/raw/2026-11-05.csv > build/clean/2026-11-05.csv
data/raw/2026-11-04.csv:4: rejected: 1206,globex,n/a,paid
awk -F, 'NR > 1 { n[$2]++; t[$2] += $3 } END { for (c in n) printf "%s\t%d\t%.2f\n", c, n[c], t[c] }' build/clean/2026-11-03.csv | sort > build/daily/2026-11-03.tsv
awk -F, 'NR > 1 { n[$2]++; t[$2] += $3 } END { for (c in n) printf "%s\t%d\t%.2f\n", c, n[c], t[c] }' build/clean/2026-11-04.csv | sort > build/daily/2026-11-04.tsv
awk -F, 'NR > 1 { n[$2]++; t[$2] += $3 } END { for (c in n) printf "%s\t%d\t%.2f\n", c, n[c], t[c] }' build/clean/2026-11-05.csv | sort > build/daily/2026-11-05.tsv
python3 scripts/report.py build/report build/daily/2026-11-03.tsv build/daily/2026-11-04.tsv build/daily/2026-11-05.tsv

The three days were cleaned in parallel, then aggregated in parallel, then combined once. Every stage left a file you can inspect:

cat build/clean/2026-11-04.csv
cat build/daily/2026-11-04.tsv
cat build/report.txt
order_id,customer,total,status
1204,initech,310.00,paid
1205,acme,87.25,paid
acme	1	87.25
initech	1	310.00
Revenue by day
  2026-11-03     178.40
  2026-11-04     397.25
  2026-11-05     359.50
 
Revenue by customer
  initech       385.50
  acme          281.15
  globex        268.50
 
Total: 935.15

The HTML version is the same table for a browser:

<!doctype html>
<title>Orders report</title>
<h1>Orders report</h1>
<table><tr><th>Customer</th><th>Revenue</th></tr><tr><td>initech</td><td>385.50</td></tr><tr><td>acme</td><td>281.15</td></tr><tr><td>globex</td><td>268.50</td></tr></table>

Incremental runs

Here's the reason to use Make for this rather than a script. Someone corrects one order in the November 4 export:

sed -i 's/1205,acme,87.25/1205,acme,97.25/' data/raw/2026-11-04.csv
make --trace
Makefile:14: update target 'build/clean/2026-11-04.csv' due to: data/raw/2026-11-04.csv
mkdir -p build/clean
awk -f scripts/clean.awk data/raw/2026-11-04.csv > build/clean/2026-11-04.csv
data/raw/2026-11-04.csv:4: rejected: 1206,globex,n/a,paid
Makefile:19: update target 'build/daily/2026-11-04.tsv' due to: build/clean/2026-11-04.csv
mkdir -p build/daily
awk -F, 'NR > 1 { n[$2]++; t[$2] += $3 } END { for (c in n) printf "%s\t%d\t%.2f\n", c, n[c], t[c] }' build/clean/2026-11-04.csv | sort > build/daily/2026-11-04.tsv
Makefile:24: update target 'build/report.txt' due to: build/daily/2026-11-04.tsv
python3 scripts/report.py build/report build/daily/2026-11-03.tsv build/daily/2026-11-04.tsv build/daily/2026-11-05.tsv

Only that day's chain and the final report ran. (--trace also shows commands that @ normally hides, like the mkdir.) When a new day arrives, the $(wildcard) picks it up and only the new file is processed:

make
tail -4 build/report.txt
awk -f scripts/clean.awk data/raw/2026-11-06.csv > build/clean/2026-11-06.csv
awk -F, 'NR > 1 { n[$2]++; t[$2] += $3 } END { for (c in n) printf "%s\t%d\t%.2f\n", c, n[c], t[c] }' build/clean/2026-11-06.csv | sort > build/daily/2026-11-06.tsv
python3 scripts/report.py build/report build/daily/2026-11-03.tsv build/daily/2026-11-04.tsv build/daily/2026-11-05.tsv build/daily/2026-11-06.tsv
  globex        268.50
  umbrella       33.10
 
Total: 1388.25

With 3 days this saves nothing; with 365 days of exports, each needing a slow validation step, it's the difference between seconds and an hour.

Walkthrough

  • $(wildcard) plus substitution references turn the list of inputs into the list of outputs, so adding a day requires no Makefile change.
  • The scripts are prerequisites. Edit clean.awk and every day is re-cleaned; edit report.py and only the report is rebuilt. That's Exercise 1.
  • .SECONDARY: keeps the build/clean/ files. They're only reached through pattern rules, so Make would otherwise treat them as intermediate and delete them after use, and here they are useful for auditing what was rejected.
  • &: declares that one report.py run produces both report files. Without it, a parallel build could run the script twice.
  • .DELETE_ON_ERROR: matters more in pipelines than anywhere: every stage writes with >, so a failed awk would otherwise leave an empty file that looks finished.

Project 4: Terraform and Docker wrappers

Infrastructure repositories use Make as a safety layer: the commands are long, they need the right environment's variables, and running the wrong one is expensive. This project wraps a Terraform configuration with two environments and a Docker image build. The Terraform here uses the built-in terraform_data resource, so it runs without a cloud account (see Terraform Introduction); the Makefile is the same for a real AWS configuration.

.
├── Dockerfile
├── Makefile
└── infra
    ├── envs
    │   ├── production.tfvars
    │   └── staging.tfvars
    └── main.tf

infra/envs/staging.tfvars holds environment = "staging" and replicas = 1; production has three replicas. The Makefile:

# Container image and infrastructure commands for logsum.
#   make plan ENV=staging     save a plan for one environment
#   make apply ENV=staging    apply exactly that saved plan
.DELETE_ON_ERROR:
.DEFAULT_GOAL := help
 
ENV   ?= staging
TAG   ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
IMAGE := registry.example.com/logsum
TF    := terraform -chdir=infra
PLAN  := infra/$(ENV)-$(TAG).tfplan
 
ifeq ($(wildcard infra/envs/$(ENV).tfvars),)
  $(error unknown ENV '$(ENV)'; choose one of: $(basename $(notdir $(wildcard infra/envs/*.tfvars))))
endif
 
.PHONY: help docker-build docker-push check plan apply clean
 
help: ## Show this help
	@grep -hE '^[a-zA-Z_-]+:.*## ' $(MAKEFILE_LIST) | \
		awk 'BEGIN {FS = ":.*## "} {printf "  %-13s %s\n", $$1, $$2}'
 
docker-build: ## Build the image $(IMAGE):$(TAG)
	@command -v docker >/dev/null || { echo "docker is not installed" >&2; exit 1; }
	docker build --pull -t $(IMAGE):$(TAG) .
 
docker-push: docker-build ## Push the image to the registry
	docker push $(IMAGE):$(TAG)
 
.make/tf-init: $(wildcard infra/*.tf)
	$(TF) init -input=false
	@mkdir -p $(@D) && touch $@
 
check: .make/tf-init ## terraform fmt -check and validate
	$(TF) fmt -check -diff
	$(TF) validate
 
$(PLAN): .make/tf-init $(wildcard infra/*.tf) infra/envs/$(ENV).tfvars
	$(TF) workspace select -or-create $(ENV)
	$(TF) plan -input=false -var-file=envs/$(ENV).tfvars -var image_tag=$(TAG) -out=$(notdir $@)
 
plan: $(PLAN) ## Save a plan for ENV (default: staging)
 
apply: $(PLAN) ## Apply the saved plan for ENV, then discard it
	$(TF) workspace select $(ENV)
	$(TF) apply -input=false $(notdir $(PLAN))
	rm -f $(PLAN)
 
clean: ## Delete saved plans and Make's stamp files
	rm -rf .make infra/*.tfplan

Running it

The repository is a git checkout tagged v1.4.0, so TAG comes from git describe. (Terraform prints colored output in a terminal; I've removed the color codes below.)

make check
terraform -chdir=infra init -input=false
Initializing the backend...
 
Initializing provider plugins...
- terraform.io/builtin/terraform is built in to Terraform
 
Terraform has been successfully initialized!
[…]
terraform -chdir=infra fmt -check -diff
terraform -chdir=infra validate
Success! The configuration is valid.

plan saves a plan file whose name includes the environment and the image tag:

make plan
make plan
terraform -chdir=infra workspace select -or-create staging
Created and switched to workspace "staging"!
[…]
terraform -chdir=infra plan -input=false -var-file=envs/staging.tfvars -var image_tag=v1.4.0 -out=staging-v1.4.0.tfplan
 
Terraform used the selected providers to generate the following execution
plan. Resource actions are indicated with the following symbols:
  + create
 
Terraform will perform the following actions:
 
  # terraform_data.service will be created
  + resource "terraform_data" "service" {
      + id     = (known after apply)
      + input  = {
          + image    = "registry.example.com/logsum:v1.4.0"
          + name     = "logsum-staging"
          + replicas = 1
        }
      + output = (known after apply)
    }
 
Plan: 1 to add, 0 to change, 0 to destroy.
[…]
Saved the plan to: staging-v1.4.0.tfplan
[…]
make: Nothing to be done for 'plan'.

The second make plan did nothing: the plan file is a real target, newer than every .tf and .tfvars file it depends on. apply applies exactly that reviewed file, then deletes it, because Terraform refuses to apply a saved plan twice anyway:

make apply
terraform -chdir=infra workspace select staging
terraform -chdir=infra apply -input=false staging-v1.4.0.tfplan
terraform_data.service: Creating...
terraform_data.service: Creation complete after 0s [id=5d0352d5-13d1-edca-90b3-cb1b9a8b9f3a]
 
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.
 
Outputs:
 
service = {
  "image" = "registry.example.com/logsum:v1.4.0"
  "name" = "logsum-staging"
  "replicas" = 1
}
rm -f infra/staging-v1.4.0.tfplan

Now change the staging configuration to two replicas. Editing a tracked file also makes git describe report v1.4.0-dirty, so the next plan gets a new name and can't be confused with the clean one:

sed -i 's/replicas    = 1/replicas    = 2/' infra/envs/staging.tfvars
make plan
terraform -chdir=infra workspace select -or-create staging
Switched to workspace "staging".
terraform -chdir=infra plan -input=false -var-file=envs/staging.tfvars -var image_tag=v1.4.0-dirty -out=staging-v1.4.0-dirty.tfplan
terraform_data.service: Refreshing state... [id=5d0352d5-13d1-edca-90b3-cb1b9a8b9f3a]
[…]
  # terraform_data.service will be updated in-place
  ~ resource "terraform_data" "service" {
        id     = "5d0352d5-13d1-edca-90b3-cb1b9a8b9f3a"
      ~ input  = {
          ~ image    = "registry.example.com/logsum:v1.4.0" -> "registry.example.com/logsum:v1.4.0-dirty"
            name     = "logsum-staging"
          ~ replicas = 1 -> 2
        }
[…]
Plan: 0 to add, 1 to change, 0 to destroy.

A typo in the environment is caught before Terraform ever runs:

make plan ENV=prod
Makefile:14: *** unknown ENV 'prod'; choose one of: production staging.  Stop.

The test machine has no Docker, so the image targets got as far as their guard. A dry run still shows exactly what they would execute, because the guard is a shell command rather than a Make $(error):

make docker-build
make -n docker-push
docker is not installed
make: *** [Makefile:24: docker-build] Error 1
command -v docker >/dev/null || { echo "docker is not installed" >&2; exit 1; }
docker build --pull -t registry.example.com/logsum:v1.4.0 .
docker push registry.example.com/logsum:v1.4.0

The Dockerfile itself is four lines (a python:3.12-slim base, copy logsum/, set the entry point) and was not built.

Walkthrough

  • TAG from git describe, with dev as the fallback outside git, ties the image tag and the plan to the exact commit. -dirty flags uncommitted changes, which you may want to refuse in apply for production.
  • The plan file is a real target named after ENV and TAG. Including both in the name solves the problem from Conditionals: Make can't see variable changes, but it can see that a file with the new name doesn't exist yet.
  • ENV is validated against the files in infra/envs/, so the list of environments lives in one place, and adding one is adding a .tfvars file.
  • .make/tf-init is a stamp file that re-runs terraform init only when a .tf file changes. A configuration with registry providers would also depend on infra/.terraform.lock.hcl.
  • Shell guard versus $(error). docker-build's check is a recipe line, so make -n still prints the plan of action on a machine without Docker. A $(error) guard would stop even a dry run. Choose deliberately.

Where you'll use this

These four shapes cover most of the Makefiles you'll meet or write:

  • Compiled projects (C, C++, and Go or Rust projects that wrap their own build tools) look like Project 1: configurations, a library, tests, install that respects DESTDIR.
  • Interpreted-language repositories look like Project 2: a menu over tools that have their own dependency handling.
  • Analytics, documentation and research repositories look like Project 3: files made from files, where incremental rebuilds save real time. The same structure turns Markdown into HTML with pandoc, or regenerates figures for a paper when the data changes.
  • Infrastructure and deployment repositories look like Project 4: guard rails around expensive commands, with saved artifacts (plans, images) as real targets.

In practice they combine. A service repository might have Project 2's test menu, Project 4's image and deploy targets, and a small Project 3-style rule that regenerates API docs, all behind one make help.

Common mistakes

Tests that can't fail in release builds

The first version of Project 1 compiled the tests with the same flags as the release program, -DNDEBUG included. The compiler noticed before I did:

cc -Iinclude -DNDEBUG -Wall -Wextra -std=c11 -O2 -MMD -MP -c tests/test_stats.c -o build/release/test_stats.o
tests/test_stats.c: In function ‘main’:
tests/test_stats.c:13:12: warning: unused variable ‘v’ [-Wunused-variable]
   13 |     double v;
      |            ^
[…]
./build/release/test_stats
test_stats: all tests passed

NDEBUG turns every assert() into nothing, so the variables the assertions used were unused, and "all tests passed" because no test ran. The target-specific -UNDEBUG fixes it. To prove the tests can fail now, I broke an expected value on purpose:

./build/release/test_stats
test_stats: tests/test_stats.c:11: main: Assertion `s.count == 3 && s.min == 48.50 && s.max == 300.00' failed.
make: *** [Makefile:35: check] Aborted (core dumped)

"Aborted (core dumped)" is Make reporting that the test program was killed by SIGABRT, which is what a failed assert() raises. Whatever your test framework, check once that a deliberately broken test fails the build.

Wrapping commands without depending on their inputs

A plan: target with a recipe and no prerequisites would run terraform plan every time and never let Make skip anything, and an apply that ran terraform apply directly would apply whatever the configuration says now, not what was reviewed. Making the plan a file with real prerequisites is what turns the Makefile from a list of aliases into a safety mechanism. The same applies to Project 3: a report: task that runs the whole pipeline every time throws away the reason for using Make.

Hard-coding paths that packagers and CI need to change

install targets that write to /usr/local directly, or Makefiles that call gcc instead of $(CC), work on the author's machine and get patched by everyone else. Use $(CC), $(AR), PREFIX, DESTDIR and ?= defaults, and your Makefile works unchanged in a distribution package, a cross-compiling CI job, or a developer's ~/.local.

Summary

  • A good Makefile declares .DELETE_ON_ERROR, sets .DEFAULT_GOAL, marks tasks .PHONY, has a help target, and keeps outputs under one directory.
  • C projects: per-configuration output trees, -MMD -MP dependencies, a static library shared by program and tests, and install with PREFIX/DESTDIR. Compile tests without NDEBUG.
  • Python projects: a stamp-file venv that tracks the requirements file, bash strict mode so pipelines can't hide failures, and a deliberate choice between optional and required tools.
  • Pipelines: derive outputs from $(wildcard) inputs, make scripts prerequisites, keep useful intermediates with .SECONDARY, and use &: for multi-output steps.
  • Infrastructure: validate ENV against real files, put variables like TAG into target names, and make plans and other reviewed artifacts real targets that apply consumes.
  • Guards can be $(error) (stops even make -n) or shell checks in the recipe (dry runs still work). Pick per target.

Exercises

Exercise 1: Predict the pipeline's workeasy

With the pipeline fully built, run touch scripts/clean.awk. Which commands should run? Check with make -n before running make -j4.

Show Solution
touch scripts/clean.awk
make -n
mkdir -p build/clean
awk -f scripts/clean.awk data/raw/2026-11-03.csv > build/clean/2026-11-03.csv
mkdir -p build/daily
awk -F, 'NR > 1 { n[$2]++; t[$2] += $3 } END { for (c in n) printf "%s\t%d\t%.2f\n", c, n[c], t[c] }' build/clean/2026-11-03.csv | sort > build/daily/2026-11-03.tsv
mkdir -p build/clean
awk -f scripts/clean.awk data/raw/2026-11-04.csv > build/clean/2026-11-04.csv
[…]
python3 scripts/report.py build/report build/daily/2026-11-03.tsv build/daily/2026-11-04.tsv build/daily/2026-11-05.tsv

Everything: clean.awk is a prerequisite of every cleaned file, so every day is re-cleaned, which changes every daily total's input, which changes the report's inputs. Note that -n prints the @mkdir lines too: a dry run shows silent commands. Editing report.py instead would rebuild only the report.

Exercise 2: Add a destroy planmedium

Add a destroy-plan target to Project 4 that saves a plan destroying everything in ENV, to infra/$(ENV)-destroy.tfplan, so a teardown can be reviewed like any other change. It should appear in make help. Run it against the applied staging environment, then apply the saved plan with Terraform directly.

Show Solution

Add destroy-plan to .PHONY, and this rule:

destroy-plan: .make/tf-init ## Save a plan that destroys everything in ENV
	$(TF) workspace select $(ENV)
	$(TF) plan -destroy -input=false -var-file=envs/$(ENV).tfvars -var image_tag=$(TAG) -out=$(ENV)-destroy.tfplan
make destroy-plan
terraform -chdir=infra apply staging-destroy.tfplan
terraform -chdir=infra workspace select staging
terraform -chdir=infra plan -destroy -input=false -var-file=envs/staging.tfvars -var image_tag=v1.4.0-dirty -out=staging-destroy.tfplan
terraform_data.service: Refreshing state... [id=6efccdfd-ff86-8be9-f9fd-39e626d08a85]
[…]
  # terraform_data.service will be destroyed
  - resource "terraform_data" "service" {
[…]
Plan: 0 to add, 0 to change, 1 to destroy.
[…]
Saved the plan to: staging-destroy.tfplan
[…]
terraform_data.service: Destroying... [id=6efccdfd-ff86-8be9-f9fd-39e626d08a85]
terraform_data.service: Destruction complete after 0s
 
Apply complete! Resources: 0 added, 0 changed, 1 destroyed.

(The tag reads v1.4.0-dirty because editing the Makefile made the checkout dirty.) I made this target phony rather than a file target on purpose: a destroy plan should always reflect the current state, never a cached file. workspace select without -or-create also means a mistyped environment can't create an empty workspace and "destroy" nothing.

Exercise 3: Prove the source tarball buildshard

Add dist and distcheck targets to Project 1. dist creates build/csvstat-1.4.0.tar.gz containing the Makefile and the src, include and tests directories under a top-level csvstat-1.4.0/ directory, and is rebuilt only when one of those files changes. distcheck unpacks the tarball into build/distcheck/ and runs make check inside it, proving the tarball is complete.

Hint

GNU tar's --transform 's,^,PREFIX/,' prepends a directory to every member name. For the nested build, $(MAKE) -C dir check.

Show Solution

Add dist distcheck to .PHONY, and:

VERSION := 1.4.0
DIST    := csvstat-$(VERSION)
 
dist: build/$(DIST).tar.gz ## Build the source tarball
 
build/$(DIST).tar.gz: Makefile $(wildcard src/*.c include/*.h tests/*.c)
	@mkdir -p $(@D)
	tar --transform 's,^,$(DIST)/,' -czf $@ Makefile src include tests
 
distcheck: build/$(DIST).tar.gz ## Unpack the tarball and run its tests
	rm -rf build/distcheck
	mkdir -p build/distcheck
	tar -xzf $< -C build/distcheck
	$(MAKE) -C build/distcheck/$(DIST) check
make distcheck
tar -tzf build/csvstat-1.4.0.tar.gz
tar --transform 's,^,csvstat-1.4.0/,' -czf build/csvstat-1.4.0.tar.gz Makefile src include tests
rm -rf build/distcheck
mkdir -p build/distcheck
tar -xzf build/csvstat-1.4.0.tar.gz -C build/distcheck
make -C build/distcheck/csvstat-1.4.0 check
make[1]: Entering directory '[…]/build/distcheck/csvstat-1.4.0'
mkdir -p build/release
cc -Iinclude -DNDEBUG -UNDEBUG -Wall -Wextra -std=c11 -O2 -MMD -MP -c tests/test_stats.c -o build/release/test_stats.o
cc -Iinclude -DNDEBUG -Wall -Wextra -std=c11 -O2 -MMD -MP -c src/csv.c -o build/release/csv.o
cc -Iinclude -DNDEBUG -Wall -Wextra -std=c11 -O2 -MMD -MP -c src/stats.c -o build/release/stats.o
ar rcs build/release/libcsvstat.a build/release/csv.o build/release/stats.o
cc  build/release/test_stats.o build/release/libcsvstat.a -o build/release/test_stats
./build/release/test_stats
test_stats: all tests passed
make[1]: Leaving directory '[…]/build/distcheck/csvstat-1.4.0'
csvstat-1.4.0/Makefile
csvstat-1.4.0/src/
csvstat-1.4.0/src/stats.c
csvstat-1.4.0/src/csv.c
csvstat-1.4.0/src/main.c
csvstat-1.4.0/include/
csvstat-1.4.0/include/stats.h
csvstat-1.4.0/include/csv.h
csvstat-1.4.0/tests/
csvstat-1.4.0/tests/test_stats.c

The nested build ran from nothing but the tarball's contents, so a header someone forgot to add to the archive would fail here, not on a user's machine. GNU Automake's make distcheck is the industrial version of this idea. data/ was deliberately left out of the tarball: the tests don't need it, and distcheck passing proves that.


Tested with: GNU Make 4.3, GCC 13.3.0, Python 3.12.3, GNU awk and Terraform v1.17.1 on Ubuntu 24.04 (WSL2), November 2026. All four Makefiles, every command and every exercise were run as shown; Terraform's ANSI color codes were stripped from the captured output, absolute paths in Make's directory messages are shortened to […], and long plan output is trimmed where marked. Not run: Docker (not installed on the test machine; the targets were exercised up to their guard and with make -n) and ruff (not installed; the article shows the targets' behavior without it). The Terraform configuration uses only terraform_data, so no cloud account or credentials were involved.

Was this page helpful?
The Dark Debugger

Written by The Dark Debugger

Engineer documenting the things that took me too long to learn, so they take you less time. Every Makefile tutorial here is tested end to end before publishing.