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.sh

data/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.99

summarize.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.txt

Run it twice in a row:

./build.sh
./build.sh
cat report.txt
summarizing 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.99

The 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:

  1. A dependency graph. Each rule names a target (a file to produce) and its prerequisites (the files it is made from).
  2. Timestamps. A target is out of date when it doesn't exist, or when any prerequisite has a newer modification time than the target.
  3. 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.txt

Read 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 Makefile
report.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:

make
mkdir -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

Make 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:

make
make: '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.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
south    15 units     480.99

The 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.csv

A 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.txt
2026-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.txt

Every 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=b
GNU 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, a git checkout that 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 -B rebuilds everything regardless of timestamps.

Deleting an output is also safe. Make notices the missing file and rebuilds just that part:

rm build/south.txt
make
mkdir -p build
./summarize.sh data/south.csv > build/south.txt
cat build/north.txt build/south.txt > report.txt

Make 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.99

The 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.txt
make
cat report.txt
mkdir -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 USD

Both 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 menuconfig and make -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 lint and make docker-build gives 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-quickstart generates a Makefile for you, so make html is how most Python projects build their docs.
  • Packaging. Linux distributions build thousands of packages with the same convention: make, then make 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
make
mkdir -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 test
python3 -m unittest -v
test_sums_per_customer (test_invoices.TotalsTest.test_sums_per_customer) ... ok
 
----------------------------------------------------------------------
Ran 1 test in 0.000s
 
OK

GNU 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 as gmake. 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
bmake
mkdir -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.mk
main.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:

ToolWhat it isWhere it winsWhat it costs
CMakeA generator: you describe a C/C++ project, it writes Makefiles, Ninja files or Visual Studio projectsCross-platform C/C++, Windows/MSVC support, finding librariesIts own language to learn; when a build fails you debug generated files
NinjaA small, very fast build executorHuge trees where a no-op rebuild must take millisecondsIts files are meant to be generated (by CMake, Meson, GN), not written by hand. No functions or conditionals
justA command runner (a justfile of named recipes)Project commands with arguments, no TAB rule, clearer errorsDoes not track file timestamps: every recipe runs every time. Has to be installed on every machine and CI image
TaskA runner configured in Taskfile.ymlCross-platform single binary; can skip tasks whose sources haven't changed, comparing checksumsYAML gets verbose; another tool to install
npm scripts, cargo, Gradle, BazelLanguage-native build toolsDeep knowledge of their own ecosystemTied 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

  1. Introduction (this article): what Make is and why it rebuilds what it rebuilds.
  2. Installing GNU Make: Linux, macOS, Windows, and an editor that keeps your TABs.
  3. Your First Makefile: rules, prerequisites, phony targets and dry runs, building a multi-file C program.
  4. Variables and How Make Expands Them: = versus :=, overrides, and the conventional CC/CFLAGS family.
  5. Pattern Rules and Automatic Variables: one rule for every .c file, $@ and $<, build directories.
  6. Built-in Functions: finding sources, transforming file lists, generating rules.
  7. Conditionals and Portable Makefiles
  8. Make as a Task Runner
  9. Multi-Directory Projects
  10. Parallel Builds, Dependency Generation, and Debugging
  11. 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
make
report.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. touch triggers a rebuild, and an input that looks older than it is can hide a change. make -B forces 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=b prints why each target was rebuilt, one "Prerequisite X is newer than target Y" line at a time.
  • GNU Make is the make on 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

Exercise 1: Add a third regioneasy

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.99

Run 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.txt
make
cat report.txt
make
mkdir -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.

Exercise 2: Delete the reporteasy

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
make
cat build/north.txt build/south.txt build/east.txt > report.txt

Just 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.

Exercise 3: Preview a rebuild with make -nmedium

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 -n
mkdir -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.txt

summarize.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.

Exercise 4: Make Make explain itselfmedium

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.

Was this page helpful?
The Dark Debugger

Written by The Dark Debugger

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