← Full reference

make

Running commands by rules from a Makefile — targets, prerequisites, variables, rebuilding only what's out of date

make reads a Makefile and runs its rules: how to produce a target from its prerequisites. A target is rebuilt only if it doesn't exist or some prerequisite is newer than it (file modification times are compared). That makes make suitable both for builds and as a short menu of project commands.

Syntax

make [options] [target…] [VARIABLE=value…]

Without a target, the first target in the file runs (or the one set in .DEFAULT_GOAL). The file is looked up under the names GNUmakefile, makefile, Makefile.

A rule in a Makefile:

target: prerequisite1 prerequisite2
	command        # a recipe line starts with a TAB character
	another_command

Options

OptionWhat it does
-nshow the commands without running anything (dry run)
-f fileuse another file instead of Makefile
-C directorychange to the directory before running
-sdon't print the commands
-Brebuild everything regardless of file times
-j 4run up to 4 recipes in parallel
-kon an error, keep going with other targets that don't depend on it
-iignore errors in all recipes
-qdo nothing, only the exit code: 0 — the target is up to date, 1 — it isn't
-eenvironment variables override assignments in the Makefile
-pprint all rules and variables (including built-in ones)
--debug=bexplain why a target is being rebuilt

Rules and targets

ElementMeaning
target: prerequisitesthe rule header; the TAB lines below it are the recipe
a b: prerequisitesone rule for several targets
%.html: %.mda pattern rule: any .html from the .md of the same name
target: normal | order-onlyprerequisites after | must exist, but their time isn't checked (handy for directories)
.PHONY: name…targets that aren't files (clean, test, build)
.DEFAULT_GOAL := namethe default target instead of the first one in the file
.ONESHELL:run the whole recipe in one shell rather than line by line
include file.mkinsert another Makefile

Recipe line prefixes

PrefixWhat it does
@commanddon't print the command itself before running it
-commandcontinue even if the command fails
\ at the end of a linecontinue the command on the next line (one shell)

Automatic variables

VariableValue
$@the current target's name
$<the first prerequisite
$^all prerequisites separated by spaces, without duplicates
$+all prerequisites with duplicates, in the original order
$?prerequisites newer than the target
$*the "stem" of the name in a pattern rule (what matched %)
$(@D) / $(@F)the target's directory / file name
$$a $ sign for the shell ($$HOME, $$f in a loop)

Variables

NotationWhat it does
VAR = valuethe value is expanded on every use
VAR := valueevaluated immediately, at assignment time
VAR ?= valueset only if the variable isn't set yet (e.g. from the environment)
VAR += moreappend to the value with a space
$(VAR) or ${VAR}substitute the value
export VARpass the variable into the environment of recipe commands
make VAR=xa value from the command line beats any assignment in the file

Environment variables are visible too, as $(HOME), but an assignment in the Makefile overrides them.

Functions

FunctionWhat it returns
$(wildcard src/*.c)files matching a pattern
$(patsubst %.c,%.o,$(SRC))pattern substitution in each word
$(SRC:.c=.o)a short form of the same suffix substitution
$(subst from,to,text)a simple substring replacement
$(notdir path) / $(dir path)file name / directory
$(basename file) / $(suffix file)without the extension / the extension only
$(addprefix p/,a b) / $(addsuffix .txt,a b)prepend a prefix / append a suffix to each word
$(filter %.c,list) / $(filter-out …)keep / remove matching words
$(foreach x,list,text)repeat the text for each element
$(shell command)the output of a shell command
$(if cond,then,else)a condition inside an expression
$(error text) / $(warning text)stop with an error / print a warning

Conditionals

ifeq ($(MODE),prod)
FLAGS = -O2
else
FLAGS = -g
endif

ifdef DEBUG
FLAGS += -DDEBUG
endif

There are also ifneq and ifndef. Conditionals are evaluated when the file is read, before any recipes run.

Examples

A small Makefile that concatenates two files:

OUT = combined.txt

.PHONY: build clean

build: $(OUT)

$(OUT): part1.txt part2.txt
	cat $^ > $@

clean:
	rm -f $(OUT)
# what would run, without running it
make -n

# build the default target (the first one — build)
make

# running again does nothing: the target is newer than its prerequisites
make

# after a prerequisite changes, the target is rebuilt
touch part2.txt && make

# a specific target and overriding a variable
make clean
make OUT=all.txt

# run a Makefile from another directory
make -C /path/to/project build

# is the target up to date — for scripts
make -q build && echo 'everything is built'

A pattern rule, an order-only prerequisite and a loop in a recipe:

SRC := $(wildcard src/*.md)
OUT := $(patsubst src/%.md,out/%.html,$(SRC))

.PHONY: all list

all: $(OUT)

out/%.html: src/%.md | out
	cp $< $@

out:
	mkdir -p $@

list:
	@for f in $(SRC); do \
	  echo "source: $$f"; \
	done

Pitfalls

  • missing separator. Stop. — a recipe line starts with spaces instead of a TAB. Check with cat -A Makefile: a TAB shows up as ^I.
  • Each recipe line runs in a separate shell. cd dir on one line doesn't affect the next. Write cd dir && command on one line, continue the line with \, or enable .ONESHELL:.
  • A target without .PHONY matches a file or directory. If there's a file test or a directory docs next to it, make test replies 'test' is up to date and does nothing.
  • $ in a recipe belongs to make. A shell variable is written $$VAR; make reads $VAR as $(V)AR — you get an empty value followed by AR.
  • A failing command stops make with a non-zero code, and the following recipe lines don't run. The - prefix suppresses the error, but don't overuse it.
  • make -n also prints @ commands — that way you see what's hidden.
  • = and := behave differently. A = $(B) takes the value of B at the time of use, A := $(B) — at the time of assignment. $(shell …) with = runs on every reference.
  • Rebuilding relies on modification time. If a file was copied with its old date preserved, make may decide the target is up to date. make -B helps then.
  • Without -j recipes run one after another; with -j the order isn't guaranteed, so all prerequisites must be declared explicitly.

See also

git · variables · exit-codes · redirection