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_GOALset explicitly, so reordering rules or adding anincludecan't change what a baremakedoes.- Every task name in
.PHONY, and every real output a real target, so Make can skip work. - A
helptarget 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/), socleanis onerm -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 checkmkdir -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 passedA header change rebuilds exactly the objects that include it, thanks to -MMD -MP:
touch include/stats.h
makecc -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/csvstatAnd packaging works the way distribution tools expect:
make install PREFIX=/usr DESTDIR=pkgroot
tree --noreport pkgrootinstall -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.aFrom a clean tree, a parallel build of everything plus the tests is safe because the graph is complete:
make clean
make -j4 all checkrm -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 passedWalkthrough
BUILDselects 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 ownCFLAGSstill wins, whileWARNINGSis kept separate so overridingCFLAGSdoesn'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 fromsrc/and one fromtests/. Make tries them in order and uses the first whose source file exists. $(OUT)/test_stats.o: CPPFLAGS += -UNDEBUGis 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.installdepends on the files it installs, not onall, somake installbuilds only what it needs, and usesDESTDIR/PREFIXexactly 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
OKThe 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 venvmake: Nothing to be done for 'venv'.
rm -rf .venv
python3 -m venv --without-pip .venv
touch .venv/.stampWalkthrough
- Bash strict mode (
SHELLand.SHELLFLAGS) is what makes... | tee test-report.txtfail the build when a test fails; withoutpipefail,tee's success would hide it. - The venv is a stamp-file target depending on
requirements.txt.--without-pipis there becauselogsumuses only the standard library and the machine I tested on lacks Ubuntu'spython3.12-venvpackage. In a project with dependencies, the recipe gains$(VENV)/bin/pip install -r requirements.txtbefore thetouch, and tools such as ruff and pytest come from the venv (RUFF ?= $(VENV)/bin/ruff) instead of thePATH. - Optional versus required tools.
lintdegrades gracefully, because a syntax check is still useful without ruff.fmtrefuses 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. ciis 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.pyOne 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,paidscripts/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 buildRunning it
make -j4awk -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.tsvThe 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.txtorder_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.15The 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 --traceMakefile: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.tsvOnly 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.txtawk -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.25With 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.awkand every day is re-cleaned; editreport.pyand only the report is rebuilt. That's Exercise 1. .SECONDARY:keeps thebuild/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 onereport.pyrun 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 failedawkwould 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.tfinfra/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/*.tfplanRunning 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 checkterraform -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 planterraform -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 applyterraform -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.tfplanNow 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 planterraform -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=prodMakefile: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-pushdocker 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.0The Dockerfile itself is four lines (a python:3.12-slim base, copy logsum/, set the
entry point) and was not built.
Walkthrough
TAGfromgit describe, withdevas the fallback outside git, ties the image tag and the plan to the exact commit.-dirtyflags uncommitted changes, which you may want to refuse inapplyfor production.- The plan file is a real target named after
ENVandTAG. 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. ENVis validated against the files ininfra/envs/, so the list of environments lives in one place, and adding one is adding a.tfvarsfile..make/tf-initis a stamp file that re-runsterraform initonly when a.tffile changes. A configuration with registry providers would also depend oninfra/.terraform.lock.hcl.- Shell guard versus
$(error).docker-build's check is a recipe line, somake -nstill 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,
installthat respectsDESTDIR. - 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 passedNDEBUG 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 ahelptarget, and keeps outputs under one directory. - C projects: per-configuration output trees,
-MMD -MPdependencies, a static library shared by program and tests, andinstallwithPREFIX/DESTDIR. Compile tests withoutNDEBUG. - 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
ENVagainst real files, put variables likeTAGinto target names, and make plans and other reviewed artifacts real targets thatapplyconsumes. - Guards can be
$(error)(stops evenmake -n) or shell checks in the recipe (dry runs still work). Pick per target.
Exercises
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 -nmkdir -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.tsvEverything: 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.
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.tfplanmake destroy-plan
terraform -chdir=infra apply staging-destroy.tfplanterraform -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.
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) checkmake distcheck
tar -tzf build/csvstat-1.4.0.tar.gztar --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.cThe 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.
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.