Linux › Section O · Development tools › Topic O.2

make

Once a program has more than a couple of source files, rebuilding it by hand becomes slow and error-prone. make reads a short description of what depends on what and runs only the commands needed to bring everything up to date.

Why make exists

In "The C compiler and linking", a two-file program was built with three commands, and after editing one file only part of the work had to be repeated. Real projects have hundreds of files, special compiler options and several programs to build. make, a Unix tool since the late 1970s, automates this. You describe the pieces in a file named Makefile (or makefile), type make, and it works out what is out of date. On Linux the implementation is GNU make, documented in its info manual (info make). GNU make has many extensions, so a Makefile that relies on them may fail with the make on a BSD system.

Targets, prerequisites and recipes

A Makefile is a list of rules. Each rule has a target (usually a file to build), a colon, its prerequisites (the files it is built from), and then a recipe: the shell commands that build it. Every recipe line must begin with a tab character, not spaces; otherwise GNU make stops with an error of the form Makefile:3: *** missing separator. Stop. The first ordinary target in the file is the default goal, built when you type plain make, so by convention it is called all. A target can also be a label rather than a file, such as clean.

Worked example: a first Makefile

Build the avg program from main.c and mean.c. Line 1 defines a variable: OBJS = main.o mean.o. Line 2 is the default rule: all: avg. Line 3 says how avg depends on its objects: avg: $(OBJS). Line 4, starting with a tab, is its recipe: $(CC) -o avg $(OBJS). Typing make then works backwards. 1. all needs avg. 2. avg needs main.o and mean.o, which do not exist. 3. No rule in the file builds them, so make uses a built-in rule and runs cc -c -o main.o main.c and then the same for mean.c (GNU make's output contains extra spaces where empty variables expand). 4. It links with cc -o avg main.o mean.o.

Built-in rules and timestamps

make already knows how to turn x.c into x.o: its built-in rule runs $(CC) with $(CPPFLAGS) and $(CFLAGS) and -c. It also knows how to build a program x straight from x.c, so in a directory holding only blah.c, make blah works with no Makefile at all. Deciding what to rebuild uses file modification times. A target is out of date if it is missing or older than any prerequisite. Run make twice and the second run builds nothing, reporting that there is nothing to be done for all. Change one file and make rebuilds only the targets downstream of it, and nothing else.

Worked example: a header change

In the avg Makefile, both .c files include mean.h, but no rule mentions it. 1. Edit mean.h, changing the function's argument type. 2. Run make. Neither object is older than its .c file, so make reports nothing to do, and the program is now built from stale objects. 3. Fix the Makefile with a rule that has no recipe: main.o mean.o: mean.h. This adds the header as a prerequisite of both objects. 4. Run make again: both objects are rebuilt and avg is relinked, a typical chain reaction. 5. Large projects generate such lines automatically with gcc -MMD -MP, which writes .d dependency files that the Makefile pulls in with -include.

Variables and automatic variables

Variables hold settings: CC (the C compiler, cc by default), CFLAGS (compiler options such as -O2 -g -Wall), CPPFLAGS (preprocessor options such as -I and -D), LDFLAGS (linker options such as -L) and LDLIBS (libraries such as -lm). Refer to one as $(NAME). Inside a recipe, automatic variables name parts of the current rule: $@ is the target, $< the first prerequisite, $^ all prerequisites and $* the stem a pattern matched. So a general rule for objects reads %.o: %.c, then a tab and $(CC) $(CPPFLAGS) $(CFLAGS) -c $< -o $@. Older Makefiles write the same idea as a suffix rule, .c.o:.

Running make from the command line

make mean.o builds just one target. Variables can be overridden for one run: make CC=clang uses clang, and make CFLAGS='-O0 -g' builds a debugging version. Several options are worth memorising. -n prints the commands without running them, a dry run. -f file reads a different Makefile. -j 4 runs up to four recipes in parallel, which can greatly shorten builds on multi-core machines. -C dir changes into dir first. -B rebuilds everything regardless of timestamps, and -k keeps going past errors to show as many problems as possible in one run.

Conventional targets

Most projects provide the same handful of labels. all builds everything. clean deletes built files, for example with a recipe of rm -f $(OBJS) avg. distclean, in autotools projects, also removes files generated by configuration, returning the tree to its distributed state. install copies programs and files into the system, so always preview it with make -n install first. check or test runs the project's test suite. Declare such labels with .PHONY: all clean install, so make never confuses them with a real file of the same name: without it, a stray file called clean would stop make clean from ever running.

Organising a larger Makefile

Good Makefiles put settings at the top and rules below. Group library options by package, such as GEO_CFLAGS = -I/opt/geo/include and GEO_LIBS = -L/opt/geo/lib -lgeo, then add them to the general variables with +=, as in CFLAGS += $(GEO_CFLAGS). Writing CFLAGS = $(CFLAGS) ... instead is an error in GNU make, because a variable defined with = is expanded each time it is used and so would refer to itself forever; GNU make detects this and stops. Give each program its own object list and its own rule, so changing one program's source does not rebuild the others, and put shared objects in a list used by both.

Common mistakes to avoid

Indenting recipe lines with spaces, which causes missing separator. Leaving header files out of the prerequisites, so changes to them are silently ignored. Writing CFLAGS = $(CFLAGS) ... instead of +=. Forgetting .PHONY on clean and install. Running make install as root without checking make -n install first: it may overwrite files anywhere in the system. Combining two programs in one rule, so each appears to depend on the other's source. Expecting a Makefile full of GNU extensions to work with every make; test it with the target system's make.

Key takeaways

A Makefile is a list of rules: target, colon, prerequisites, then tab-indented recipe lines. make rebuilds a target only when it is missing or older than a prerequisite, using built-in rules for common steps such as .c to .o. List headers as prerequisites or generate them with gcc -MMD -MP. Use CC, CFLAGS, CPPFLAGS, LDFLAGS and LDLIBS, plus $@, $< and $^ in recipes. Override variables on the command line and use -n, -f, -j, -C, -B and -k. Provide all, clean, install and check, declared .PHONY.

Flashcards

Flashcard

Makefile

File of rules that tells make how to build targets

Also accepted: makefile.

Test your understanding

Question 1 of 5

make stops with Makefile:4: *** missing separator. Stop. What is the most likely cause?

Question 2 of 5

After editing only mean.c in the avg project, what does make rebuild?

Question 3 of 5

In a recipe for the rule prog: a.o b.o, what does $^ expand to?

Question 4 of 5

Why should you run make -n install before make install?

Question 5 of 5

A project directory contains a file named clean, and make clean now says the target is up to date. What fixes this?

← Previous topicNext topic →