Parallel Builds, Dependency Generation, and Debugging
Make builds fast and correct with -j, compiler-generated header dependencies, order-only and grouped targets, .DELETE_ON_ERROR, and the flags that show why Make did what it did.
By The Dark DebuggerUpdated 31 min read
This article is about the difference between a Makefile that works and one you can trust. We'll run builds in parallel and watch a missing prerequisite break them, let the compiler write the header dependencies, use order-only prerequisites, grouped targets and the special targets that control what Make deletes, and then go through Make's debugging tools and its most common error messages. It builds on pattern rules and Multi-Directory Projects; everything here is GNU Make 4.3.
Why this matters
A build that's correct when run serially, from scratch, on the author's machine is the easy
case. Real builds are incremental (you changed one header), parallel (CI runs make -j8), and
sometimes interrupted (a script failed halfway through writing its output). Each of those
exposes a different kind of Makefile bug, and they all have the same symptom: a build that
"usually works". By the end of this article you'll be able to make each of those bugs happen on
purpose, which is the best way to know you've fixed them.
The project
We'll use csvstat again, a small C program that summarizes a numeric column of a CSV file,
this time in one directory with a generated source file. scripts/gen_version.py reads
VERSION and writes build/version.h and build/version.c, which main.c uses for
--version. Three shell scripts under tests/ are smoke tests.
.
├── Makefile
├── VERSION
├── data
│ └── orders.csv
├── scripts
│ └── gen_version.py
├── src
│ ├── csv.c
│ ├── csv.h
│ ├── main.c
│ ├── stats.c
│ └── stats.h
└── tests
├── smoke-big.sh
├── smoke-empty.sh
└── smoke-orders.shHere's the finished Makefile. Every special line in it gets its own section below.
# csvstat: a parallel-safe single-directory build.
.DELETE_ON_ERROR:
CFLAGS ?= -O2 -Wall -Wextra
CPPFLAGS := -Isrc -Ibuild
DEPFLAGS = -MMD -MP
COLUMN ?= 3
SRCS := $(wildcard src/*.c)
OBJS := $(SRCS:src/%.c=build/%.o) build/version.o
SMOKE := $(patsubst tests/%.sh,%,$(wildcard tests/smoke-*.sh))
.PHONY: all check clean
all: build/csvstat
build/csvstat: $(OBJS)
$(CC) $(LDFLAGS) $^ -o $@
build/%.o: src/%.c | build
$(CC) $(CPPFLAGS) $(CFLAGS) $(DEPFLAGS) -c $< -o $@
build/version.o: build/version.c
$(CC) $(CPPFLAGS) $(CFLAGS) -c $< -o $@
# One run of the generator produces both files (a grouped target).
build/version.c build/version.h &: VERSION scripts/gen_version.py | build
python3 scripts/gen_version.py VERSION build/version
# main.c includes the generated header. The .d files can't say so
# before the first build, so this one dependency is written by hand.
build/main.o: build/version.h
build:
mkdir -p $@
build/report.txt: data/orders.csv build/csvstat
./build/csvstat $(COLUMN) < $< > $@
check: $(SMOKE)
smoke-%: tests/smoke-%.sh build/csvstat
@sh $<
clean:
rm -rf build
-include $(OBJS:.o=.d)make
./build/csvstat --versionmkdir -p build
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/csv.c -o build/csv.o
python3 scripts/gen_version.py VERSION build/version
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/main.c -o build/main.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/stats.c -o build/stats.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -c build/version.c -o build/version.o
cc build/csv.o build/main.o build/stats.o build/version.o -o build/csvstat
csvstat 2.1.0Parallel builds with -j
make -j4 lets Make run up to four recipes at once. It walks the same dependency graph as
always, and any target whose prerequisites are all up to date can start as soon as a job slot
is free. The usual invocation is make -j"$(nproc)", one job per CPU. Plain -j with no
number means "no limit", which on a big project can start hundreds of compilers at once and
exhaust memory; always give a number. -l N (--load-average) additionally holds back new
jobs while the system load is above N, which is useful on shared build machines.
On this tiny project, rebuilding everything (-B) took 0.129 seconds with one job and 0.068
seconds with four. On a project with hundreds of files the ratio is what matters, and it's
why every CI system builds with -j.
Missing prerequisites break parallel builds
Parallel builds are only as correct as the graph. Here's an earlier version of the Makefile,
which the author "fixed" by putting version.o first in the link line:
CFLAGS ?= -O2 -Wall -Wextra
CPPFLAGS := -Isrc -Ibuild
SRCS := $(wildcard src/*.c)
OBJS := $(SRCS:src/%.c=build/%.o)
all: build/csvstat
# version.o goes first, so version.h exists before main.c is compiled
build/csvstat: build/version.o $(OBJS)
$(CC) $(LDFLAGS) $^ -o $@
build/%.o: src/%.c
@mkdir -p build
$(CC) $(CPPFLAGS) $(CFLAGS) -c $< -o $@
build/version.o: build/version.c
$(CC) $(CPPFLAGS) $(CFLAGS) -c $< -o $@
build/version.c build/version.h &: VERSION scripts/gen_version.py
@mkdir -p build
python3 scripts/gen_version.py VERSION build/versionSerially, it works, because Make handles prerequisites left to right and generates the version files first:
makepython3 scripts/gen_version.py VERSION build/version
cc -Isrc -Ibuild -O2 -Wall -Wextra -c build/version.c -o build/version.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -c src/csv.c -o build/csv.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -c src/main.c -o build/main.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -c src/stats.c -o build/stats.o
cc build/version.o build/csv.o build/main.o build/stats.o -o build/csvstatI then ran rm -rf build && make -j4 four times. The first run failed:
python3 scripts/gen_version.py VERSION build/version
cc -Isrc -Ibuild -O2 -Wall -Wextra -c src/csv.c -o build/csv.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -c src/main.c -o build/main.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -c src/stats.c -o build/stats.o
src/main.c:6:10: fatal error: version.h: No such file or directory
6 | #include "version.h"
| ^~~~~~~~~~~
compilation terminated.
make: *** [Makefile:14: build/main.o] Error 1
make: *** Waiting for unfinished jobs....and the other three succeeded. Nothing in the graph says main.o needs version.h, so with
free job slots Make compiled main.c at the same moment Python was still starting up to write
the header. Whether that fails depends on which process wins, which is why parallel-build bugs
show up as "flaky CI" rather than as a clear error.
Ordering prerequisites in a list is never a dependency. The fix is to state the real one,
build/main.o: build/version.h, after which -j can't get it wrong (that's Exercise 3).
.NOTPARALLEL
If you inherit a Makefile you can't fix yet, the special target .NOTPARALLEL: makes Make
ignore -j and run one job at a time. Added to the top of the broken Makefile:
make -j4python3 scripts/gen_version.py VERSION build/version
cc -Isrc -Ibuild -O2 -Wall -Wextra -c build/version.c -o build/version.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -c src/csv.c -o build/csv.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -c src/main.c -o build/main.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -c src/stats.c -o build/stats.o
cc build/version.o build/csv.o build/main.o build/stats.o -o build/csvstatIn GNU Make 4.3 it applies to the whole makefile (sub-makes started with $(MAKE) can still run
in parallel). Make 4.4 added a per-target form and a .WAIT marker, but you can't rely on
4.4 being installed yet. Treat .NOTPARALLEL as a stopgap with a ticket attached, not a fix.
Readable output: --output-sync
Parallel jobs write to the same terminal, so their output interleaves. make check runs three
smoke tests, and with -j4 they run at once:
make -j4 checksmoke-big: start
smoke-big: generating 150000 rows
smoke-empty: start
smoke-orders: start
csvstat: no numeric values in column 2
smoke-empty: ok
smoke-orders: got: count 5 min 15.00 max 310.00 mean 118.13
smoke-orders: ok
smoke-big: summarizing
smoke-big: got: count 150000 min 0.00 max 99.90 mean 49.95
smoke-big: okThree tests, one stream. When one fails in CI, working out which lines belong to it is
miserable. --output-sync (-O) makes Make capture each job's output and print it in one
piece when the job finishes:
make -j4 --output-sync=target checksmoke-empty: start
csvstat: no numeric values in column 2
smoke-empty: ok
smoke-orders: start
smoke-orders: got: count 5 min 15.00 max 310.00 mean 118.13
smoke-orders: ok
smoke-big: start
smoke-big: generating 150000 rows
smoke-big: summarizing
smoke-big: got: count 150000 min 0.00 max 99.90 mean 49.95
smoke-big: okThe modes are target (group by target, the usual choice), line (keep individual lines
intact), recurse (group a whole sub-make's output) and none. The cost is that you don't
see a slow job's output until it finishes, so for interactive work you may prefer the
interleaved stream; in CI logs, always sync.
Automatic header dependencies: -MMD and -MP
build/%.o: src/%.c tells Make that each object depends on its source file. It says nothing
about headers. To see the consequence, run the same Makefile with DEPFLAGS emptied, so no
dependency information is generated, then change a header:
make DEPFLAGS=
touch src/stats.h
make DEPFLAGS=[…]
make: Nothing to be done for 'all'.stats.h defines struct summary, which both main.c and stats.c use. Change a field in
it and Make won't recompile either file, and the two objects will disagree about the struct's
layout. That kind of bug produces garbage at run time rather than an error at build time.
Writing build/main.o: src/csv.h src/stats.h ... by hand for every file doesn't scale and is
wrong the moment someone adds an #include. The compiler already knows which headers it read,
so we ask it to write that down while compiling:
-MMDwrites a.dfile next to the object, in Makefile syntax, listing the source and every non-system header it included. (-MDwould include system headers likestdio.htoo, which only slows Make down.)-MPadds an empty rule for each header. That sounds pointless; the next section shows why it isn't.-include $(OBJS:.o=.d)reads the.dfiles back in. The-means "don't complain about missing ones", which is the normal state on a clean checkout.
With the real Makefile:
cat build/main.dbuild/main.o: src/main.c src/csv.h src/stats.h build/version.h
src/csv.h:
src/stats.h:
build/version.h:touch src/stats.h
makecc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/main.c -o build/main.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/stats.c -o build/stats.o
cc build/csv.o build/main.o build/stats.o build/version.o -o build/csvstatExactly the two files that include stats.h were recompiled; csv.o was left alone. Note the
timing: dependencies are produced by a compile, for use by the next build. That's fine for
ordinary headers. On a clean checkout every object has to be compiled anyway, and after that
the .d files exist.
What -MP is for
Headers get renamed and deleted. Here's what happens without -MP when csv.h is renamed to
csvparse.h (and the two #include lines updated):
make DEPFLAGS=-MMDmake: *** No rule to make target 'src/csv.h', needed by 'build/csv.o'. Stop.The old build/csv.d still says build/csv.o depends on src/csv.h. That file is gone and
nothing can make it, so Make stops, and keeps stopping until someone deletes the build
directory. With -MP, the .d file also contains src/csv.h:, an empty rule that tells Make
"if this file is missing, consider it made". The same rename with the real Makefile just
rebuilds:
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/csv.c -o build/csv.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/main.c -o build/main.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/stats.c -o build/stats.o
cc build/csv.o build/main.o build/stats.o build/version.o -o build/csvstatGenerated headers need one manual line
The race earlier came from a header that doesn't exist until the build creates it. -MMD
can't help with the first build: there's no main.d yet to say main.o needs version.h. So
for generated headers, and only for them, write the dependency yourself:
build/main.o: build/version.h. Make merges it with the rule from the pattern and the .d
file.
Order-only prerequisites
Objects go into build/, so the directory must exist first. The natural way to say that is a
prerequisite, and it's wrong. Here's the pattern rule with build as a normal prerequisite,
built twice:
build/%.o: src/%.c buildmake
makemkdir -p build
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/csv.c -o build/csv.o
[…]
cc build/csv.o build/main.o build/stats.o build/version.o -o build/csvstat
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/csv.c -o build/csv.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/main.c -o build/main.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/stats.c -o build/stats.o
cc build/csv.o build/main.o build/stats.o build/version.o -o build/csvstatThe second run recompiled everything, and so would every run after it. A directory's modification time changes whenever a file inside it is created or deleted:
ls -ld --time-style=full-iso build build/csv.odrwxr-xr-x 2 sid sid 4096 2026-11-10 01:31:08.856098531 -0500 build
-rw-r--r-- 1 sid sid 1648 2026-11-10 01:31:08.796613831 -0500 build/csv.oWriting csvstat and the .d files updated build/ after csv.o was written, so every
object always looks older than its "prerequisite". Prerequisites after a | are order-only:
Make builds them if they don't exist, but never compares their timestamps. That's exactly
right for directories, and it's how the real Makefile spells it:
build/%.o: src/%.c | build.
Order-only prerequisites are also right for anything else whose existence matters but whose changes shouldn't trigger rebuilds, such as a virtualenv (see Make as a Task Runner) or a downloaded toolchain.
Grouped targets: one recipe, several files
gen_version.py writes two files in one run. Before GNU Make 4.3, people wrote that like this:
build/version.c build/version.h: VERSION scripts/gen_version.py | buildThat line doesn't mean what it looks like. Listing several targets in an ordinary rule is
shorthand for several independent rules that happen to share a recipe. Under -j,
main.o asks for version.h and version.o asks for version.c, and Make runs the
recipe once for each:
make -j4mkdir -p build
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/csv.c -o build/csv.o
python3 scripts/gen_version.py VERSION build/version
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/stats.c -o build/stats.o
python3 scripts/gen_version.py VERSION build/version
cc -Isrc -Ibuild -O2 -Wall -Wextra -c build/version.c -o build/version.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/main.c -o build/main.o
cc build/csv.o build/main.o build/stats.o build/version.o -o build/csvstatTwo generator runs writing the same files at the same time (it happened in both of my test
runs). Here that's wasted work; with a code generator that writes files incrementally, a
reader can see a half-written file. GNU Make 4.3 added grouped targets, written with &:.
The targets are produced together by one execution of the recipe:
build/version.c build/version.h &: VERSION scripts/gen_version.py | build
python3 scripts/gen_version.py VERSION build/versionmkdir -p build
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/csv.c -o build/csv.o
python3 scripts/gen_version.py VERSION build/version
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/stats.c -o build/stats.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/main.c -o build/main.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -c build/version.c -o build/version.o
cc build/csv.o build/main.o build/stats.o build/version.o -o build/csvstatOne run. If you must support Make older than 4.3 (macOS's bundled 3.81, for instance), there are two traditional workarounds: a pattern rule with several targets, which GNU Make has always treated as one recipe producing all of them, or a stamp file that the generator rule touches and both outputs depend on.
.DELETE_ON_ERROR: don't keep broken outputs
The Makefile has a report target that runs our program with shell redirection:
build/report.txt: data/orders.csv build/csvstat
./build/csvstat $(COLUMN) < $< > $@The shell creates build/report.txt before csvstat even starts. If csvstat then fails,
the file is left behind, empty, with a fresh timestamp. Without .DELETE_ON_ERROR, asking for
column 2 (which has no numbers) went like this:
make build/report.txt COLUMN=2
make build/report.txt COLUMN=2
ls -l build/report.txt./build/csvstat 2 < data/orders.csv > build/report.txt
csvstat: no numeric values in column 2
make: *** [Makefile:36: build/report.txt] Error 1
make: 'build/report.txt' is up to date.
-rw-r--r-- 1 sid sid 0 Nov 10 01:31 build/report.txtThe second run succeeded. A failed build turned into a successful one just by running it
again, with an empty report as the result. In CI with retries, that's how broken artifacts get
published. With .DELETE_ON_ERROR: in the Makefile:
./build/csvstat 2 < data/orders.csv > build/report.txt
csvstat: no numeric values in column 2
make: *** [Makefile:37: build/report.txt] Error 1
make: *** Deleting file 'build/report.txt'and every retry fails the same way until the problem is fixed. There's no good reason to leave it out; the GNU Make manual says it's almost always what you want and is only off by default for historical compatibility. Make also deletes the target when you interrupt it with Ctrl+C, with or without this setting.
Intermediate files: .INTERMEDIATE, .SECONDARY and .PRECIOUS
When Make chains pattern rules to reach a target, the files in the middle are intermediate, and Make deletes them when it's done. A small data pipeline shows it. Monthly order exports arrive gzipped, and each gets a one-line report:
# Monthly order exports arrive gzipped; each gets a one-line report.
REPORTS := $(patsubst exports/%.csv.gz,reports/%.txt,$(wildcard exports/*.csv.gz))
all: $(REPORTS)
work/%.csv: exports/%.csv.gz
@mkdir -p $(@D)
gzip -dc $< > $@
reports/%.txt: work/%.csv
@mkdir -p $(@D)
awk -F, 'NR > 1 { n++; t += $$3 } END { printf "%d orders, %.2f total\n", n, t }' $< > $@make
ls work reports
cat reports/2026-11.txtgzip -dc exports/2026-10.csv.gz > work/2026-10.csv
awk -F, 'NR > 1 { n++; t += $3 } END { printf "%d orders, %.2f total\n", n, t }' work/2026-10.csv > reports/2026-10.txt
gzip -dc exports/2026-11.csv.gz > work/2026-11.csv
awk -F, 'NR > 1 { n++; t += $3 } END { printf "%d orders, %.2f total\n", n, t }' work/2026-11.csv > reports/2026-11.txt
rm work/2026-10.csv work/2026-11.csv
reports:
2026-10.txt
2026-11.txt
work:
4 orders, 575.65 totalThe rm at the end is Make's own doing. The work/*.csv files were never mentioned
explicitly, only reached through the work/%.csv pattern, so Make treated them as disposable.
It also remembers that they don't need to exist: a second make says
Nothing to be done for 'all'. even though work/ is empty, and touching one export rebuilds
just that month, deleting its intermediate again. For decompressed exports that's a sensible
default: they're big and easily recreated.
When you want to keep them (to inspect the data, or because recreating them is slow), there are three special targets:
| Special target | Effect |
|---|---|
.SECONDARY: files | Treat the files as intermediate (don't rebuild them just because they're missing) but never delete them. With no prerequisites, applies to every target. |
.INTERMEDIATE: files | Mark explicitly mentioned files as intermediate, so they're deleted after use. |
.PRECIOUS: files | Never delete these, not even when Make is interrupted or a recipe fails. Accepts patterns like work/%.csv. |
Adding .SECONDARY: to the pipeline and rebuilding from scratch:
gzip -dc exports/2026-10.csv.gz > work/2026-10.csv
awk -F, 'NR > 1 { n++; t += $3 } END { printf "%d orders, %.2f total\n", n, t }' work/2026-10.csv > reports/2026-10.txt
gzip -dc exports/2026-11.csv.gz > work/2026-11.csv
awk -F, 'NR > 1 { n++; t += $3 } END { printf "%d orders, %.2f total\n", n, t }' work/2026-11.csv > reports/2026-11.txtNo rm line, and ls work now lists both CSVs. Be careful with .PRECIOUS on outputs that can
be half-written: it overrides .DELETE_ON_ERROR, which is exactly the protection you wanted.
Debugging a Makefile
When Make does something surprising, it can tell you why. Each of these examples starts with
touch src/csv.h on an up-to-date build.
make -n: what would run
make -ncc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/csv.c -o build/csv.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/main.c -o build/main.o
cc build/csv.o build/main.o build/stats.o build/version.o -o build/csvstatA dry run prints the recipes without executing them, with variables expanded, so it's also the
quickest way to see the exact compiler command line. Two caveats: lines containing $(MAKE)
are executed (so recursive builds can dry-run their sub-makes), and a dry run can't show
what a recipe would do differently after an earlier one ran.
--trace and --debug=b: why it runs
make --traceMakefile:20: update target 'build/csv.o' due to: src/csv.h
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/csv.c -o build/csv.o
Makefile:20: update target 'build/main.o' due to: src/csv.h
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/main.c -o build/main.o
Makefile:17: update target 'build/csvstat' due to: build/csv.o build/main.o
cc build/csv.o build/main.o build/stats.o build/version.o -o build/csvstat--trace is the one I reach for first: for each recipe, the line of the Makefile it came from
and the prerequisites that triggered it. --debug=b ("basic") tells the same story as a
decision log:
make --debug=bGNU Make 4.3
[…]
Reading makefiles...
Updating makefiles....
Updating goal targets....
File 'all' does not exist.
Prerequisite 'src/csv.h' is newer than target 'build/csv.o'.
Must remake target 'build/csv.o'.
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/csv.c -o build/csv.o
Successfully remade target file 'build/csv.o'.
Prerequisite 'src/csv.h' is newer than target 'build/main.o'.
Must remake target 'build/main.o'.
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/main.c -o build/main.o
Successfully remade target file 'build/main.o'.
Prerequisite 'build/csv.o' is newer than target 'build/csvstat'.
Prerequisite 'build/main.o' is newer than target 'build/csvstat'.
Must remake target 'build/csvstat'.
cc build/csv.o build/main.o build/stats.o build/version.o -o build/csvstat
Successfully remade target file 'build/csvstat'.
Must remake target 'all'.
Successfully remade target file 'all'.make -p: what Make believes
-p prints Make's entire database after reading the Makefiles: every variable with its value
and origin, every rule, and every built-in rule. It's thousands of lines, so grep it. This shows
what build/main.o actually depends on, after the pattern rule, the hand-written line and the
.d file were merged:
make -p | grep -A4 '^build/main.o:'build/main.o: src/main.c build/version.h src/main.c src/csv.h src/stats.h build/version.h | build
# Implicit rule search has been done.
# Implicit/static pattern stem: 'main'
# Last modified 2026-11-10 01:31:09.68312568
# File has been updated.Add -n to look at variables without building anything, or use -f /dev/null to see Make's
built-in rules on their own:
make -pn | grep -E '^(OBJS|SMOKE) :='
make -p -f /dev/null | grep -A3 '^%.o: %.c'OBJS := build/csv.o build/main.o build/stats.o build/version.o
SMOKE := smoke-big smoke-empty smoke-orders
make: *** No targets. Stop.
%.o: %.c
# recipe to execute (built-in):
$(COMPILE.c) $(OUTPUT_OPTION) $<
[…]make -d: everything
-d is --debug=a, every decision Make makes, including the implicit-rule search. For this
five-file project, one incremental build produced 3,531 lines. It's occasionally the only way to
answer "why did Make pick that rule?", and grep is mandatory:
make -d | grep -n 'build/csv.o' | head -82370: Considering target file 'build/csv.o'.
2371: Looking for an implicit rule for 'build/csv.o'.
2375: Found an implicit rule for 'build/csv.o'.
2463: Finished prerequisites of target file 'build/csv.o'.
2464: Prerequisite 'src/csv.c' is older than target 'build/csv.o'.
2465: Prerequisite 'build' is order-only for target 'build/csv.o'.
2466: Prerequisite 'src/csv.c' is older than target 'build/csv.o'.
2467: Prerequisite 'src/csv.h' is newer than target 'build/csv.o'.$(info), $(warning), $(error) and --warn-undefined-variables
The print functions run while Make reads the file, so they're the printf of Makefile
debugging. $(warning) and $(error) prefix the file and line number; $(error) also stops.
This file has a deliberate typo on its last line:
SRCS := $(wildcard src/*.c)
OBJS := $(SRCS:src/%.c=build/%.o)
$(info SRCS = $(SRCS))
$(info OBJS = $(OBJS))
ifeq ($(OBJS),)
$(warning no sources found under src/)
endif
.PHONY: all
all:
@echo "would link: $(OBJS)"
@echo "flags: $(CFLGAS)"make --warn-undefined-variablesSRCS = src/csv.c src/main.c src/stats.c
OBJS = build/csv.o build/main.o build/stats.o
Makefile:13: warning: undefined variable 'CFLGAS'
would link: build/csv.o build/main.o build/stats.o
flags: Without the flag, the typo silently expands to nothing. And in a directory with no src/:
SRCS =
OBJS =
Makefile:7: no sources found under src/
would link:
flags: --warn-undefined-variables is noisy on large Makefiles that rely on empty defaults, so I use it
as a one-off check rather than leaving it on.
Common error messages, decoded
| Message | What it means | Usual fix |
|---|---|---|
missing separator. Stop. | A recipe line doesn't start with a TAB, or a line isn't valid Make syntax | Use a TAB; see Introduction to Make |
No rule to make target 'X', needed by 'Y'. Stop. | X doesn't exist and no rule builds it | Typo, a missing file, a stale .d file (use -MP), or a missing ordering under -j |
recipe commences before first target. Stop. | A TAB-indented line that isn't valid Make syntax appears before any rule | Remove the TAB, or move the line into a rule |
warning: overriding recipe for target 'X' | Two rules with recipes for the same target; the last one wins | Usually two included files both define clean or similar; merge them |
Circular X <- Y dependency dropped. | X depends on Y, which depends on X | Rethink the graph; Make silently drops one edge |
*** [Makefile:N: target] Error 1 | The recipe at line N exited with status 1 | Read the output just above it; that's the real error |
Error 127 | The shell couldn't find the command | Tool not installed, or not on PATH |
Nothing to be done for 'X' / 'X' is up to date | X needed no work: the first when the goal has no recipe of its own (typical for all), the second when a file target was already current | Not an error; if surprising, use --trace |
Three of these, reproduced:
CFLAGS := -O2
@echo "configuring with $(CFLAGS)"
all:
@echo "building"Makefile:2: *** recipe commences before first target. Stop..PHONY: clean
clean:
rm -rf build
# ...two hundred lines later, or in an included file...
clean:
rm -rf build distMakefile:7: warning: overriding recipe for target 'clean'
Makefile:3: warning: ignoring old recipe for target 'clean'
rm -rf build distreport.txt: summary.txt
cat summary.txt > report.txt
summary.txt: report.txt
echo "summary" > summary.txtmake: Circular summary.txt <- report.txt dependency dropped.
echo "summary" > summary.txt
cat summary.txt > report.txtThe circular case is the dangerous one, because it "works": Make drops an edge and builds anyway, and the warning scrolls away in a long build.
Where you'll use this
- CI pipelines.
make -j"$(nproc)" --output-sync=targetis the standard CI invocation: fast, with logs you can read. If a build only fails under-j, you now know to look for a missing prerequisite, not a flaky machine. - C and C++ projects of any size.
-MMD -MPplus-includeis how hand-written GNU Makefiles track headers; CMake and Meson generate the equivalent for you. - Data pipelines.
.DELETE_ON_ERRORand intermediate-file control matter as soon as outputs are produced by scripts that can fail halfway, and grouped targets fit any tool that writes several files at once. - Inherited Makefiles.
--trace,-pand--warn-undefined-variablesare how you learn what a 2,000-line Makefile actually does before you change it.
The CI invocation on this project, from a clean tree:
make clean && make -j4 --output-sync=target checkrm -rf build
mkdir -p build
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/stats.c -o build/stats.o
python3 scripts/gen_version.py VERSION build/version
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/csv.c -o build/csv.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -c build/version.c -o build/version.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/main.c -o build/main.o
cc build/csv.o build/main.o build/stats.o build/version.o -o build/csvstat
smoke-empty: start
csvstat: no numeric values in column 2
smoke-empty: ok
smoke-orders: start
smoke-orders: got: count 5 min 15.00 max 310.00 mean 118.13
smoke-orders: ok
smoke-big: start
smoke-big: generating 150000 rows
smoke-big: summarizing
smoke-big: got: count 150000 min 0.00 max 99.90 mean 49.95
smoke-big: okNotice that main.c was compiled after the generator ran, while stats.c and csv.c, which
don't need the generated header, started straight away. That's the graph doing its job.
Common mistakes
A build that only fails with -j
fatal error: version.h: No such file or directory, or a link that can't find a library, on
some CI runs but never locally. Something reads a file that its rule doesn't list as a
prerequisite, and serial order was hiding it. Find the file in the error, find the target
that reads it, and add the dependency. make --trace on a serial build shows the order you've
been relying on.
"No rule to make target 'src/csv.h'" after renaming a header
The .d files from the previous build still mention the old name. With -MP in your
dependency flags this can't happen; without it, rm -rf build gets you going, and adding -MP
stops it recurring.
Everything rebuilds every time
Usually a directory, or a phony target, listed as a normal prerequisite of real files.
make --trace says due to: build (or the phony target's name). Make it order-only with |.
A failed build that "succeeds" on the second try
An output file was created by > before the command failed. Add .DELETE_ON_ERROR: to every
Makefile; it costs nothing.
Summary
make -j"$(nproc)"runs independent recipes in parallel. Never use bare-j. A build that only fails under-jhas a missing prerequisite; list order is not a dependency.--output-sync=targetkeeps each job's output together; use it in CI..NOTPARALLEL:serializes a Makefile you can't fix yet.-MMD -MPmakes the compiler write.ddependency files and-includereads them.-MPkeeps renamed or deleted headers from breaking the build. Generated headers still need one hand-written dependency.- Prerequisites after
|are order-only: built if missing, timestamps ignored. Use them for output directories. a b &: deps(GNU Make 4.3+) declares one recipe that produces several files; without&,-jcan run the recipe once per target..DELETE_ON_ERROR:deletes a target whose recipe failed. Intermediate files are deleted after use unless kept with.SECONDARYor.PRECIOUS.- Debug with
-n(what),--traceand--debug=b(why),-p(what Make believes),-d(everything), and$(info)/$(warning)plus--warn-undefined-variables.
Exercises
With everything built, run touch src/stats.h. Before running Make, write down which commands
should run. Then check with make --trace.
Show Solution
touch src/stats.h
make --traceMakefile:20: update target 'build/main.o' due to: src/stats.h
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/main.c -o build/main.o
Makefile:20: update target 'build/stats.o' due to: src/stats.h
cc -Isrc -Ibuild -O2 -Wall -Wextra -MMD -MP -c src/stats.c -o build/stats.o
Makefile:17: update target 'build/csvstat' due to: build/main.o build/stats.o
cc build/csv.o build/main.o build/stats.o build/version.o -o build/csvstatmain.c and stats.c include stats.h (the .d files say so); csv.c doesn't, so csv.o is
reused, and version.o doesn't depend on any of it. The link runs because two of its objects
changed. If your prediction included csv.o, check with cat build/csv.d.
Add a pattern rule so that make print-OBJS prints OBJS= followed by its value, for any
variable name. Use it to print OBJS, SMOKE and DEPFLAGS in one command.
Hint
In a pattern rule, $* is the part matched by %. $($*) is then the value of the variable
with that name.
Show Solution
print-%:
@echo '$*=$($*)'make print-OBJS print-SMOKE print-DEPFLAGSOBJS=build/csv.o build/main.o build/stats.o build/version.o
SMOKE=smoke-big smoke-empty smoke-orders
DEPFLAGS=-MMD -MPUnlike $(info), this needs no edit to the Makefile each time you want to look at something,
and unlike make -p it shows the value fully expanded the way a recipe would see it. Many
teams keep this rule permanently. The single quotes matter if a value contains characters the
shell would interpret, though a value containing a single quote will still break it.
Take the broken Makefile from Missing prerequisites break parallel
builds. Fix it properly: state the real
dependency, and stop relying on the order of the link line. Then prove the fix by building
from scratch with -j4 several times in a row.
Show Solution
CFLAGS ?= -O2 -Wall -Wextra
CPPFLAGS := -Isrc -Ibuild
SRCS := $(wildcard src/*.c)
OBJS := $(SRCS:src/%.c=build/%.o) build/version.o
all: build/csvstat
build/csvstat: $(OBJS)
$(CC) $(LDFLAGS) $^ -o $@
build/%.o: src/%.c
@mkdir -p build
$(CC) $(CPPFLAGS) $(CFLAGS) -c $< -o $@
build/version.o: build/version.c
$(CC) $(CPPFLAGS) $(CFLAGS) -c $< -o $@
build/version.c build/version.h &: VERSION scripts/gen_version.py
@mkdir -p build
python3 scripts/gen_version.py VERSION build/version
build/main.o: build/version.hfor i in 1 2 3 4 5 6; do rm -rf build; make -j4 >/dev/null 2>&1; echo "run $i: exit $?"; done
make -j4 -Brun 1: exit 0
run 2: exit 0
run 3: exit 0
run 4: exit 0
run 5: exit 0
run 6: exit 0
cc -Isrc -Ibuild -O2 -Wall -Wextra -c src/csv.c -o build/csv.o
python3 scripts/gen_version.py VERSION build/version
cc -Isrc -Ibuild -O2 -Wall -Wextra -c src/stats.c -o build/stats.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -c build/version.c -o build/version.o
cc -Isrc -Ibuild -O2 -Wall -Wextra -c src/main.c -o build/main.o
cc build/csv.o build/main.o build/stats.o build/version.o -o build/csvstatSix clean parallel builds, six successes, and in the -B run main.c is compiled only after
the generator. A loop like this is a cheap way to gain confidence in a parallel fix, but it
can't prove the absence of a race. The real proof is that every file a recipe reads is now in
its prerequisites.
make check runs every smoke test every time. Change it so each test writes its output to
build/smoke-NAME.log, and the log is a real target that depends on the test script and the
binary. A passing test should print just its last line; a failing test should print its whole
log, fail the build, and not leave a log behind (so it reruns next time). Show: a first run,
a second run that does nothing, a run after touching one test, and a failing test.
Hint
Replace the smoke-% rule with build/smoke-%.log: tests/smoke-%.sh build/csvstat, and make
check depend on $(SMOKE:%=build/%.log). In the recipe, redirect the script's output to $@
and print it with cat if the script fails. Which special target already handles "don't leave
a log behind"?
Show Solution
check: $(SMOKE:%=build/%.log)
build/smoke-%.log: tests/smoke-%.sh build/csvstat
sh $< > $@ 2>&1 || { cat $@; exit 1; }
@tail -n 1 $@make check
make check
touch tests/smoke-orders.sh
make check[…]
sh tests/smoke-big.sh > build/smoke-big.log 2>&1 || { cat build/smoke-big.log; exit 1; }
smoke-big: ok
sh tests/smoke-empty.sh > build/smoke-empty.log 2>&1 || { cat build/smoke-empty.log; exit 1; }
smoke-empty: ok
sh tests/smoke-orders.sh > build/smoke-orders.log 2>&1 || { cat build/smoke-orders.log; exit 1; }
smoke-orders: ok
make: Nothing to be done for 'check'.
sh tests/smoke-orders.sh > build/smoke-orders.log 2>&1 || { cat build/smoke-orders.log; exit 1; }
smoke-orders: ok(The trimmed lines at the top are the program being built.) To see a failure, I changed the
expected mean in smoke-orders.sh to a wrong value:
sed -i 's/118.13/118.14/' tests/smoke-orders.sh
make check
ls build/smoke-orders.logsh tests/smoke-orders.sh > build/smoke-orders.log 2>&1 || { cat build/smoke-orders.log; exit 1; }
smoke-orders: start
smoke-orders: got: count 5 min 15.00 max 310.00 mean 118.13
smoke-orders: FAIL
make: *** [Makefile:42: build/smoke-orders.log] Error 1
make: *** Deleting file 'build/smoke-orders.log'
ls: cannot access 'build/smoke-orders.log': No such file or directory.DELETE_ON_ERROR removed the failed log, so the test will run again next time instead of
counting as "up to date". Rebuilding the binary reruns every test, because every log depends on
it. Logs as targets also give you parallel tests for free: make -j4 check runs them
concurrently, and the logs keep their output separate without --output-sync.
Tested with: GNU Make 4.3, GCC 13.3.0 and Python 3.12.3 on Ubuntu 24.04 (WSL2) with 8 CPUs,
November 2026. Every Makefile and command above was run as shown; trimmed output is marked
[…]. The parallel race in the broken Makefile failed on one of four clean -j4 builds, and
the ungrouped generator ran twice in both runs I tried; on your machine the interleaving, and
how often the race fires, will differ. GNU Make 4.4 features (per-target .NOTPARALLEL,
.WAIT) are mentioned but were not tested.
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.