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 Velloreth
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:
| Variable | Meaning |
|---|---|
$@ | 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.
Related reading
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.