← all letters
letter to myself

Make tutorial

Hey Nic. Looking to make some stuff, are we?

nicholas van huyssteen · 16 oct 2026 · 24 min read

A brief word on the history of Make#

This first section doesn’t contain any actionable information. I include it because I think it is important to pay respects to the people who gave us this technology. With that being said, feel free to skip to the next section.

Make was written by Stuart Feldman at Bell Labs in April 1976, on Unix. It first shipped with PWB/UNIX (the Programmer’s Workbench variant) and then went out more widely with Version 7 Unix in 1979.

The reason it exists is fairly mundane. A colleague of Feldman’s, Steve Johnson (the author of yacc and lint), lost a morning debugging a program that was actually correct. The problem was that a file had been changed and its object file was never recompiled, so he was running stale code. Back then people built programs with ad hoc shell scripts, or just retyped the commands, and this kind of mistake was common. Feldman’s idea was to describe the dependencies between files and let a tool compare modification timestamps to decide what needed rebuilding. That core model (targets, prerequisites, recipes, timestamps) is still how Make works today.

Basics#

Like much of the most useful, widely adopted software, Make is simple. In fact, a valid explanation of Make could look like this: It creates an output if a certain set of prerequisites is met. This description is true, but not very useful. Let’s expand the explanation a bit. At its core it does three things:

  1. It checks for prerequisites that you give it.
  2. It compares file modification timestamps.
  3. It runs shell commands that you give it.

It works like this: You create a Makefile, consisting of rules. A rule is the basic unit of a Makefile. It looks something like this:

target: prerequisites
	recipe
  • target: the file this rule produces
  • prerequisites: the files it depends on
  • recipe: the shell commands that produce it. The recipe line must start with a TAB. If you get a missing separator error, this is why.

I think it’s time for an example. Most people use Make for building C programs. This is its intended use case, but nothing in its design ties it to C. Apart from a few built-in conveniences we’ll get to later, Make doesn’t know what C is or what a compiler is. It knows “file X depends on files Y and Z, and here’s a command that produces X.”

Create a Makefile. Inside the Makefile, write the following:

a_directory:
	mkdir a_directory

By default, Make starts with the first (top) rule in the Makefile. We only have one rule, so that’s the one it runs. This rule shows that there is some output called a_directory, which is created by the shell command mkdir a_directory and has no prerequisites. In the shell, in the same directory as the Makefile, run:

make

It should print

mkdir a_directory

and you should see a new directory called a_directory. Make will echo the recipe being executed. If you want to mute the echo, add an @ in front of the recipe, like so:

a_directory:
	@mkdir a_directory

Let’s see an example with prerequisites:

a_directory/another_directory: a_directory
	mkdir a_directory/another_directory

a_directory:
	mkdir a_directory

From the Makefile’s directory, run the command rm -r a_directory so that we’re working with a fresh environment. We’ll write a rule for this later. Then run make again. You should see the following output:

mkdir a_directory
mkdir a_directory/another_directory

and observe that the directory structure a_directory/another_directory has been created.

What happens here is that Make checks the first rule, but finds that a_directory is missing, so it runs the rule that produces it first. Afterwards it goes back to the original rule and executes it now that its prerequisite has been satisfied.

In a more technical sense, Make creates a rule dependency graph and traverses it depth-first. We’ll explore the concept with a better example later in this tutorial.

The C example#

Now let’s see Make in its natural habitat: a C project.

Suppose that you are a C programmer, and you’ve just finished writing up an implementation of a linked list. You’ve got a project directory that looks like this:

project/
├── src/
│   ├── main.c
│   └── datastructures/
│       ├── list.c
│       └── list.h
└── Makefile

main.c is the entry point into your program, and it uses the types and functions declared in list.h and implemented in list.c. In order to build the program you would typically run a command like the one below from the root of your project:

cc src/main.c src/datastructures/list.c -o app

This produces the binary app, which you can then execute to run your program.

We can wrap this in a Makefile:

app: src/main.c src/datastructures/list.c src/datastructures/list.h
	cc src/main.c src/datastructures/list.c -o app

Why would we do this? Firstly, it stops execution if any of the prerequisites aren’t met. Secondly, and more importantly, it checks the timestamps of the files to see if app is newer than its prerequisites. You can check for yourself: run make. You should see the following output:

cc src/main.c src/datastructures/list.c -o app

Run it again and you should see make: 'app' is up to date. (or make: `app' is up to date. on the older Make that macOS ships).

Now let’s bump the timestamp on list.h by running

touch src/datastructures/list.h

and run make again. You’ll see that the recipe is executed once again.

There’s a problem with the recipe above. If we change main.c, then list.c recompiles too. In a big project this wastes a lot of time.

Simplifying a little, C compilation has two stages:

  • Compile: Uses the .c files to create .o files. These are called object files, and they contain machine code with unresolved references to symbols defined in other files.
  • Link: Combines all the object files into one executable.

It is better practice to describe each stage as its own rule:

app: main.o list.o
	cc main.o list.o -o app

main.o: src/main.c src/datastructures/list.h
	cc -c src/main.c -o main.o

list.o: src/datastructures/list.c src/datastructures/list.h
	cc -c src/datastructures/list.c -o list.o

Remember the dependency graph I mentioned earlier? Well, here’s the one that running make for the above would produce:

app
├── main.o
│   ├── main.c
│   └── list.h
└── list.o
    ├── list.c
    └── list.h

Make starts at app and works depth-first: it goes all the way down the main.o branch, then the list.o branch, and only then comes back up to build app itself. You can see this in the order a fresh build runs the commands:

cc -c src/main.c -o main.o
cc -c src/datastructures/list.c -o list.o
cc main.o list.o -o app

Let’s check that this solves our problem. With everything built, pretend you’ve edited main.c:

touch src/main.c
make
cc -c src/main.c -o main.o
cc main.o list.o -o app

Only main.o is rebuilt, then relinked into app. list.c isn’t touched. Now try touch src/datastructures/list.h and run make again: both object files rebuild, because both depend on list.h. That’s the dependency graph in action. Make walks it, and only rebuilds the branches with something newer underneath.

Running Make#

Choosing a target#

So far we’ve only run plain make, which builds the first target in the Makefile. You can also tell Make which target you want. Everything is already built at this point, so delete list.o first:

rm list.o
make list.o
cc -c src/datastructures/list.c -o list.o

Make builds that target, plus anything it needs, and nothing else. app and main.o are left alone.

Cleaning up#

Remember running rm -r a_directory by hand to get a fresh environment? A C project needs the same thing: deleting app and the object files so you can build from scratch. Instead of typing that out every time, we can give it a rule:

app: main.o list.o
	cc main.o list.o -o app

main.o: src/main.c src/datastructures/list.h
	cc -c src/main.c -o main.o

list.o: src/datastructures/list.c src/datastructures/list.h
	cc -c src/datastructures/list.c -o list.o

clean:
	rm -f app main.o list.o

Run it with make clean. It goes at the bottom so that plain make still builds app.

clean is an odd rule. It has no prerequisites, and its recipe never creates a file called clean. Because that file never exists, Make treats clean as out of date every time, so the recipe always runs.

That works until a file called clean shows up:

touch clean
make clean
make: 'clean' is up to date.

Make found a file named clean, saw that it has no prerequisites newer than it, and decided there was nothing to do. To stop this, tell Make that clean isn’t a file:

.PHONY: clean
clean:
	rm -f app main.o list.o

A target listed under .PHONY always has its recipe run, whatever files exist.

Recipes and the shell#

Each line of a recipe runs in its own shell. Add this rule to the bottom of your Makefile:

where:
	cd src
	pwd

and run make where. pwd prints the project directory, not src. The cd happened in a shell that exited as soon as its line finished.

If commands depend on each other, put them on one line:

where:
	cd src && pwd

or split one long line with a backslash:

where:
	cd src && \
	pwd

Now pwd prints the src directory. You can delete the where rule again.

When a command fails#

Make stops as soon as a command fails. To see this, break main.c by adding a line of nonsense to the end, then start from a clean slate so that list.o doesn’t exist yet:

echo oops >> src/main.c
make clean
make
cc -c src/main.c -o main.o
...
make: *** [Makefile:5: main.o] Error 1

The ... stands in for your compiler’s error message, which will vary. Make never even tried list.o. That’s usually what you want: there’s no point linking app if one of its pieces failed.

But sometimes you want to see every error at once. make -k (keep going) builds everything it can that doesn’t depend on the failure:

make -k
cc -c src/main.c -o main.o
...
make: *** [Makefile:5: main.o] Error 1
cc -c src/datastructures/list.c -o list.o
make: Target 'app' not remade because of errors.

list.o is on a different branch of the dependency graph from main.o, so Make builds it anyway. app depends on both, so it’s skipped.

Remove the oops line from main.c before moving on.

Finally, if you don’t care whether a particular command fails, put a - in front of it:

clean:
	-rm app main.o list.o

Make reports the failure as (ignored) and carries on. In our clean rule, rm -f already ignores missing files, so we don’t need it there.

Variables#

Let’s continue with our C example to discuss variables. So far we’ve been using cc, which on most machines points at whatever the default C compiler is. But you might want a specific one: gcc, clang, tcc, or whatever else your machine has.

Instead of replacing every instance of cc in the Makefile to change the compiler used, we can assign a variable and reference it in our rules:

CC = cc

app: main.o list.o
	$(CC) main.o list.o -o app

main.o: src/main.c src/datastructures/list.h
	$(CC) -c src/main.c -o main.o

list.o: src/datastructures/list.c src/datastructures/list.h
	$(CC) -c src/datastructures/list.c -o list.o

.PHONY: clean
clean:
	rm -f app main.o list.o

Variables are plain text substitution. $(CC) gets replaced with its text before the shell sees the command.

It is also uncommon to use a compiler in such a bare-bones way, without any flags. Most developers compile their projects with warnings and debugging information enabled, so they’ll likely add the following flags: -Wall -Wextra -g. Let’s add these to the Makefile, but save ourselves the effort of adding them everywhere:

CC     = cc
CFLAGS = -Wall -Wextra -g

app: main.o list.o
	$(CC) main.o list.o -o app

main.o: src/main.c src/datastructures/list.h
	$(CC) $(CFLAGS) -c src/main.c -o main.o

list.o: src/datastructures/list.c src/datastructures/list.h
	$(CC) $(CFLAGS) -c src/datastructures/list.c -o list.o

.PHONY: clean
clean:
	rm -f app main.o list.o

The names of these variables aren’t arbitrary, but more on that later. You can also override variables from the command line.

make CFLAGS="-O2"          # sets CFLAGS to "-O2" and runs make
make CC=gcc                # sets the compiler to gcc and runs make

This allows anyone to switch compilers without touching the Makefile.

Keep in mind that an override replaces the value entirely, so make CFLAGS="-O2" drops -Wall -Wextra -g.

One catch: if everything is already built, make CFLAGS="-O2" does nothing. Make only compares timestamps, and none of your files changed, so it doesn’t notice that the flags did. Use make -B CFLAGS="-O2" to rebuild everything.

Ultimately, variables save us work by allowing us to make one change instead of many.

There are two types of variable assignment that you’re most likely to use:

Syntax Name When the right side is evaluated
= recursively expanded Every time the variable is used (lazy)
:= simply expanded Once, at the moment of assignment

The examples below demonstrate the difference between the two:

A = $(B)
B = hello
# $(A) holds "hello"  (B is looked up when A is used)
C := $(D)
D = hello
# $(C) holds ""  (D was empty when C was assigned)

Automatic variables#

Make also provides shorthand in the form of automatic variables:

Variable Means
$@ The target
$< The first prerequisite
$^ All prerequisites (duplicates removed)

So we might write:

CC     = cc
CFLAGS = -Wall -Wextra -g

app: main.o list.o
	$(CC) $^ -o $@

main.o: src/main.c src/datastructures/list.h
	$(CC) $(CFLAGS) -c $< -o $@

list.o: src/datastructures/list.c src/datastructures/list.h
	$(CC) $(CFLAGS) -c $< -o $@

.PHONY: clean
clean:
	rm -f app main.o list.o

Much quicker to write and equally readable once you get used to it.

Pattern rules#

Let’s suppose that in addition to your linked list implementation, you wrote an implementation of a hash map and main.c now also depends on map.c and map.h:

project/
├── src/
│   ├── main.c
│   └── datastructures/
│       ├── list.c
│       ├── list.h
│       ├── map.c
│       └── map.h
└── Makefile

You update your Makefile:

CC     = cc
CFLAGS = -Wall -Wextra -g

app: main.o list.o map.o
	$(CC) $^ -o $@

main.o: src/main.c src/datastructures/list.h src/datastructures/map.h
	$(CC) $(CFLAGS) -c $< -o $@

list.o: src/datastructures/list.c src/datastructures/list.h
	$(CC) $(CFLAGS) -c $< -o $@

map.o: src/datastructures/map.c src/datastructures/map.h
	$(CC) $(CFLAGS) -c $< -o $@

.PHONY: clean
clean:
	rm -f app main.o list.o map.o

Notice how all the .o rules have the exact same recipes? Furthermore, list.o and map.o are identical apart from the names. We can take advantage of this to condense the file even more by employing a pattern rule. Take a look at this:

CC     = cc
CFLAGS = -Wall -Wextra -g

app: main.o list.o map.o
	$(CC) $^ -o $@

main.o: src/main.c src/datastructures/list.h src/datastructures/map.h
	$(CC) $(CFLAGS) -c $< -o $@

%.o: src/datastructures/%.c src/datastructures/%.h
	$(CC) $(CFLAGS) -c $< -o $@

.PHONY: clean
clean:
	rm -f app main.o list.o map.o

Let’s walk through what Make does with this file. It starts at the first rule, app, which needs main.o, list.o and map.o. For each of those, Make goes looking for a rule that produces it.

main.o is easy: there’s a rule with exactly that name. A rule that names its target outright like this is called an explicit rule.

list.o has no rule of its own, so Make tries the pattern rule. In a pattern rule, % stands for any non-empty piece of text. The target %.o matches list.o, with % standing for list. That matched piece is called the stem.

Make takes the stem and puts it in place of every % in the prerequisites as well. So for list.o and map.o, the pattern fills in like this:

Target Stem Prerequisites
list.o list src/datastructures/list.c src/datastructures/list.h
map.o map src/datastructures/map.c src/datastructures/map.h

This is also why the recipe uses $< and $@ instead of file names. A pattern rule doesn’t know the names until Make fills them in.

Two things worth knowing:

  • %.o matches main.o too, but explicit rules always beat pattern rules, so main.o still uses its own rule. That’s lucky, because the pattern would have looked for src/datastructures/main.c, which doesn’t exist.
  • A pattern rule only applies if its prerequisites exist, or if Make can build them. Add vector.o to app without writing src/datastructures/vector.c, and Make won’t use the pattern. It stops with No rule to make target 'vector.o', needed by 'app'.

Built-in rules#

So far we’ve been assuming a neat directory structure. For my next example let’s instead assume that our program files and Makefile are all in the same directory:

project/
├── main.c
├── list.c
├── list.h
├── map.c
├── map.h
└── Makefile

Then Makefile can look like this:

CC     = cc
CFLAGS = -Wall -Wextra -g

app: main.o list.o map.o
	$(CC) $^ -o $@

%.o: %.c %.h
	$(CC) $(CFLAGS) -c $< -o $@

.PHONY: clean
clean:
	rm -f app main.o list.o map.o

Delete the pattern rule so that it looks like

CC     = cc
CFLAGS = -Wall -Wextra -g

app: main.o list.o map.o
	$(CC) $^ -o $@

.PHONY: clean
clean:
	rm -f app main.o list.o map.o

It still works! How?

GNU Make has built-in implicit rules, including one that’s essentially:

%.o: %.c
	$(CC) $(CFLAGS) $(CPPFLAGS) -c -o $@ $<

That’s why the variables are named CC and CFLAGS: they’re conventions that the built-in rules use. You can see every built-in rule and variable with make -p -f /dev/null. The -f /dev/null gives Make an empty Makefile to read, so it prints the built-ins without also running your build. It’s a lot so you might want to pipe it into less.

Notice how we have now removed header files from our prerequisites? We’ll explore the consequences of that in the next section.

A classic trap: header dependencies#

Strictly speaking, we don’t have to list header files as prerequisites, because the recipe never mentions them. The build in the previous section worked fine without them.

The problem shows up when you change a header. With everything built, try:

touch list.h
make
make: 'app' is up to date.

Make has no idea that main.o and list.o were built from list.h, so it doesn’t rebuild them. That might sound harmless, but imagine you’d added a field to a struct in list.h. main.o and list.o would still be using the old layout of that struct, and your program would read and write memory in the wrong places. That’s a very confusing bug, because the code you’re looking at is correct. This is exactly the bug that sent Steve Johnson storming into Feldman’s office in 1976.

We could go back to listing headers by hand, but that doesn’t scale. Every time you add or remove an #include, you’d have to remember to update the Makefile to match. Even our old %.o: %.c %.h rule only covered each file’s own header, so it would never have noticed that main.c includes list.h and map.h.

Fortunately, the compiler already knows which headers each file includes. It read them, after all. We can ask it to write that down for us by adding two flags to CFLAGS:

CFLAGS = -Wall -Wextra -g -MMD -MP
  • -MMD: while compiling list.c, also write list.d, which contains a Make rule listing every non-system header it included.
  • -MP: adds an empty rule for each header, so deleting a header doesn’t break the build.

Run make clean and then make. Remember that changing CFLAGS doesn’t trigger a rebuild on its own, which is why we clean first. Afterwards you’ll find a .d file next to each object file. Here’s main.d:

main.o: main.c list.h map.h
list.h:
map.h:

It’s just a Make rule, written by the compiler! The first line is exactly the rule we would otherwise have had to write and maintain by hand. The other two are the empty rules from -MP.

Including other files#

Make doesn’t read .d files on its own. We have to tell it to, with include:

include main.d

When Make reaches that line, it reads main.d as if its contents had been pasted into the Makefile right there. Rules, variables, anything. It isn’t only for generated files, either. It’s also how big projects split one huge Makefile into several smaller ones, or share settings between them.

We want every .d file, and Make expands wildcards in include, so we can write:

include *.d

There’s one catch. The .d files are created by compiling, so on a fresh build they don’t exist yet, and Make stops with *.d: No such file or directory. Remember the - prefix from earlier, which tells Make to ignore a failing command? It works on include too:

-include *.d

Now Make skips any files that are missing. That’s safe, because on the first build every object file is missing, so everything gets compiled anyway. Make doesn’t need to know about the headers until there’s something to be out of date.

Here’s the full Makefile:

CC     = cc
CFLAGS = -Wall -Wextra -g -MMD -MP

app: main.o list.o map.o
	$(CC) $^ -o $@

.PHONY: clean
clean:
	rm -f app *.o *.d

-include *.d

Two other things changed. clean now deletes the .d files as well. The shell expands each *, so *.o and *.d catch every object and dependency file without us naming them one by one.

The -include also goes at the bottom, and that matters. The .d files are full of rules, so if they were included at the top, the first of them (list.o, from list.d) would become the default goal. Plain make would build list.o and stop.

Now try the experiment again:

touch list.h
make
cc -Wall -Wextra -g -MMD -MP   -c -o main.o main.c
cc -Wall -Wextra -g -MMD -MP   -c -o list.o list.c
cc main.o list.o map.o -o app

Both object files that include list.h are rebuilt, and map.o is left alone, without a single header listed by hand. Every build, Make reads the .d files before it decides what’s out of date, and every compile keeps them up to date. In other words, the compiler is now writing part of the Makefile for us.

Debugging and parallelism#

As a Makefile grows, you’ll eventually find yourself asking “why did that rebuild?” or, worse, “why didn’t that rebuild?”. Make has a few flags that help answer those questions.

Dry runs#

make -n prints the commands Make would run, without running any of them:

touch list.h
make -n
cc -Wall -Wextra -g -MMD -MP   -c -o main.o main.c
cc -Wall -Wextra -g -MMD -MP   -c -o list.o list.c
cc main.o list.o map.o -o app

Run make -n again and you’ll get the same output, because nothing was actually built. It’s a good habit to do a dry run after changing a Makefile, especially before trying out a new rule that deletes things, like clean.

Asking Make why#

make -n shows you what Make is going to do, but not why. For that, use --debug=b (b for basic):

make --debug=b
GNU Make 4.4.1
...
Updating goal targets....
  Prerequisite 'list.h' is newer than target 'main.o'.
 Must remake target 'main.o'.
cc -Wall -Wextra -g -MMD -MP   -c -o main.o main.c
 Successfully remade target file 'main.o'.
  Prerequisite 'list.h' is newer than target 'list.o'.
 Must remake target 'list.o'.
cc -Wall -Wextra -g -MMD -MP   -c -o list.o list.c
 Successfully remade target file 'list.o'.
 Prerequisite 'main.o' is newer than target 'app'.
 Prerequisite 'list.o' is newer than target 'app'.
Must remake target 'app'.
cc main.o list.o map.o -o app
Successfully remade target file 'app'.

This is the timestamp comparison from the very beginning of this letter, made visible. The indentation even follows the dependency graph: the further down the graph a target is, the further its lines are indented.

Unlike -n, this runs the build for real. Combine the two, make -n --debug=b, to get the reasoning without the side effects.

If something isn’t rebuilding when you expect it to, look for the prerequisite you changed in this output. If it’s not there, Make doesn’t know the target depends on it, which is exactly the header trap from the previous section.

Printing the database#

We’ve already met make -p in the section on built-in rules. Run it in your project instead of with -f /dev/null, and it prints everything Make knows after reading your Makefile: your rules, the built-in rules, the rules included from the .d files, and the final value of every variable. That’s handy when a variable doesn’t hold what you think it does.

Like --debug=b, it also runs the build. Add -q (question mode), which tells Make to check whether things are up to date without running anything:

make -pq | less

Parallel builds#

By default, Make runs one command at a time. But look at our dependency graph: main.o, list.o and map.o don’t depend on each other, so there’s no reason for one to wait for another. The -j (jobs) flag tells Make how many commands it may run at once:

make clean
make -j4

The output looks the same as before, though the three compile lines may come out in a different order from run to run, because they really are running at the same time. app is always last, because it needs all three.

A sensible number is the number of CPU cores you have (nproc on Linux, sysctl -n hw.ncpu on macOS). -j without a number means no limit, which on a big project can start hundreds of compilers at once.

-j is only safe because we described the dependency graph correctly. Make runs two targets at the same time whenever the graph says neither depends on the other. If the graph is missing a dependency, Make will happily run things in the wrong order.

Remember our very first example with prerequisites? In an empty directory, create a Makefile with a version that leaves out the prerequisite and relies on the order of the targets instead:

all: a_directory a_directory/another_directory

a_directory/another_directory:
	mkdir a_directory/another_directory

a_directory:
	sleep 1
	mkdir a_directory

all is a common name for a first rule whose only job is to list everything that should be built. The sleep 1 pretends that creating a_directory is slow.

Without -j, Make builds prerequisites from left to right, so a_directory is created first and everything works. Now delete a_directory and run make -j2:

sleep 1
mkdir a_directory/another_directory
...
make: *** [Makefile:4: a_directory/another_directory] Error 1
make: *** Waiting for unfinished jobs....
mkdir a_directory

Both rules started at once, and another_directory lost the race. Waiting for unfinished jobs is Make letting the commands that were already running finish before it stops.

Without the sleep, this would fail only some of the time, depending on which mkdir happened to run first. That’s what makes missing dependencies so nasty in parallel builds: the build passes, then fails, then passes again, with nothing changed. If a build works without -j but fails with it, look for a missing prerequisite.