The Command Script

The command script for a rule can consist of several lines, each of which must begin with a tab. Comments and blank lines are ignored, so that the command script ends with the next target line or variable definition.

Furthermore, the first line of the command script may be placed after a semicolon at the end of the dependency line, as in the following syntax:

target_list : [prerequisite_list] ; [command
        [command
        [...]]]

This variant is rarely used today, however.

The important thing to remember about the command part of a make rule is that it is not a shell script. When make invokes a rule to build its target, each line in the rule’s command section is executed individually in a separate shell instance. For that reason, you must make sure that no command depends on the side effects of a preceding line. For example, the following commands will not run etags in the src/ subdirectory:

TAGS:
        cd src/
        etags *.c

In trying to build TAGS, make runs the shell command cd src/ in the current directory. When that command exits, make runs etags *.c in a new shell, again in the current directory.

There are two ways to cause several commands to run in the same shell: putting them on one line, separated by a semicolon, or adding a semicolon and a backslash to place them virtually on one line:

TAGS:
	    cd src/ ; etags *.c ;\
	    cd .. ; ls src/TAGS

Another reason for running multiple commands in the same shell could be to speed up processing, especially in large projects.

Pattern Rules

The last two rules in Example 20-1 show a repetitive pattern. Each of the two object files, circle.o and circulararea.o, depends on a source file with the same name and the suffix .c, and the commands to build them are the same. make lets you describe such cases economically using pattern rules. Here is a single rule that replaces the last two rules in Example 20-1:

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

The first line of this rule has three colon-separated parts rather than two. The first part is a list of the targets that the rule applies to. The rest of the line, %.o: %.c, is a pattern explaining how to derive a prerequisite name from each of the targets, using the percent sign (%) as a wildcard. When make matches each target in the list against the pattern %.o, the part of the target that corresponds to the wildcard % is called the stem. The stem is then substituted for the percent sign in %.c to yield the prerequisite.

The general syntax of such pattern rules is:

[target_list :] target_pattern : prerequisite_pattern
        [command-script]

You must make sure that each target in the list matches the target pattern. Otherwise, make issues an error message.

If you include an explicit target list, the rule is a static pattern rule. If you omit the target list, the rule is called an implicit rule, and applies to any target whose name matches the target pattern. For example, if you expect to add more modules as the circle program grows and evolves, you can make a rule for all present and future object files in the project like this:

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

And if a certain object needs to be handled differently for some reason, you can put a static pattern rule for that object file in the makefile as well. make then applies the static rule for targets explicitly named in it, and the implicit rule for all other .o files. Also, make refrains from announcing an error if any object file’s implicit prerequisite does not exist.

The percent sign is usually used only once in each pattern. To represent a literal percent sign in a pattern, you must escape it with a backslash. For example, the filename app%3amodule.o matches the pattern app\%3a%.o, and the resulting stem is module. To use a literal backslash in a pattern without escaping a percent sign that happens to follow it, you need to escape the backslash itself. Thus, the filename app\module.o would match the pattern app\\%.o, yielding the stem module.

Suffix Rules

The kind of pattern rule in which the percent sign represents all but the filename’s suffix is the modern way of expressing a suffix rule. In older makefiles, you might see such a rule expressed in the following notation:

.c.o:
        $(CC) $(CFLAGS) ...

The “target” in this rule consists simply of the target and source filename suffixes—and in the opposite order; that is, with the source suffix first, followed by the target suffix. This example with the target .c.o: is equivalent to a pattern rule beginning with %o: %c. If a suffix rule target contains only one suffix, then that is the suffix for source filenames, and target filenames under that rule are assumed to have no suffix.

GNU make also supports suffix rules, but that notation is considered obsolete. Pattern rules using the % wildcard character are more readable, and more versatile.

Every suffix used in the target of a suffix rule must be a “known suffix.” make stores its list of known suffixes in the built-in variable SUFFIXES. You can add your own suffixes by declaring them as prerequisites of the built-in target .SUFFIXES (see “Special Targets Used as Runtime Options” for more about this technique).

Built-In Rules

You don’t have to tell make how to do standard operations like compiling an object file from C source; the program has a built-in default rule for that operation, and for many others. Example 20-2 shows a more elegant version of our sample makefile that takes advantage of built-in rules.

# A slightly more elegant makefile for "circle".
 
CC = gcc
CFLAGS = -Werror -std=c99
OBJS =  circle.o circulararea.o
 
circle: $(OBJS) -lm

This makefile does away with the rule for compiling source code into objects, depending instead on make’s built-in pattern rule. Furthermore, the rule that says the executable circle depends on the two object files has no command script. This is because make also has a built-in rule to link objects to build an executable. We will look at those built-in rules in a moment. First, suppose we enter this command:

$ touch *.c ; make circle

This produces roughly the same output as before:

gcc -Werror -std=c99   -c -o circle.o circle.c
gcc -Werror -std=c99   -c -o circulararea.o circulararea.c
gcc circle.o circulararea.o  /usr/lib/libm.so  -o circle

None of these commands is visible in the new makefile in Example 20-2, even if individual arguments are recognizable in the variable assignments. To display make’s built-in rules (as well as the variables at work), you can run the program with the command-line switch -p. The output is rather long. Here are the parts of it that are relevant to our example (including the comments that make generates to identify where each variable or rule definition originates):

# default
OUTPUT_OPTION = -o $@
 
# default
LINK.o = $(CC) $(LDFLAGS) $(TARGET_ARCH)
 
# default
COMPILE.c = $(CC) $(CFLAGS) $(CPPFLAGS) $(TARGET_ARCH) -c
 
%: %.o
#  commands to execute (built-in):
        $(LINK.o) $^ $(LOADLIBES) $(LDLIBS) -o $@
 
%.o: %.c
#  commands to execute (built-in):
        $(COMPILE.c) $(OUTPUT_OPTION) $<

Note that the linking step was handled by a combination of two rules: make automatically applied the command defined by the built-in rule using the information about the prerequisites provided by the dependency rule in the makefile.

Finally, the makefile in Example 20-2, unlike Example 20-1, does not define a variable for linker options. Instead, it correctly lists the C math library as a prerequisite of the executable circle, using the same -lm notation as the compiler’s command line. The output shown illustrates how make expands this notation to the full library filename.

Implicit Rule Chains

make tries to use implicit rules, whether built-in ones or pattern rules from the makefile, for any target that doesn’t have an explicit rule with a command script. There may be many implicit rules that match a given target. For example, make has built-in rules to generate an object file (matching the pattern %.o) from source code in C (%.c), C++ (%.cpp), or even assembler (%.s). Which rule does make use, then? It selects the first one in the list for which the prerequisites are available or can be made by applying appropriate rules. In this way, make can automatically apply a chain of implicit rules to generate a target. If make generates any intermediate files that are not mentioned in the makefile, it deletes them after they have served their purpose. For example, suppose that the current directory contains only the file square.c, and the makefile contains the following:

%: %.o
        cc -o $@ $^
 
%.o : %.c
        cc -c -o $@ $<

To disable all the built-in rules and use only the two implicit rules we can see in the makefile, we’ll run make with the -r option:

$ ls
Makefile  square.c
$ make -r square
cc -c -o square.o square.c
cc -o square square.o
rm square.o
$ ls
Makefile square  square.c

From the target, the two implicit rules in the makefile, and the available source file, make found the indirect way to build the target, and then automatically cleaned up the intermediate object file because it isn’t mentioned in the makefile or on the command line.

Double-Colon Rules

Before we move away from rules, another kind of rule that you should know about is the double-colon rule, so named because it has not one but two colons between the targets and the prerequisites:

target :: prerequisites
    commands

Double-colon rules are the same as single-colon rules unless your makefile contains multiple double-colon rules for the same target. In that case, make treats the rules as alternative rather than cumulative: instead of collating all the rules’ prerequisites into a single set of dependencies for the target, make tests the target against each rule’s prerequisites separately to decide whether to execute that rule’s script. Example 20-3 shows a makefile that uses double-colon rules.

# A makefile for "circle" to demonstrate double-colon rules.
 
CC = gcc
RM = rm -f
CFLAGS = -Wall -std=c99
DBGFLAGS = -ggdb -pg
DEBUGFILE = ./debug
SRC = circle.c circulararea.c
 
circle :: $(SRC)
        $(CC) $(CFLAGS) -o $@ -lm $^
 
circle :: $(DEBUGFILE)
        $(CC) $(CFLAGS) $(DBGFLAGS) -o $@ -lm $(SRC)
 
.PHONY : clean
clean  :
        $(RM) circle

The makefile in Example 20-3 builds the target circle in either of two ways, with or without debugging options in the compiler command line. In the first rule for circle, the target depends on the source files. make runs the command for this rule if the source files are newer than the executable. In the second rule, circle depends on a file named debug in the current directory. The command for that rule doesn’t use the prerequisite debug at all. That file is empty; it just sits in the directory for the sake of its timestamp, which tells make whether to build a debugging version of the circle executable. The following sample session illustrates how make can alternate between the two rules:

$ make clean
rm -f circle
$ make circle
gcc -Wall -std=c99 -o circle -lm circle.c circulararea.c
$ make circle
make: `circle' is up to date.
$ touch debug
$ make circle
gcc -Wall -std=c99 -ggdb -pg -o circle -lm circle.c circulararea.c
$ make circle
make: `circle' is up to date.
$ make clean
rm -f circle
$ make circle
gcc -Wall -std=c99 -o circle -lm circle.c circulararea.c

As the output shows, make applies only one rule or the other, depending on which rule’s prerequisites are newer than the target. (If both rules’ prerequisites are newer than the target, make applies the rule that appears first in the makefile.)

Assignment Operators

Which assignment operator you use in defining a variable determines whether it is a simply or a recursively expanded variable. The assignment operator = in the following example creates a recursively expanded variable:

DEBUGFLAGS = $(CFLAGS) -ggdb -DDEBUG -O0

make stores the character sequence to the right of the equals sign verbatim; the nested variable $(CFLAGS) is not expanded until $(DEBUGFLAGS) is used.

To create a simply expanded variable, use the assignment operator := as shown in the following example:

OBJ = circle.o circulararea.o
TESTOBJ := $(OBJ) profile.o

In this case, make stores the character sequence circle.o circulararea.o profile.o as the value of $(TESTOBJ). If a subsequent assignment modifies the value of $(OBJ), $(TESTOBJ) is not affected.

You can define both recursively expanded and simply expanded variables not only in the makefile, but also on the make command line, as in the following example:

$ make CFLAGS=-ffinite-math-only circulararea.o

Each such assignment must be contained in a single command-line argument. If the assignment contains spaces, you must escape them or enclose the entire assignment in quotation marks. Any variable defined on the command line, or in the shell environment, can be cancelled out by an assignment in the makefile that starts with the optional override keyword, as this one does:

override CPPLFAGS = -DDEBUG

Use override assignments with caution, unless you want to confuse and frustrate future users of your makefile.

make also provides two more assignment operators. Here is the complete list:

=

Defines a recursively expanded variable.

:=

Defines a simply expanded variable.

+=

Also called the append operator. Appends more characters to the existing value of a variable. If the left operand is not yet defined, the assignment defines a recursively expanded variable. Or, to put it another way, the result of the append operator is a recursively expanded variable, unless its left operand already exists as a simply expanded variable.

This operator provides the only way to append characters to the value of a recursively expanded variable. The following assignment is wrong, as recursive expansion would cause an infinite loop:

OBJ = $(OBJ) profile.o

Here is the right way to do it:

OBJ += profile.o

The += operator automatically inserts a space before appending the new text to the variable’s previous value.

?=

The conditional assignment operator. Assigns a value to a variable, but only if the variable has no value.

The conditional assignment operator can only define recursively expanded variables. If its left operand already exists, it remains unaffected, regardless of whether it is a simply expanded or a recursively expanded variable.

In addition to these operations, there are two more ways to define make variables. One is the define directive, used to create variables of multiple lines; we will discuss this later in “Macros”. Another is by setting environment variables in the system shell before you invoke make. We will discuss make’s use of environment variables later in the chapter as well.

Variables and Whitespace

In a variable assignment, make ignores any whitespace between the assignment operator and the first non-whitespace character of the value. However, trailing whitespace up to the end of the line containing the variable assignment, or up to a comment that follows on the same line, becomes part of the variable’s value. Usually this behavior is unimportant because most references to make variables are options in shell command lines, where additional whitespace has no effect. However, if you use variable references to construct file or directory names, unintended whitespace at the end of an assignment line can be fatal.

On the other hand, if you develop complex makefiles, you might sometimes need a literal space that make does not ignore or interpret as a list separator. The easiest way is to use a variable whose value is a single space character, but defining such a variable is tricky. Simply enclosing a space in quotation marks does not have the same effect as in C. Consider the following assignment:

ONESPACE := ' '
TEST = Does$(ONESPACE)this$(ONESPACE)work?

In this case, a reference to $(TEST) would expand to the following text:

Does' 'this' 'work?

Double quotation marks are no different: they also become part of the variable’s value. To define a variable containing just the space and nothing else, you can use the following lines:

NOTHING :=
ONESPACE := $(NOTHING) # This comment terminates the variable's value.

The variable reference $(NOTHING) expands to zero characters, but it ends the leading whitespace that make trims off after the assignment operator. If you do not insert a comment after the space character that follows $(NOTHING), you may find it hard to tell when editing the makefile whether the single trailing space is present as desired.

Target-Specific Variable Assignments

You can make any of the assignment operations apply to only a specific target (or target pattern) by including a line in your makefile with the form:

target_list: [override]assignment

While make is building the given target—or its prerequisites—the target-specific or pattern-specific variable supersedes any other definition of the same variable name elsewhere in the makefile.

Example 20-4 shows a sample makefile illustrating different kinds of assignments.

# Tools and options:
CC = gcc
CFLAGS = -c -Wall -std=c99 $(ASMFLAGS)
DEBUGCFLAGS = -ggdb -O0
RM = rm -f
MKDIR = mkdir -p
 
# Filenames:
OBJ = circle.o circulararea.o
SYMTABS = $(OBJ:.o=.sym)
EXEC = circle
 
# The primary targets:
production: clean circle
 
testing: clean debug
 
symbols: $(SYMTABS)
 
clean:
        $(RM) $(OBJ) *.sym circle circle-dbg
 
# Rules to build prerequisites:
circle debug: $(OBJ) -lm
        $(CC) $(LDFLAGS) -o $(EXEC) $^
 
$(OBJ): %.o: %.c
        $(CC) $(CFLAGS) $(CPPFLAGS) -o $@ $<
 
$(SYMTABS): %.sym: %.c
        $(CC) $(CFLAGS) $(CPPFLAGS) -o $*.o $<
 
# Target-specific options:
debug: CPPFLAGS += -DDEBUG
debug: EXEC = circle-dbg
debug symbols: CFLAGS += $(DEBUGCFLAGS)
symbols: ASMFLAGS = -Wa,-as=$*.sym,-L

For the targets debug and symbols, this makefile uses the append operator to add the value of DEBUGCFLAGS to the value of CFLAGS, while conserving any compiler flags already defined.

The assignment to SYMTABS illustrates another feature of make variables: you can perform substitutions when referencing them. As Example 20-4 illustrates, a substitution reference has this form:

$(name:ending=new_ending)

When you reference a variable in this way, make expands it, and then checks the end of each word in the value (where a word is a sequence of non-whitespace characters followed by a whitespace character, or by the end of the value) for the string ending. If the word ends with ending, make replaces that part with new_ending. In Example 20-4, the resulting value of $(SYMTABS) is circle.sym circulararea.sym.

The variable CFLAGS is defined near the top of the makefile, with an unconditional assignment. The expansion of the nested variable it contains, $(ASMFLAGS), is deferred until make expands $(CFLAGS) in order to execute the compiler command. The value of $(ASMFLAGS), for example, may be -Wa,-as=circle.sym,-L, or it may be nothing. When make builds the target symbols, the compiler command expands recursively to:

gcc -c -Wall -std=c99 -Wa,-as=circle.sym,-L -ggdb -O0
-o circle.o circle.c
gcc -c -Wall -std=c99 -Wa,-as=circulararea.sym,-L -ggdb -O0
-o circulararea.o circulararea.c

(Each of these two gcc commands is generated in a single line, which is split in two here to fit the page.) As you can see, if there is no variable defined with the name CPPFLAGS at the time of variable expansion, make simply replaces $(CPPFLAGS) with nothing.

Like many real-life makefiles, the one in Example 20-4 uses variables to store the names of common utilities like mkdir and rm together with the standard options that we want to use with them. This approach not only saves repetition in the makefile’s command scripts but also makes maintenance and porting easier.

The Automatic Variables

The command scripts in Example 20-4 also contain a number of single-character variables: $@, $<, $‸, and $*. These are automatic variables, which make defines and expands itself in carrying out each rule. Here is a complete list of the automatic variables and their meanings in a given rule:

$@

The target filename.

$*

The stem of the target filename—that is, the part represented by % in a pattern rule.

$<

The first prerequisite.

$‸

The list of prerequisites, excluding duplicate elements.

$?

The list of prerequisites that are newer than the target.

$+

The full list of prerequisites, including duplicates.

$%

If the target is an archive member, the variable $% yields the member name without the archive filename, and $@ supplies the filename of the archive.

The last of these automatic variables brings up a special target case. Because most programs depend not only on source code but also on library modules, make also provides a special notation for targets that are members of an archive:

archive_name(member_name): [prerequisites]
        [command_script]

The name of the archive member is enclosed in parentheses immediately after the filename of the archive itself. Here is an example:

AR = ar -rv
 
libcircularmath.a(circulararea.o): circulararea.o
      $(AR) $@ $%

This rule executes the following command to add or replace the object file in the archive:

ar -rv libcircularmath.a circulararea.o

In other make versions, these special variables also have long names that start with a dot, such as $(.TARGET) as a synonym for $@. Also, some make programs use the symbol $> for all prerequisites rather than GNU make’s $‸.

When an automatic variable expands to a list, such as a list of filenames, the elements are separated by spaces.

To separate filenames from directories, there are two more versions of each automatic variable in this list whose names are formed with the suffixes D and F. Because the resulting variable name is two characters, not one, parentheses are required. For example, $(@D) in any rule expands to the directory part of the target, without the actual filename, while $(@F) yields just the filename with no directory. (GNU make supports these forms for compatibility’s sake, but provides more flexible handling of filenames by means of functions; see “Built-In Functions”.)

Other Built-In Variables

The variables that make uses internally are described in the following list. You can also use them in makefiles. Remember that you can find out the sources of all variables in the output of make -p:

CURDIR

This variable holds the name of the current working directory after make has processed its -C or --directory command-line options. You can modify this variable, but doing so doesn’t change the working directory.

.LIBPATTERNS

A list of filename patterns that determines how make searches for libraries when a prerequisite starts with -l. The default value is lib%.so lib%.a. A prerequisite called -lncurses causes make to search for libncurses.so and libncurses.a, in that order.

MAKE

This variable holds the name of the make executable. When you use $(MAKE) in a command, make automatically expands it to the full path name of the program file so that all recursive instances of make are from the same executable.

MAKECMDGOALS

make stores any targets specified on the command line in this variable. You can modify this variable, but doing so doesn’t change the targets make builds.

MAKEFILES

A list of standard makefiles that make reads every time it starts.

MAKEFILE_LIST

A list of all the makefiles that the present invocation of make is using.

MAKEFLAGS

This variable contains the command-line options with which make was invoked, with some exceptions. Each instance of make reads this variable from the environment on starting, and exports it to the environment before spawning a recursive instance. You can modify this variable in the environment or in a makefile.

MAKELEVEL

When make invokes itself recursively, this variable holds the degree of recursion of the present instance. In exporting this variable to the environment, make increments its value. Child instances of make print this number in square brackets after the program name in their console output.

MAKESHELL

On Windows, this variable holds the name of the command interpreter for make to use in running command scripts. MAKESHELL overrides SHELL.

SHELL

The name of the shell that make invokes when it runs command scripts, usually /bin/sh. Unlike most variables, make doesn’t read the value of SHELL from the environment (except on Windows), as users’ shell preferences would make make’s results less consistent. If you want make to run commands using a specific shell, you must set this variable in your makefile.

SUFFIXES

make’s default list of known suffixes (see “Suffix Rules”). This variable contains the default list, which is not necessarily the list currently in effect; the value of this variable does not change when you clear the list or add your own known suffixes using the built-in target .SUFFIXES.

VPATH

The directory path that make uses to search for any files not found in the current working directory.

Environment Variables

If you want, you can set environment variables in the shell before starting make, and then reference them in the makefile using the same syntax as for other make variables. Furthermore, you can use the export directive in the makefile to copy any or all of make’s variables to the shell environment before invoking shell commands, as in the following example:

INCLUDE=/usr/include:/usr/local/include:~/include
export INCLUDE
export LIB := $(LIBS):/usr/lib:/usr/local/lib
 
%.o: %.c
        $(CC) $(CFLAGS) -o $@ -c $<

When the C compiler is invoked by the pattern rule in this example, it can obtain information defined in the makefile by reading the environment variables INCLUDE and LIB. Similarly, make automatically passes its command-line options to child instances by copying them to and then exporting the variable MAKEFLAGS. See “Recursive make Commands” for other examples.

The shell environment is more restrictive than make with regard to the characters that are permitted in variable names and values. It might be possible to trick your shell into propagating environment variables containing illegal characters, but the easiest thing by far is just to avoid special characters in any variables you want to export.

Built-In Functions

GNU make provides more than 20 useful text-processing and flow-control functions, which are listed briefly in the following sections.

User-Defined Functions

You can define functions in the same way as simply expanded variables or macros, using the define directive or the := assignment operator. Functions in make are simply variables that contain numbered parameter references ($1, $2, $3, etc.) to represent arguments that you provide when you use the built-in function call to expand the variable.

In order for these parameters to be replaced with the arguments when make expands your user-defined function, you have to pass the function name and arguments to the built-in make function call.

Example 20-5 defines the macro getmodulename to return a filename for a program module depending on whether the flag STATIC has been set, to indicate a statically linked executable, or left undefined, to indicate dynamic object linking.

# A conditional assignment, just as a reminder that
# the user may define STATIC=1 or STATIC=yes on the command line.
STATIC ?=
 
# A function to generate the "library" module name:
# Syntax: $(call getmodulename, objectname, isstatic)
define getmodulename
  $(if $2,$1,$(addsuffix .so,$(basename $1)))
endef
 
all: circle
 
circle: circle.o $(call getmodulename,circulararea.o,$(STATIC))
        $(CC) -o $@ $^
 
ifndef STATIC
%.so: %.o
      $(CC) -shared -o $@ $<
endif

The $(call …) function expands the macro getmodulename either to the text circulararea.o, or, if the variable STATIC is not defined, to circulararea.so.

The rule to build the object file circulararea.o in Example 20-5 brings us to our next topic, as it illustrates another way to query the STATIC flag: by means of the conditional directive ifndef.

Conditionals

You can also make part of your makefile conditional upon the existence of a variable by using the ifdef or ifndef directive. They work the same as the C preprocessor directives of the same names, except that in make, an undefined variable is the same as one whose value is empty. Here is an example:

OBJ = circle.o
LIB = -lm
 
ifdef SHAREDLIBS
  LIB += circulararea.so
else
  OBJ += circulararea.o
endif
 
circle: $(OBJ) $(LIB)
        $(CC) -o $@ $^
 
%.so : %.o
       $(CC) -shared -o $@ $<

As the example shows, the variable name follows ifdef or ifndef without a dollar sign or parentheses. The makefile excerpt shown here defines a rule to link object files into a shared library if the variable SHAREDLIBS has been defined. You might define such a general build option in an environment variable, or on the command line, for example.

You can also make certain lines of the makefile conditional upon whether two expressions—usually the value of a variable and a literal string—are equal. The ifeq and ifneq directives test this condition. The two operands whose equality is the condition to test are either enclosed together in parentheses and separated by a comma, or enclosed individually in quotation marks and separated by whitespace. Here is an example:

ifeq ($(MATHLIB), /usr/lib/libm.so)
  # ... Special provisions for this particular math library ...
endif

That conditional directive, with parentheses, is equivalent to this one with quotation marks:

ifeq "$(MATHLIB)" "/usr/lib/libm.so"
  # ... Special provisions for this particular math library ...
endif

The second version has one strong advantage: the quotation marks make it quite clear where each of the operands begins and ends. In the first version, you must remember that whitespace within the parentheses is significant, except immediately before and after the comma (see also “Variables and Whitespace”).

Includes

The include directive serves the same purpose as its C preprocessor counterpart but works slightly differently. To start with an example, you might write a makefile named defaults.mk with a set of standard variables for your environment, containing something like this:

BINDIR = /usr/bin
HOMEBINDIR = ~/bin
SRCDIR = project/src
BUILDDIR = project/obj
 
RM = rm -f
MKDIR = mkdir -p
# ... etc. ...

Then you could add these variables to any makefile by inserting this line:

include defaults.mk

The include keyword may be followed by more than one filename. You can also use shell wildcards like * and ?, and reference make variables to form filenames:

include $(HOMEBINDIR)/myutils.mk $(SRCDIR)/*.mk

For included files without an absolute path, make searches in the current working directory first, then in any directories specified with the -I option on the command line, and then in standard directories determined when make was compiled.

If make fails to find a file named in an include directive, it continues reading the makefile, and then checks to see whether there is a rule that will build the missing file. If so, make rereads the whole makefile after building the included file. If not, make exits with an error. The -include directive (or its synonym sinclude) is more tolerant: it works the same as include except that make ignores the error and goes on working if it can’t find or build an included file.

Other Directives

Of the other four make directives, three are used to control the interplay between make’s internal variables and the shell environment, while the fourth instructs make where to look for specific kinds of files. These directives are:

override variable_assignment

Ordinarily, variables defined on the command line take precedence over definitions or assignments with the same name in a makefile. Prefixing the override keyword makes an assignment in a makefile take precedence over the command line. The variable_assignment may use the =, :=, or += operator, or the define directive.

export [variable_name|variable_assignment]

You can prefix export to a variable assignment or to the name of a variable that has been defined to export that variable to the environment, so that programs invoked by command scripts (including recursive invocations of make) can read it.

The export directive by itself on a line exports all make variables to the environment.

Tip

make does not export variables whose names contain any characters other than letters, digits, and underscores. The values of variables you export from makefiles may contain characters that are not allowed in shell environment variables. Such values will probably not be accessible by ordinary shell commands. Nonetheless, child instances of make itself can inherit and use them.

The make variables SHELL and MAKEFLAGS, and also MAKEFILES if you have assigned it a value, are exported by default. Any variables that the current instance of make acquired from the environment are also passed on to child processes.

unexport variable_name

Use the unexport directive to prevent a variable from being exported to the environment. The unexport directive always overrides export.

vpath pattern directory[:directory[:…]]

The pattern in this directive is formed in the same way as in make pattern rules, using one percent sign (%) as a wildcard character. Whenever make needs a file that matches the pattern, it looks for it in the directories indicated, in the order of their appearance. Here is an example:

vpath  %.c  $(MYPROJECTDIR)/src
vpath  %.h  $(MYPROJECTDIR)/include:/usr/include

On Windows, the separator character in the directory list is a semicolon, not a colon.

Generating Header Dependencies

Our program executable circle depends on more files than those we have named in the sample makefile up to now. To begin with, just think of the standard headers included in our source code—not to mention the implementation-specific header files they include in turn.

Most C source files include both standard and user-defined header files, and the compiled program should be considered out of date whenever any header file has been changed. Because you cannot reasonably be expected to know the full list of header files involved, the standard make technique to account for these dependencies is to let the C preprocessor analyze the #include directives in your C source and write the appropriate make rules. The makefile lines in Example 20-6 fulfill this purpose.

CC = gcc
OBJ = circle.o circulararea.o
LIB = -lm
 
circle: $(OBJ) $(LIB)
        $(CC) $(LDFLAGS) -o $@ $^
 
%.o: %.c
        $(CC) $(CFLAGS) $(CPPFLAGS) -o $@ $<
 
dependencies: $(OBJ:.o=.c)
        $(CC) -M $^ > $@
 
include dependencies

The third rule uses a special kind of make variable reference, called a substitution reference, to declare that the target dependencies depend on files like those named in the value of $(OBJ) but with the ending .c instead of .o. The command to build dependencies runs the compiler with the preprocessor option -M, which instructs it to collate dependency information from source files. (The GCC compiler permits fine control of the dependency output by means of more preprocessor options that start with -M, which are listed in “GCC Options for Generating Makefile Rules”.)

The first time you use this makefile, make prints an error message about the include directive because no file named dependencies exists. When this happens, however, make automatically treats the missing file named in the include directive as a target, and looks for a rule to build it. The include directive itself is placed below the target rules to prevent the included file’s contents from defining a new default target.

Recursive make Commands

Your makefile rules can include any command that is executable on your system. This includes the make command itself, and recursive invocation of make is in fact a frequently used technique, especially to process source code in subdirectories. make is designed to be aware of such recursive invocation, and incorporates certain features that help it work smoothly when you use it in this way. This section summarizes the special features of “recursive make.”

The most typical recursive use of make is in building projects that are organized in subdirectories with a makefile in each one. The following snippet illustrates how a top-level makefile can invoke recursive instances of make in three subdirectories named utils, drivers, and doc:

.PHONY: utils drivers doc
 
utils drivers doc:
    $(MAKE) -C $@

The variable MAKE is not defined in the makefile; it is defined internally to yield the full pathname of the currently running program file. Your makefiles should always invoke make in this way to ensure consistent program behavior.

The command-line option -C, or its long form, --directory, causes make to change to the specified working directory on startup, before it even looks for a makefile. This is how make “passes control” to the makefile in a subdirectory when used recursively. In this example, the command does not name a target, so the child make will build the first target named in the default makefile in the given subdirectory.

The subdirectories themselves are declared as prerequisites of the special target .PHONY so that make never considers them up to date (see “Phony Targets” for more details). However, if files in one subdirectory depend on files in a parallel subdirectory, you must account for these dependencies in the makefile of a higher-level directory that contains both subdirectories.

There are a few things to remember about command-line options and special variables when you use make recursively. A more complete list of make options and environment variables appears in the following section. The following list merely summarizes those with a special relevance to the recursive use of make:

• Some of make’s command-line options instruct it not to execute commands but to only print them (-n), touch the files (-t), or indicate whether the targets are up to date (-q). In these cases, if the subordinate make command were not executed, then these options would be incompatible with the recursive use of make. To ensure recursion, when you run make with one of the -t, -n, or -q options, commands containing the variable reference $(MAKE) are executed even though other commands are not. You can also extend this special treatment to other commands individually by prefixing a plus sign (+) to the command line as a command modifier.

• The variable MAKELEVEL automatically contains a numeral indicating the recursion depth of the current make instance, starting with 0 for a make invoked from the console.

• The parent instance of make passes its command-line options to child instances by copying them to the environment variable MAKEFLAGS. However, the options -C, -f, -o, and -W are exceptions: these options, which take a file or directory name as their argument, do not appear in MAKEFLAGS.

• The -j option, whose argument tells make how many commands it can spawn for parallel processing, is passed on to child instances of make but with the parallel job limit decreased by one.

• By default, a child instance of make inherits those of its parent’s variables that were defined on the command line or in the environment. You can use the export directive to pass on variables defined in a makefile.

Like any other shell command in a makefile rule, a recursive instance of make can exit with an error status. If this happens, the parent make also exits with an error (unless it was started with the -k or --keep-going option), so that the error cascades up the chain of recursive make instances.

When using make recursively with multiple makefiles in subdirectories, you should use the include directive to avoid duplicating common definitions, implicit rules, and so on. See “Includes” for more information.

Command-Line Options

The following is a brief summary of the command-line options supported by GNU make. Some of these options can also be enabled by including special targets in the makefile. These targets are described in “Special Targets Used as Runtime Options”.

-B, --always-make

Build unconditionally. In other words, make considers all targets out of date.

-C dir, --directory=dir

make changes the current working directory to dir before it does anything else. If the command line includes multiple -C options (which is often the case when make invokes itself recursively), each directory specified builds on the previous one. Here is an example:

$ make -C src -C common -C libs

These options would have the same effect as -C src/common/libs.

-d

Print debugging information.

-e, --environment-overrides

In the case of multiple definitions of a given variable name, variables defined on the make command line or in makefiles normally have precedence over environment variables. This command-line option makes environment variables take precedence over variable assignments in makefiles (except for variables specified in override directives).

-f filename, --file=filename, --makefile=filename

Use the makefile filename.

-h, --help

Print make’s command-line options.

-i, --ignore-errors

Ignore any errors that occur when executing command scripts.

-I dir, --include-dir=dir

If a makefile contains include directives that specify files without absolute paths, search for such files in the directory dir (in addition to the current directory). If the command line includes several -I options, the directories are searched in the order of their occurrence.

-j [number], --jobs[=number]

Run multiple commands in parallel. The optional integer argument number specifies the maximum number of simultaneous jobs. The -j argument by itself causes make to run as many simultaneous commands as possible. (Naturally, make is smart enough not to start building any target before its prerequisites have been completed.) If the command line includes several -j options, the last one overrides all others.

-k, --keep-going

This option tells make not to exit after a command has returned a nonzero exit status. Instead, make abandons the failed target and any other targets that depend on it but continues working on any other goals in progress.

-l [number], --load-average[=number], --max-load[=number]

In conjunction with the -j option, -l (that’s a lowercase L) prevents make from executing more simultaneous commands whenever the system load is greater than or equal to the floating-point value number. The -l option with no argument cancels any load limit imposed by previous -l options.

-n, --just-print, --dry-run, --recon

make prints the commands it would otherwise run, but doesn’t actually execute them.

-o filename, --old-file=filename, --assume-old=filename__

make treats the specified file as if it were up to date, and yet older than any file that depends on it.

-p, --print-data-base

Before executing any commands, make prints its version information and all its rules and variables, including built-ins and those acquired from makefiles.

-q, --question

make builds nothing and prints nothing, but returns an exit status as follows:

Exit status	Meaning
0	All specified targets are up to date.
1	At least one target is out of date.
2	An error occurred.

-r, --no-builtin-rules

This option disables make’s built-in implicit rules, as well as the default list of suffixes for old-style suffix rules. Pattern rules, user-defined suffixes, and suffix rules that you have defined in makefiles still apply, as do built-in variables.

-R, --no-builtin-variables

Like -r, but also disables make’s built-in rule-specific variables. Variables you define in makefiles are unaffected.

-s, --silent, --quiet

Ordinarily, make echoes each command on standard output before executing it. This option suppresses such output.

-S, --no-keep-going, --stop

This option causes a recursive instance of make to ignore a -k or --keep-going option inherited from its parent make.

-t, --touch

make simply touches target files—that is, it updates their timestamps—instead of rebuilding them.

-v, --version

make prints its version and copyright information.

-w, --print-directory

make prints a line indicating the working directory before and after processing the makefile. This output can be useful in debugging recursive make applications. This option is enabled by default for recursive instances of make, and whenever you use the -C option.

--no-print-directory

Disable the working directory output in cases where -w is automatically activated.

-W filename, --what-if=filename, --new-file=<filename,
--assume-new=filename

make treats the file filename as if it were brand new.

--warn-undefined-variables

Normally, make takes references to undefined variables in its stride, treating them like references to variables with empty values. This option provides warnings about undefined variables to help you debug makefiles.

Special Targets Used as Runtime Options

The built-in targets listed in this section are ordinarily used in makefiles to alter make’s runtime behavior in general. Other built-in targets are used primarily to assign attributes to certain targets in a makefile, and are listed in “Other Target Attributes”.

.DEFAULT

You can use the built-in target .DEFAULT to introduce a command script that you want make to execute for any target that is not covered by any other explicit or implicit rule. make also executes the .DEFAULT command script for every prerequisite that is not a target in some rule.

.DELETE_ON_ERROR

You can include the built-in target .DELETE_ON_ERROR anywhere in a makefile to instruct make to delete any target that has been changed by its command script if the script returns a nonzero value on exiting.

.SILENT

Normally, make prints each command to standard output before executing it. However, if a given target is a prerequisite of .SILENT, then make does not print the rules when building that target.

If you include .SILENT with no prerequisites in a makefile, it applies to all targets, like the command-line options -s or --silent.

.EXPORT_ALL_VARIABLES

This target acts as an option telling make to export all the currently defined variables before spawning child processes (see “Recursive make Commands”).

.NOTPARALLEL

This built-in target is a general option; any prerequisites are ignored. The target .NOTPARALLEL in a makefile overrides the command-line option -j for the current instance of make, so that targets are built in sequence. If make invokes itself, however, the new instance of make still executes commands in parallel, unless its makefile also contains .NOTPARALLEL.

.SUFFIXES

This built-in target defines the list of suffixes that make recognizes for use in old-style suffix rules (see “Suffix Rules”). You can add suffixes to the built-in list by naming them as prerequisites of .SUFFIXES, or clear the list by declaring the target .SUFFIXES with no prerequisites.

GCC Options for Generating Makefile Rules

-M

Generate a rule showing the prerequisites for the object file that would result from compiling a given source file. The -M option implies the -E option (preprocess only; don’t compile), but the -MD and -MMD variants do not. By default, the dependency rules are written to standard output.

-MD

Like -M, but allows GCC to compile source files (unless -E is also present) in addition to running the preprocessor. The dependency output is written to a file whose name is taken from the -o argument, if any, but with the filename ending .d.

-MM

Like -M, but omit header files located in system header directories (and any files they depend on in turn) from the dependency list.

-MMD

Combines the effects of -MM and -MD.

The following options are modifiers used in addition to -M, -MD, -MM, or -MMD:

-MF filename

Writes the dependency information to filename rather than to standard output or to a preprocessor output file.

-MG

Include nonexistent header files in the dependency list.

-MP

Include a phony target for each header file in the dependency output. The effect is that make doesn’t complain about header files that have been removed from the project but not from the dependency list.

-MT target

Substitute target for the actual target in generating dependency rules.

-MQ target

Like -MT, but quote any special characters.