make(1)

Makefile Structure

A makefile can contain four different kinds of lines: target lines, shell command lines, macro definitions, and include lines.

General Description

make executes commands previously placed in a makefile to update one or more target names. Target names are typically names of programs. If no -f option is specified, the file names makefile, Makefile, s.makefile, SCCS/s.makefile, s.Makefile and SCCS/s.Makefile are tried in that order. If -f - is specified, the standard input is used. More than one -f option can be specified. The makefile arguments are processed in the order specified. A space between the -f and the file name must be present, and multiple makefile names must each have their own -f option preceding them. The contents of a makefile override the built-in rules and macros if they are present.

If no target names are specified on the command line, make updates the first target in the (first) makefile that is not an inference rule. A target is updated in two cases: firstly, if it depends on files that are newer than the target; secondly, if it depends on files that have same modification time as that of the target. Missing files are deemed to be out-of-date. All dependents of a target are recursively updated, if necessary, before the target is updated. This effects a depth-first update of the dependency tree for the target.

If a target does not have any dependents specified after the separator on the target line (explicit dependents), any shell commands associated with that target are executed if the target does not exist.

A target line can have either a single or double colon between the target name or names and any explicit dependent names. A target name can appear on more than one target line, but all of those lines must be of the same (single- or double-colon) type. For the usual single-colon case, at most one of these target lines can have explicit commands associated with it. If the target is out-of-date with any of its dependents on any of the lines, the explicit commands are executed, if they are specified, or else a default rule can be executed. For the double-colon case, explicit commands can be associated with more than one of the target lines containing the target name; if the target is out-of-date with any of the dependents on a particular line, the commands for that line are executed. A built-in rule may also be executed.

Target lines and their associated shell command lines are also referred to as rules. Hash marks (#) and newline characters surround comments anywhere in the makefile except in rules. Comments in the rules depend on the setting of the SHELL macro.

The following makefile says that pgm depends on two files: a.o and b.o, and that they in turn depend on their corresponding source files (a.c and b.c) and a common file incl.h:

Command lines are executed one at a time, each by its own shell. Each command line can have one or more of the following prefixes: -, @, or +. These prefixes are explained below.

Commands returning nonzero status normally terminate make. The -i option or the presence of the special target .IGNORE in the makefile cause make to continue executing the makefile regardless of how many command lines cause errors, although the error messages are still printed on standard output. If - is present at the beginning of a command line, any error returned by that line is printed to standard output but make does not terminate. The prefix - can be used to selectively ignore errors in a makefile. If the -k option is specified and a command line returns an error status, work is abandoned on the current target, but continues on other branches that do not depend on that target. If the -k option is present in the MAKEFLAGS environment variable, processing can be returned to the default by specifying the -S option.

The -n option specifies printing of a command line without execution. However, if the command line has the string $(MAKE) or ${MAKE} in it or + as a prefix, the line is always executed (see discussion of the MAKEFLAGS macro under Environment). The -t (touch) option updates the modified date of a file without executing any commands.

A command line is normally printed before it is executed, but if the line has a @ at the beginning, printing is suppressed. The -s option or the presence of the special target .SILENT: in the makefile suppresses printing of all command lines. The @ can be used to selectively turn off printing. Everything printed by make (except the initial tab) is passed directly to the shell without alteration. Thus,

produces

just as the shell would.

The -b option allows old makefiles (those written for the old version of make) to run without errors. The old version of make assumed that if a target did not have any explicit commands associated with it, the user intended the command to be null, and would not execute any .DEFAULT rule that might have been defined. The current version of make operates in this mode by default. However, the current version of make provides a -B option which turns this mode off so that if a target does not have explicit commands associated with it and a .DEFAULT rule is defined, the .DEFAULT rule is executed. Note that the -b and -B options have no effect on the search and possible location and execution of an appropriate inference rule for the target. The search for a built-in inference rule other than .DEFAULT is always performed.

The signals SIGINT, SIGQUIT, SIGHUP, and SIGTERM (see signal(5)) cause the target to be deleted unless the target depends on the special name .PRECIOUS.

Options

The following is a brief description of all options and some special names. Options can occur in any order. They can be specified separately, or together with one -, except for the -f option.

Parallel Make

If make is invoked with the -P option, it tries to build more than one target at a time, in parallel. (This is done by using the standard UNIX system process mechanism which enables multiple processes to run simultaneously.) For the makefile shown in the example in the previous subsection, it would create processes to build a.o and b.o in parallel. After these processes were complete, it would build pgm.

The number of targets make will try to build in parallel is determined by the value of the environment variable PARALLEL. If -P is invoked, but PARALLEL is not set, then make will try to build no more than two targets in parallel.

You can use the .MUTEX directive to serialize the updating of some specified targets. This is useful when two or more targets modify a common output file, such as when inserting modules into an archive or when creating an intermediate file with the same name, as is done by lex and yacc. If the makefile in the previous subsection contained a .MUTEX directive of the form

it would prevent make from building a.o and b.o in parallel.

Environment

All variables defined in the environment (see environ(5)) are read by make and are treated and processed as macro definitions, with the exception of the SHELL environment variable which is always ignored. The value of the SHELL environment variable will not be used as a macro and will not be modified by defining the SHELL macro in a makefile or on the command line. Variables with no definition or empty string definitions are included by make.

There are four possible sources of macro definitions which are read in the following order: internal (default), current environment, the makefile(s), and command line. Because of this order of processing, macro assignments in a makefile override environment variables. The -e option allows the environment to override the macro assignments in a makefile. Command-line macro definitions always override any other definitions.

The MAKEFLAGS environment variable is processed by make on the assumption that it contains any legal input option (except -f, -p, and -d) defined for the command line. The MAKEFLAGS variable can also be specified in the makefile.

(UNIX Standard only, see standards(5). MAKEFLAGS in the makefile replaces the MAKEFLAGS environment variable. Command line options have precedence over MAKEFLAGS environment variable.)

If MAKEFLAGS is not defined in either of these places, make constructs the variable for itself, puts the options specified on the command line and any default options into it, and passes it on to invocations of commands. Thus, MAKEFLAGS always contains the current input options. This proves very useful for doing recursive make commands. Even when the -n option is specified, command lines containing the string $(MAKE) or ${MAKE} are executed; hence, one can perform a make -n recursively on an entire software system to see what would have been executed. This is possible because the -n is put into MAKEFLAGS and passed to the recursive invocations of $(MAKE) or ${MAKE}. This is one way of debugging all of the makefiles for a software project without actually executing any of the commands.

Each of the commands in the rules is given to a shell to be executed. The shell used is the shell command interpreter (see sh(1)), or the one specified in the makefile by the SHELL macro. To ensure the same shell is used each time a makefile is executed, the line:

or a suitable equivalent should be put in the macro definition section of the makefile.

Suffixes

Target and/or dependent names often have suffixes. Knowledge about certain suffixes is built into make and used to identify appropriate inference rules to be applied to update a target (see the subsection on Inference Rules). The current default list of suffixes is:

These suffixes are defined as the dependents of the special built-in target .SUFFIXES. This is done automatically by make.

Additional suffixes can be specified in a makefile as the dependents list for .SUFFIXES. These additional values are added to the default values. Multiple suffix lists accumulate. The order of the suffix list is significant (see the Inference Rules subsection). If the user wishes to change the order of the suffixes, he must first define .SUFFIXES with a null dependent list, which clears the current value for .SUFFIXES, and then define .SUFFIXES with the suffixes in the desired order. The list of suffixes built into make on any machine can be displayed by:

The list of built-in suffixes incorporated with the definitions in a given makefile called mymakefile can be displayed by:

Inference Rules

Certain target or dependent names (such as those ending with .o) have inferable dependents such as .c and .s, etc. If no update commands for such a name appear in the makefile, and if an inferable dependent file exists, that dependent file is compiled to update the target. In this case, make has inference rules that allow building files from other files by examining the suffixes and determining an appropriate inference rule to use. There are currently default inference rules defined for:

Double suffix inference rules (.c.o) define how to build x.o from x.c. Single suffix inference rules (.c) define how to build x from x.c. In effect, the first suffix is null. Single suffix rules are useful for building targets from only one source file; e.g., shell procedures and simple C programs.

A tilde in the above rules refers to an SCCS file (see sccsfile(4)). Thus, the rule .c~.o would transform an SCCS C source file into an object file (.o). Since the s. of the SCCS files is a prefix, it is incompatible with the suffix point-of-view of the make command. Hence, the tilde is a way of changing any file reference into an SCCS file reference.

A rule to create a file with suffix .o from a file with suffix .c is specified as an entry with .c.o as the target and no dependents. Shell commands associated with the target define the rule for making a .o file from a .c file. Any target name that has no slashes in it and starts with a dot is identified as an inference (implicit) rule instead of a target (explicit) rule. Targets with one dot are single suffix inference rules; targets with two dots are double suffix inference rules. Users can, in a makefile, define additional inference rules and either redefine or cancel default inference rules.

The default inference rule for changing a .c file into a .o file might look like this:

and the default inference rule for changing a yacc file to a C object file might look like this:

Certain macros are used in the default inference rules to permit the inclusion of optional matter in any resulting commands. For example, CFLAGS, LDFLAGS, and YFLAGS are used for compiler options to cc(1), lex(1), and yacc(1), respectively. LDFLAGS is commonly used to designate linker/loader options. These macros are automatically defined by make but can be redefined by the user in the makefile.

The macro LIBS is, by convention, used to specify the order of inclusion of any special libraries during the linking phase of compilation. To specify a particular order of inclusion for a particular set of libraries, the existing single suffix rule for a .c file,

can be redefined as

as well as defining LIBS in the makefile.

There are also some special built-in macros used in the inference rules (@, <). See the Built-in Macros subsection.

If a target does not have explicit dependents, or if a dependent does not also have a target that matches it with associated explicit rules, make looks for the first inference rule that matches both the target's (dependent's) suffix (which may be null) and a file which matches the other suffix of the rule. Since it conducts this search by going through the list of .SUFFIXES values front to back, the order in which .SUFFIXES is defined is significant.

To print out the rules compiled into the make on any machine, type:

Since make defines an inference rule .c.o, the example in the General Description subsection can be rewritten more simply:

Libraries

If a target or dependent name contains parentheses, it is assumed to be an archive library, the string within parentheses referring to a member within the library. Thus lib(file.o) and $(LIB)(file.o) both refer to an archive library that contains file.o (this assumes the LIB macro has been previously defined). The expression $(LIB)(file1.o file2.o) is not valid. Rules pertaining to archive libraries have the form .xx.a where xx is the suffix from which the archive member is to be made. An unfortunate byproduct of the current implementation requires the xx to be different from the suffix of the archive member. Thus, one cannot have lib(file.o) depend upon file.o explicitly. The most common use of the archive interface follows. Here, we assume the source files are all C type source:

(See the subsection on Built-in Macros for an explanation of the <, @, and * symbols.) In fact, the .c.a rule listed above is built into make and is unnecessary in this example. This rule is applied to each dependent of lib in turn. The following example accomplishes this more efficiently:

Here substitution in the macros is used. The $? list is defined to be the set of object file names (inside lib) whose C source files are out-of-date. The substitution sequence translates the .o to .c. (Unfortunately, one cannot as yet transform to .c~; however, this may become possible in the future.) Note also, the disabling of the .c.a rule, which would have created and archived each object file, one by one. This particular construct speeds up archive library maintenance considerably, but becomes very cumbersome if the archive library contains a mix of assembly programs and C programs.

Archive members containing the definition of a symbol are designated by double parentheses around the symbol name, lib((entry_name)), but are otherwise handled as described above.

Built-In Targets

make has knowledge about some special targets. These must be specified in the makefile to take effect (with the exception of .SUFFIXES, which is automatically set by make but can be changed by the user).

Built-in Macros

There are five internally maintained macros that are useful for writing rules for building targets. In order to clearly define the meaning of these macros, some clarification of the terms target and dependent is necessary. When make updates a target, it may actually generate a series of targets to update. Before any rule (either explicit or implicit) is applied to the target to update it, recursion takes place on each dependent of the target. The dependent, upon recursion, becomes a target itself, and may have or generate its own dependents, which in turn are recursed upon until a target is found that has no dependents, at which point the recursion stops. Not all targets processed by make appear as explicit targets in the makefile; some of them are explicit dependents from the makefile while others are implicit dependents generated as make recursively updates the target. For instance, when the following makefile is executed:

the following series of targets to be made is generated:

In the definitions below, the word target refers to a target specified in the makefile, an explicit dependent specified in the makefile which becomes the target when make recurses on it, or an implicit dependent (generated as a result of locating an inference rule and file that match the suffix of the target) which becomes the target when make recurses on it. The word dependent refers to an explicit dependent specified in the makefile for a particular target, or an implicit dependent generated as a result of locating an appropriate inference rule and corresponding file that matches the suffix of the target.

It may be helpful to think of target rules as user specified rules for a particular target name, and inference rules as user or make specified rules for a particular class of target names. It may also be helpful to remember that the value of the target name and its corresponding dependent names change as make recurses on both explicit and implicit dependents, and that inference rules are only applied to implicit dependents or to explicit dependents which do not have target rules defined for them in the makefile.

These five macros can have alternative forms. When an uppercase D or F is appended to any of the five macros, the meaning is changed to ``directory part'' for D and ``file part'' for F. Thus, $(@D) refers to the directory part of the string $@. If there is no directory part, ./ is generated. When the $? macro contains more than one dependent name, the $(?D) expands to a list of directory name parts and the $(?F) expands to a list of the file name parts.

In addition to the built-in macros listed above, other commonly used macros are defined by make. These macros are used in the default inference rules, and can be displayed with the -p option. These macros can be used in target rules in the makefile. They can also be redefined in the makefile.

Special Macros

The VPATH macro allows make to search a colon separated list of directories for dependents. Lines of the form VPATH= path1:path2 ... causes make to first search the current directory for a dependent and if the dependent is not found, make searches path1 and continues until the directories specified in the VPATH macro are exhausted.

Environment Variables

LANG provides a default value for the internationalization variables that are unset or null. If LANG is unset or null, the default value of "C" (see lang(5)) is used. If any of the internationalization variables contains an invalid setting, make will behave as if all internationalization variables are set to "C". See environ(5).

LC_ALL If set to a nonempty string value, overrides the values of all the other internationalization variables.

LC_CTYPE determines the interpretation of text as single and/or multi-byte characters, the classification of characters as printable, and the characters matched by character class expressions in regular expressions.

LC_MESSAGES determines the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output.

NLSPATH determines the location of message catalogues for the processing of LC_MESSAGES.

PROJECTDIR provides a directory to be used to search for SCCS files not found in the current directory. In all of the following cases, the search for SCCS files will be made in the directory SCCS in the identified directory. If the value of PROJECTDIR begins with a slash, it is considered an absolute path name; otherwise, the home directory of a user of that name is examined for a subdirectory src or source. If such a directory is found, it is used. Otherwise, the value is used as a relative path name.

If PROJECTDIR is not set or has a null value, the current directory is searched first, followed by a search in the SCCS directory in the current directory. The setting of PROJECTDIR affects all files listed in the remainder of this utility description for files with a component named SCCS.

International Code Set Support

Single and multi-byte character code sets are supported.

NFS Warning

When comparing modification times of files located on different NFS servers, make behaves unpredictably if the clocks on the servers are not synchronized.