Introduction to Make
What GNU Make is, how it uses a dependency graph and file timestamps to rebuild only what changed, and how it compares with CMake, Ninja, just and Task.
By The Dark DebuggerUpdated 20 min read
This is the first article in the Make path. We'll take a small reporting job that a shell script rebuilds from scratch on every run, rewrite it as a Makefile, and watch Make skip the work that doesn't need redoing. Then we'll look at where Make is used today and how it compares with CMake, Ninja, just and Task. You need to be comfortable running commands in a terminal (Introduction to Bash covers that). You don't need to know C.
The problem: rebuilding everything, every time
Here is a small but realistic job. A shop exports one CSV of sales per region. A script turns each export into a one-line summary, and the summaries are stitched together into a report.
.
├── build.sh
├── data
│ ├── north.csv
│ └── south.csv
└── summarize.shdata/north.csv looks like this:
date,sku,units,unit_price
2026-11-02,KB-104,3,49.00
2026-11-02,MS-220,5,19.50
2026-11-03,KB-104,1,49.00
2026-11-03,HD-310,2,89.99summarize.sh does the per-region work with awk (see
awk: Processing Columns and Records if the awk part is
new to you):
#!/bin/sh
# Usage: ./summarize.sh data/REGION.csv
# Prints one line: region, units sold, revenue.
region=$(basename "$1" .csv)
awk -F, -v region="$region" '
NR > 1 { units += $3; revenue += $3 * $4 }
END { printf "%-6s %4d units %10.2f\n", region, units, revenue }
' "$1"And build.sh is the obvious way to run the whole job:
#!/bin/sh
set -e
mkdir -p build
for csv in data/*.csv; do
out="build/$(basename "$csv" .csv).txt"
echo "summarizing $csv -> $out"
./summarize.sh "$csv" > "$out"
done
echo "writing report.txt"
cat build/*.txt > report.txtRun it twice in a row:
./build.sh
./build.sh
cat report.txtsummarizing data/north.csv -> build/north.txt
summarizing data/south.csv -> build/south.txt
writing report.txt
summarizing data/north.csv -> build/north.txt
summarizing data/south.csv -> build/south.txt
writing report.txt
north 11 units 473.48
south 13 units 441.99The second run redid everything, even though nothing had changed. With two small CSVs that costs nothing. Now picture 300 regional exports, or a step that queries a data warehouse, compiles a C file, or renders a PDF. Every edit to one input costs you the whole pipeline.
You could fix that by hand: wrap each step in if [ "$csv" -nt "$out" ] ("is the CSV newer
than the output?"). Then you'd need the same check for the report against every summary, and
again for the script itself. Keep going and you have written a worse version of Make.
What Make is
Make is a program that reads a file called Makefile and brings a set of files up to date.
It needs three ingredients, and the rest of this path is mostly detail on these three:
- A dependency graph. Each rule names a target (a file to produce) and its prerequisites (the files it is made from).
- Timestamps. A target is out of date when it doesn't exist, or when any prerequisite has a newer modification time than the target.
- Recipes. Shell commands that rebuild a target. Make hands each line to
/bin/sh.
Here is the same job as a Makefile:
report.txt: build/north.txt build/south.txt
cat build/north.txt build/south.txt > report.txt
build/north.txt: data/north.csv
mkdir -p build
./summarize.sh data/north.csv > build/north.txt
build/south.txt: data/south.csv
mkdir -p build
./summarize.sh data/south.csv > build/south.txtRead the first rule as "report.txt is made from the two summaries, by running this cat
command". The indented lines are the recipe, and the indentation must be a real TAB
character, not spaces. cat -A makes the difference visible, printing a tab as ^I and each
line end as $:
cat -A Makefilereport.txt: build/north.txt build/south.txt$
^Icat build/north.txt build/south.txt > report.txt$
$
build/north.txt: data/north.csv$
^Imkdir -p build$
^I./summarize.sh data/north.csv > build/north.txt$
$
build/south.txt: data/south.csv$
^Imkdir -p build$
^I./summarize.sh data/south.csv > build/south.txt$Run make with no arguments:
makemkdir -p build
./summarize.sh data/north.csv > build/north.txt
mkdir -p build
./summarize.sh data/south.csv > build/south.txt
cat build/north.txt build/south.txt > report.txtMake started at the first target in the file, report.txt. Before it could decide anything
about the report it had to bring both prerequisites up to date, so it followed each one down
to its own rule, built the summaries, and built the report last. It printed every command
before running it. That echo is why the output looks like a transcript.
Now run it again without changing anything:
makemake: 'report.txt' is up to date.Nothing ran. That one line is the reason Make exists.
Changing one input
Add a sale to the south region and rebuild:
echo '2026-11-05,MS-220,2,19.50' >> data/south.csv
make
cat report.txtmkdir -p build
./summarize.sh data/south.csv > build/south.txt
cat build/north.txt build/south.txt > report.txt
north 11 units 473.48
south 15 units 480.99The north summary was left alone. Make rebuilt the south summary because its CSV changed, and then the report because one of its prerequisites had just changed. That chain is the dependency graph at work:
report.txt
/ \
build/north.txt build/south.txt
| |
data/north.csv data/south.csvA change anywhere in the graph flows upward to everything that depends on it, and nowhere else.
How Make decides: modification times
Make doesn't remember anything between runs. There is no database and no cache file. It looks at the filesystem every time. Here are the modification times from the build above:
stat -c '%y %n' data/north.csv build/north.txt data/south.csv build/south.txt report.txt2026-11-09 21:39:31.274375281 -0500 data/north.csv
2026-11-09 21:39:31.386375277 -0500 build/north.txt
2026-11-09 21:39:32.414375238 -0500 data/south.csv
2026-11-09 21:39:32.426375238 -0500 build/south.txt
2026-11-09 21:39:32.432574570 -0500 report.txtEvery output is newer than its inputs, so everything is up to date. GNU Make compares these times at full nanosecond resolution on Linux, so even targets built in the same second are ordered correctly.
You can ask Make to explain its reasoning with --debug=b (b for "basic"). Touch the north
CSV and rebuild:
touch data/north.csv
make --debug=bGNU Make 4.3
[…]
Reading makefiles...
Updating makefiles....
Updating goal targets....
Prerequisite 'data/north.csv' is newer than target 'build/north.txt'.
Must remake target 'build/north.txt'.
mkdir -p build
./summarize.sh data/north.csv > build/north.txt
Successfully remade target file 'build/north.txt'.
Prerequisite 'build/north.txt' is newer than target 'report.txt'.
Must remake target 'report.txt'.
cat build/north.txt build/south.txt > report.txt
Successfully remade target file 'report.txt'."Prerequisite X is newer than target Y" is the whole decision procedure. I've trimmed the
version banner that --debug prints first. Note what touch did: the file's content didn't
change, only its timestamp, and Make rebuilt anyway. Make compares times, never contents. Two
consequences are worth knowing early:
- Anything that bumps a timestamp triggers a rebuild:
touch, re-saving a file in your editor without changes, agit checkoutthat rewrites the file. A rebuild you didn't need wastes time, but it is never wrong. - Anything that makes an input look older than it is can hide a change. Copying a file in
with
cp -p(which preserves the old timestamp) or a machine whose clock is behind can leave a stale target that Make believes is fresh. If you ever doubt a build,make -Brebuilds everything regardless of timestamps.
Deleting an output is also safe. Make notices the missing file and rebuilds just that part:
rm build/south.txt
makemkdir -p build
./summarize.sh data/south.csv > build/south.txt
cat build/north.txt build/south.txt > report.txtMake only knows what you tell it
Here is the trap that catches everyone once. Change the summary script so revenue is labelled with a currency:
sed -i 's/%10.2f/%10.2f USD/' summarize.sh
grep printf summarize.sh
make
cat report.txt END { printf "%-6s %4d units %10.2f USD\n", region, units, revenue }
make: 'report.txt' is up to date.
north 11 units 473.48
south 15 units 480.99The report is stale and Make is perfectly happy. The rules never said the summaries depend
on summarize.sh, so as far as Make knows, editing it can't affect anything. The fix is to
list the script as a prerequisite of every target it produces:
report.txt: build/north.txt build/south.txt
cat build/north.txt build/south.txt > report.txt
build/north.txt: data/north.csv summarize.sh
mkdir -p build
./summarize.sh data/north.csv > build/north.txt
build/south.txt: data/south.csv summarize.sh
mkdir -p build
./summarize.sh data/south.csv > build/south.txtmake
cat report.txtmkdir -p build
./summarize.sh data/north.csv > build/north.txt
mkdir -p build
./summarize.sh data/south.csv > build/south.txt
cat build/north.txt build/south.txt > report.txt
north 11 units 473.48 USD
south 15 units 480.99 USDBoth summaries were rebuilt because summarize.sh was now newer than both of them. The
lesson generalises: every file whose change should trigger a rebuild must appear as a
prerequisite. That means scripts, config files and, in C projects, header files. Forgetting
one gives you a build that is silently out of date. That's worse than a slow build. Later
in the path, dependency generation shows how to
get the compiler to write the header list for you.
Where you'll use this
Make has been around since 1976. It's still in daily use because it ships with nearly every Unix-like build environment and the idea underneath it hasn't aged. These are the places you will run into it:
- C and C++ builds. The Linux kernel's build system (Kbuild) is written in GNU Make. You
configure and build a kernel with
make menuconfigandmake -j"$(nproc)". Git, Redis and CPython (./configure && make) all build with Make. Tools like Autoconf and CMake generate Makefiles, so even projects that don't hand-write one often end up running Make. - Task runners for Go, Python and JavaScript projects. A short Makefile with
make test,make lintandmake docker-buildgives humans and CI the same entry point, whatever tools sit underneath. Make as a Task Runner covers this pattern in depth. - Data pipelines and research. Anything shaped like "raw files in, derived files out": the sales report above, regenerating plots for a paper, rebuilding a LaTeX PDF when a figure changes.
- Documentation. Sphinx's
sphinx-quickstartgenerates a Makefile for you, somake htmlis how most Python projects build their docs. - Packaging. Linux distributions build thousands of packages with the same convention:
make, thenmake install DESTDIR=...into a staging directory. We'll see why that variable exists in Variables and How Make Expands Them.
Here is a complete example of the task-runner case, a small Python tool that totals invoices per customer. One Makefile does both jobs Make is good at: it builds a file only when its inputs change, and it gives the project named commands.
.
├── Makefile
├── invoices.py
├── orders.csv
└── test_invoices.py.PHONY: test summary clean
summary: build/summary.json
build/summary.json: orders.csv invoices.py
mkdir -p build
python3 invoices.py orders.csv > build/summary.json
test:
python3 -m unittest -v
clean:
rm -rf build __pycache__.PHONY tells Make that test, summary and clean are command names, not files. You'll
see exactly why that matters in Your First Makefile.
summary is the first target, so a bare make builds the JSON:
make
cat build/summary.json
makemkdir -p build
python3 invoices.py orders.csv > build/summary.json
{
"acme": 290.25,
"globex": 99.5
}
make: Nothing to be done for 'summary'.On the second run Make says "Nothing to be done for 'summary'" instead of "is up to date".
summary is phony and has no recipe of its own, so there was nothing to run once its
prerequisite was fresh. make test, on the other hand, runs every time, which is what you
want from a test command:
make testpython3 -m unittest -v
test_sums_per_customer (test_invoices.TotalsTest.test_sums_per_customer) ... ok
----------------------------------------------------------------------
Ran 1 test in 0.000s
OKGNU Make, BSD make, and the alternatives
"Make" is a family of programs. This path teaches GNU Make, the one installed as make
on every Linux distribution, in WSL and in almost every CI image. The others you'll meet:
- BSD make. FreeBSD, OpenBSD and NetBSD ship their own
make, with different syntax for conditionals (.if), includes (.include) and variable modifiers (${VAR:S/old/new/}). GNU Make is available there as a package and runs asgmake. A GNU Makefile that uses functions like$(patsubst ...)won't run under BSD make. - POSIX make. The subset of features that every make agrees on: plain rules, simple
variables, suffix rules. It's portable, but it has no
%pattern rules and no functions. You'll rarely write strict POSIX Makefiles, but it helps to know where the line is. See Conditionals and Portable Makefiles. - GNU Make 3.81 on macOS. Apple's command-line tools still ship a 2006 release. Why, and what to do about it, is in Installing GNU Make.
To see the difference for real, I unpacked Ubuntu's bmake package (NetBSD make, version
20200710) next to GNU Make. The sales-report Makefile only uses plain rules, so BSD make runs
it unchanged:
bmake
bmakemkdir -p build
./summarize.sh data/north.csv > build/north.txt
mkdir -p build
./summarize.sh data/south.csv > build/south.txt
cat build/north.txt build/south.txt > report.txt
`report.txt' is up to date.Extensions are where the dialects split. Here is a file written in BSD syntax, with a
.if conditional and a ${VAR:.c=.o} modifier:
SRCS = main.c parse.c report.c
OBJS = ${SRCS:.c=.o}
.if ${DEBUG:U0} == 1
CFLAGS += -g
.endif
show:
@echo ${OBJS}bmake -f bsd.mk
make -f bsd.mkmain.o parse.o report.o
bsd.mk:4: *** missing separator. Stop.GNU Make chokes on the .if line. The reverse fails too: a GNU Makefile using ifeq and
$(patsubst ...) stops BSD make with "Missing dependency operator". If a project's README
says to run gmake, this is why.
And the tools people reach for instead of Make:
| Tool | What it is | Where it wins | What it costs |
|---|---|---|---|
| CMake | A generator: you describe a C/C++ project, it writes Makefiles, Ninja files or Visual Studio projects | Cross-platform C/C++, Windows/MSVC support, finding libraries | Its own language to learn; when a build fails you debug generated files |
| Ninja | A small, very fast build executor | Huge trees where a no-op rebuild must take milliseconds | Its files are meant to be generated (by CMake, Meson, GN), not written by hand. No functions or conditionals |
| just | A command runner (a justfile of named recipes) | Project commands with arguments, no TAB rule, clearer errors | Does not track file timestamps: every recipe runs every time. Has to be installed on every machine and CI image |
| Task | A runner configured in Taskfile.yml | Cross-platform single binary; can skip tasks whose sources haven't changed, comparing checksums | YAML gets verbose; another tool to install |
| npm scripts, cargo, Gradle, Bazel | Language-native build tools | Deep knowledge of their own ecosystem | Tied to one language |
My take: if your project's language already has a good build tool (cargo, Gradle, npm), let that tool build the code and use Make, if at all, as a thin layer of named commands on top. Make earns its place when outputs are files made from other files by shell commands, when the project spans several languages, or when it must work on a fresh Linux box with nothing extra installed.
Make's weak spots are real, and we'll meet each of them in this path. The TAB rule. Terse
error messages. $ meaning one thing to Make and another to the shell. Weak native Windows
support. Timestamp-only change detection. And no built-in knowledge of which headers a C
file includes. None of them are deal-breakers once you know them.
What this path covers
- Introduction (this article): what Make is and why it rebuilds what it rebuilds.
- Installing GNU Make: Linux, macOS, Windows, and an editor that keeps your TABs.
- Your First Makefile: rules, prerequisites, phony targets and dry runs, building a multi-file C program.
- Variables and How Make Expands Them:
=versus:=, overrides, and the conventionalCC/CFLAGSfamily. - Pattern Rules and Automatic Variables: one rule for
every
.cfile,$@and$<, build directories. - Built-in Functions: finding sources, transforming file lists, generating rules.
- Conditionals and Portable Makefiles
- Make as a Task Runner
- Multi-Directory Projects
- Parallel Builds, Dependency Generation, and Debugging
- Real-World Makefiles: complete Makefiles for C, Python, Docker and documentation projects.
Common mistakes
"missing separator"
The recipe line was indented with spaces. Make only recognises a recipe line by its leading
TAB, so it tried to read cat data.csv > report.txt as a rule or variable definition and
failed:
cat -A Makefile
makereport.txt: data.csv$
cat data.csv > report.txt$
Makefile:2: *** missing separator. Stop.With exactly eight spaces, GNU Make 4.3 guesses what happened:
Makefile:2: *** missing separator (did you mean TAB instead of 8 spaces?). Stop.The fix is to replace the leading spaces with a TAB, and to configure your editor so it stops inserting spaces in Makefiles. Installing GNU Make shows the Vim and VS Code settings.
"No rule to make target ..., needed by ..."
A prerequisite doesn't exist and no rule says how to create it. Here I added an east region
to the Makefile before creating its CSV:
make: *** No rule to make target 'data/east.csv', needed by 'build/east.txt'. Stop.Read it right to left: something needed data/east.csv, the file isn't there, and Make has no
recipe to produce it. Usually it's a typo in a filename, or a file that was never created or
committed.
"No targets specified and no makefile found"
make: *** No targets specified and no makefile found. Stop.You ran make in a directory without a Makefile, usually the wrong directory. GNU Make looks
for GNUmakefile, makefile and Makefile, in that order. A file named Makefile.txt or
MakeFile doesn't count. Use make -C path/to/project to run Make in another directory
without cd-ing, or make -f other.mk to read a differently named file.
A stale result with no error at all
The quietest mistake is the one from earlier: Make says "up to date", but an input it
wasn't told about has changed. If a result looks wrong after an edit, ask whether the file
you edited is listed as a prerequisite. make -B forces a full rebuild to confirm the
suspicion.
Summary
- Make brings files up to date using a dependency graph (targets and prerequisites), modification timestamps, and shell recipes.
- A target is rebuilt when it is missing or older than any prerequisite. Make keeps no state between runs; it reads the filesystem every time.
- Make compares timestamps, never file contents.
touchtriggers a rebuild, and an input that looks older than it is can hide a change.make -Bforces everything. - Make only knows the dependencies you write down. Scripts, configs and headers must be listed as prerequisites or edits to them won't trigger rebuilds.
- Recipe lines start with a TAB. Spaces give
missing separator. make --debug=bprints why each target was rebuilt, one "Prerequisite X is newer than target Y" line at a time.- GNU Make is the
makeon Linux. BSD make and POSIX make differ, CMake and Ninja generate and run C/C++ builds, and just and Task are command runners with nicer syntax and no TAB rule.
Exercises
Add an east region to the sales report: a data/east.csv file and a rule that builds
build/east.txt, with the report including it. Use this data:
date,sku,units,unit_price
2026-11-03,MS-220,6,19.50
2026-11-04,HD-310,3,89.99Run make twice and confirm the second run does nothing.
Hint
You need a new rule and a change to the report.txt rule: both its prerequisite list and
its cat command.
Show Solution
report.txt: build/north.txt build/south.txt build/east.txt
cat build/north.txt build/south.txt build/east.txt > report.txt
build/north.txt: data/north.csv summarize.sh
mkdir -p build
./summarize.sh data/north.csv > build/north.txt
build/south.txt: data/south.csv summarize.sh
mkdir -p build
./summarize.sh data/south.csv > build/south.txt
build/east.txt: data/east.csv summarize.sh
mkdir -p build
./summarize.sh data/east.csv > build/east.txtmake
cat report.txt
makemkdir -p build
./summarize.sh data/east.csv > build/east.txt
cat build/north.txt build/south.txt build/east.txt > report.txt
north 11 units 473.48 USD
south 15 units 480.99 USD
east 9 units 386.97 USD
make: 'report.txt' is up to date.Only the new summary and the report were built. North and south were already up to date.
If you edit the Makefile before creating the CSV, you get the
No rule to make target 'data/east.csv' error from Common mistakes.
With everything up to date, delete report.txt (but not the build/ directory) and run
make. Before you run it, predict exactly which commands will appear.
Show Solution
rm report.txt
makecat build/north.txt build/south.txt build/east.txt > report.txtJust the cat. The report is missing, so it must be rebuilt, but all three summaries still
exist and are newer than their CSVs and summarize.sh, so none of them are touched.
Run touch summarize.sh, then make -n. The -n flag ("dry run") prints the commands Make
would run without running them. Which commands are listed, and why all of them?
Show Solution
touch summarize.sh
make -nmkdir -p build
./summarize.sh data/north.csv > build/north.txt
mkdir -p build
./summarize.sh data/south.csv > build/south.txt
mkdir -p build
./summarize.sh data/east.csv > build/east.txt
cat build/north.txt build/south.txt build/east.txt > report.txtsummarize.sh is a prerequisite of all three summaries, so touching it makes all three out of
date, and the report depends on all three. Nothing was actually executed. Run plain make
afterwards to really rebuild. Dry runs are covered properly in
Your First Makefile.
touch data/south.csv, then run make --debug=b. Find the two lines that explain why
report.txt was rebuilt, and say which file's timestamp each line compares.
Show Solution
touch data/south.csv
make --debug=b[…]
Updating goal targets....
Prerequisite 'data/south.csv' is newer than target 'build/south.txt'.
Must remake target 'build/south.txt'.
mkdir -p build
./summarize.sh data/south.csv > build/south.txt
Successfully remade target file 'build/south.txt'.
Prerequisite 'build/south.txt' is newer than target 'report.txt'.
Must remake target 'report.txt'.
cat build/north.txt build/south.txt build/east.txt > report.txt
Successfully remade target file 'report.txt'.The first Prerequisite ... is newer line compares the touched CSV with its summary. The
second compares the freshly rebuilt build/south.txt with report.txt. The report wasn't
rebuilt because of the CSV directly, but because the summary it depends on had just been
regenerated. The indentation shows how deep in the graph each decision was made.
Tested with: GNU Make 4.3, GNU Bash 5.2.21 and Python 3.12.3 on Ubuntu 24.04 (WSL2),
November 2026. Every Makefile, command and output above was run as shown; the only trim is
the version banner at the top of --debug=b output. The BSD make examples used bmake
20200710 from Ubuntu's archive, unpacked into a local directory rather than installed. CMake,
Ninja, just and Task were not installed, so their rows in the comparison table come from
their official documentation, not from test runs.
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.