Skip to content
Velloreth
Developer Tools 6 min read

Make and Makefiles: A Practical Introduction

Make is a build tool that runs a command when a file is out of date. Learn the rules, the variables, and the patterns worth knowing.

By

What Make does

Make reads a file called Makefile, and it builds a target from its prerequisites. The key idea is the timestamp: if a prerequisite is newer than the target, the recipe runs; otherwise it is skipped.

app: main.o util.o
	cc -o app main.o util.o

main.o: main.c
	cc -c main.c

util.o: util.c
	cc -c util.c

The first rule is the default. Running make with no argument builds app.

Make is not only for compilation. The same mechanism runs a task when a file changes, and a .PHONY target turns it into a general task runner.

The anatomy of a rule

target: prerequisites
	recipe

The target is the file to build. The prerequisites are the files it depends on. The recipe is the command, indented with a tab.

The tab is not optional. A recipe line that starts with spaces produces missing separator. This is the single most common Makefile error.

A recipe line is passed to the shell, one line per shell invocation by default. A multi-line command needs a backslash continuation or a single line.

build:
	cd src && \
	npm run build

Variables

CC := cc
CFLAGS := -Wall -O2
SRC := $(wildcard src/*.c)
OBJ := $(SRC:.c=.o)

app: $(OBJ)
	$(CC) $(CFLAGS) -o $@ $^

:= is a simple assignment, expanded once. = is recursive, expanded each time it is used.

$(wildcard ...) expands a glob, which is how a source list is built without listing every file.

$(SRC:.c=.o) substitutes the suffix, turning a source list into an object list.

The automatic variables are the ones worth knowing:

VariableMeaning
$@the target
$^all prerequisites
$<the first prerequisite
$?the prerequisites newer than the target

Pattern rules

A pattern rule replaces a rule per file.

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

% matches a stem. The rule says: to build any .o, compile the matching .c. One rule replaces a rule per source file.

A static pattern rule restricts the pattern to a list.

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

Phony targets

.PHONY: all test lint clean

all: build

test:
	npm test

lint:
	npm run lint

clean:
	rm -rf dist node_modules

.PHONY declares that the target is not a file. Without it, a target named test is skipped if a file named test exists, because Make considers it up to date.

all is the conventional default, and it usually depends on the build targets.

A help target is a good default for a project that is used as a task runner.

.PHONY: help
help:
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
		| awk 'BEGIN {FS = ":.*?## "}; {printf "  %-15s %s\n", $$1, $$2}'

build: ## Build the project
	npm run build

test: ## Run the tests
	npm test

The @ suppresses the echo of the command, which keeps the output clean.

A task runner

A Makefile is a good task runner for a project, even when there is nothing to compile.

.PHONY: install dev test lint build deploy clean

install:
	npm ci

dev:
	npm run dev

test:
	npm test

lint:
	npm run lint

build:
	npm run build

deploy: build
	./scripts/deploy.sh

clean:
	rm -rf dist coverage

The advantage over a shell script is the dependency graph: make deploy runs build first, and make skips a step whose output is up to date.

The advantage over npm scripts is that it is not tied to Node, and it composes across languages.

Why a Makefile is worth learning

Make is older than most of the tools it competes with, and it is still installed on almost every Unix system. That ubiquity is the reason it is worth knowing: a Makefile works on a build server, in a container, and on a developer’s laptop without an install step. The second reason is the dependency graph, which a shell script does not have. A script runs every step in order, while Make runs only the steps whose inputs have changed, which turns a slow build into a fast one. The third reason is that a Makefile is a readable description of a project’s tasks, and a new developer can run make help to see them. The cost is the tab-sensitive syntax and the terse error messages, which is why a project that already has a task runner does not need to add one.

Make versus a task runner

A modern project has several options for a task runner, and the choice is a matter of the environment rather than of capability. A Makefile is the right choice when the project already has a C or C++ component, when the build server has make and nothing else, or when the tasks have a real dependency graph. A package.json script is the right choice for a Node project, because it needs no extra file and every Node developer already knows it. A dedicated runner such as Task or Just is the right choice when the team wants a modern syntax and is willing to install a tool. The practical advice is to use what the project already has, and to add a Makefile only when the dependency graph or the cross-language composition justifies it. A project with two task runners is a project where a new developer does not know which one to run.

Common mistakes

Spaces instead of a tab. The missing separator error. Configure the editor for a Makefile.

A target that is not phony. A file with the same name makes Make skip the recipe.

= where := is needed. A recursive variable that runs a shell command runs it every time it is expanded, which is slow and can produce a different value.

A recipe that changes directory without a continuation. Each line is a separate shell, so a cd on one line does not affect the next.

# Wrong: the cd does not persist
build:
	cd src
	npm run build

# Right: one shell
build:
	cd src && npm run build

A missing prerequisite. Make does not rebuild when a file it does not know about changes.

A clean that removes too much. A rm -rf with an unset variable is a disaster. Guard it.

clean:
	rm -rf $(BUILD_DIR)

Assuming a GNU extension is portable. $(wildcard) and $(shell) are GNU Make. A BSD make does not have them.

A quotable summary

A Makefile describes how to build a target from its prerequisites, and Make runs a recipe only when a prerequisite is newer than the target. A rule has a target, prerequisites and a recipe, and the recipe must be indented with a tab. Variables and pattern rules remove repetition, and .PHONY marks a target that is a task rather than a file. A Makefile is also a good task runner for a project, because it gives a dependency graph and it is not tied to one language.

For the shell in the recipes, see bash-scripting-basics and for the pipeline, ci-cd-pipeline-basics. For the broader context, linux-command-line-basics and package-json-explained.

Frequently asked questions

What is a Makefile used for?
A Makefile describes how to build files from other files. Make checks the timestamps, and it runs a recipe only when a prerequisite is newer than the target. It is used for compiling code, but it is also a general task runner for a project, with targets such as test, lint and deploy.
Why does my Makefile say 'missing separator'?
A recipe line must start with a tab, not spaces. This is the most common Makefile error. Check the indentation, and configure your editor to insert a real tab in a Makefile. A .editorconfig with indent_style = tab for Makefiles prevents it.
What does .PHONY mean?
It declares that a target is not a file. Without it, a target named test would be skipped if a file named test exists, because Make would consider it up to date. Marking it phony tells Make to run the recipe regardless.
What is the difference between = and := in a Makefile?
= is a recursive assignment: the value is expanded each time the variable is used. := is a simple assignment: the value is expanded once, at the point of assignment. Use := for a value that should be computed once, such as a shell command, and = for a value that should reflect a later change.
How do I run a target that is not the first one?
Pass the target name to make, as in make test. The first target in the file is the default, so a common convention is to put an all or help target first and list the others.
Can I use make on Windows?
Yes, with a port such as GNU Make from MSYS2, Chocolatey or a WSL environment. The recipes are shell commands, so a recipe that uses a Unix tool needs that tool available. A cross-platform project often uses a container or a task runner instead.