make - Maintain program-generated and interdependent files

Description

make helps you manage projects containing a set of interdependent files, such as a program with many source and object files, or a document built from source files, macro files, and so on. make keeps all such files up-to-date with one another. If one file changes, make updates all the other files that depend on the changed file.

In a double-byte locale, environment variable values, here-documents, and the command line can all contain environment values.

Options

-c dir

Attempts to change into the specified directory when make starts up. If make cannot change to the directory, an error message is printed. This option is useful for recursive makefiles when you are building in a different directory.

-D macro definition

Define macro on the command line before reading any makefile. Use the same form as a normal macro definition (macro=string). If you use this option, make assigns the value to the macro before reading the makefile; any definition of the same macro contained in the makefile supersedes this definition.

Note: make uses any macros defined in this way before reading any makefile, including the startup file. This allows you to define a startup file by providing a value for MAKESTARTUP on the command line:

make -D MAKESTARTUP=$HOME/project/startup.mk

-E

Suppresses reading of the environment. If you do not specify either -E or -e, make reads the environment before reading the makefile.

-e

Reads the environment after reading the makefile. If neither -E nor -e are specified, make reads the environment before reading the makefile, except for the SHELL environment variable, which you must explicitly export. This option does not affect the value of MAKEFLAGS.

-f file

Uses file as the source for the makefile description. make ignores the makefiles specified as prerequisites to the .MAKEFILES target. If you specify a minus sign (-) in place of file, make reads the standard input. (In other words, make expects you to enter the makefile from the terminal or to redirect it from a file.) You can use more than one -f option.

-i

Tells make to ignore all errors and continue making other targets. This is equivalent to the .IGNORE attribute or macro.

-k

Makes all independent targets, even if an error occurs. Ordinarily, make stops after a command returns a nonzero status. Specifying -k tells make to ignore the error and continue to make other targets, as long as they are not related to the target that received the error. make does not attempt to update anything that depends on the target that was being made when the error occurred.

-n

Displays the commands that make would execute to update the chosen targets, but does not actually execute any recipe lines unless they have a plus sign (+) command prefix. make displays recipe lines with an at sign (@) command prefix on standard output (stdout). For more information about recipe lines, see Recipe lines in z/OS UNIX System Services Programming Tools.

With group recipes, make displays the commands that it uses to update a given target, but it also executes the commands.

Note: z/OS make supports group recipes, but traditional implementations of make do not. A group recipe signifies a collection of command lines fed as a unit to the command interpreter. By contrast, make executes commands in a normal recipe one by one. For more information about group recipes, see Group recipes in z/OS UNIX System Services Programming Tools.

If make finds the string $ (MAKE) in a recipe line, it expands it, adds -n to the MAKEFLAGS, and then executes the recipe line. This enables you to see what happens when recursive calls are made to make. The output correctly shows line breaks in recipes that are divided into several lines of text using the \<newline> sequence.

-p

Prints the makefile after it has been processed to include macro and target definitions. This display is in human-readable form useful for debugging, but you cannot use it as input to make.

-q

Checks whether the target is up-to-date. If it is up-to-date, make exits with a status of 0; otherwise, it exits with a status of 1 (typically interpreted as an error by other software). No commands are run when -q is specified.

-r

Does not read the startup file. Various control macros and default rules will not be defined.

-S

Ends make if an error occurs during operations to bring a target up-to-date (opposite of -k). This is the default.

-s

Specifies that recipe commands, warning messages, or touch messages (see the -t option) not be displayed. This is equivalent to the .SILENT attribute or macro.

-t

Touches the target to mark them as up-to-date, but only executes commands to change a target if the target has a plus sign (+) command prefix. make does not touch up-to-date targets or targets that have prerequisites but not recipes. make displays a message for each touched target file indicating the file name.

-u

Forces an unconditional update: make behaves as if all the prerequisites of the given target are out of date.

-V

Prints the version number of make and a list of built-in rules.

-v

Causes make to display a detailed account of its progress. This includes what files it reads, the definition and redefinition of each macro, metarule and suffix rule searches, and other information.

-x

Exports all macro definitions to the environment. This happens just before make begins making targets (but after it has read the entire makefile).

Targets

A target is normally a file that you want to ensure is up-to-date with the files on which it is dependent (the prerequisites). For example, you might want to check to see if a is based on the most recent version of the corresponding source code. If it is not, then have the source code recompiled to get an up-to-date version. In this case, the compiled program file is the target and the corresponding source files are prerequisites (that is, the files on which a target is dependent).

make updates all targets that are specified on the command line. If you do not specify any target, make updates the targets in the first rule of the makefile. A target is out of date if it is older than any of its prerequisites (based on modification times) or if it does not exist. To update a target, make first recursively ensures that all the target's prerequisites are up-to-date, processing them in the order in which they appear in the rule. If the target itself is out of date, make then runs the recipe that is associated with the target. If the target has no associated recipe, make considers up-to-date.

make also supports another form of targets, known as special targets.

Special target directives are called targets because they appear in the target position of rules; however, they are really keywords, not targets. The rules they appear in are really directives that control the behavior of make.

The special target must be the only target in a special rule; you cannot list other normal or special targets.

A name of the form library(member) indicates a member of a library. The library portion is a target with the .LIBRARY attribute, and the member portion is a prerequisite of the library target.

A name of the form library((entry)) indicates the library module that contains the given entry point. Once again, the library portion is a target with the .LIBRARY attribute. make regards the library member that contains the entry point entry as a prerequisite of the library target.

Makefiles

A makefile is a text file that describes the dependencies between various files. It normally contains a list of targets and identifies the prerequisites on which each depends. It also contains a series of instructions, called recipes, which describe the actions to be taken if a given target is out of date with its prerequisites.

By default, if you do not specify the -f option, make looks for a file in your current directory named makefile. If it does not find this file, it searches your current directory for a file named Makefile. If make finds either file, it uses this file as your makefile.

You can change the default makefiles with the .MAKEFILES special target. This target is already specified in the startup.mk file. See Targets for more information.

Makefile contents

Comments begin with the pound (#) character and extend to the end of the line. make discards all comment text.

Inside makefiles, you can split long lines over several lines of text. To do this, put a backslash (\) at the very end of the line. You can use this technique to extend comments as well as recipe lines and macro definitions, for example.

If a rule or macro definition must contain a # character, use \#; otherwise, make mistakes the # for the beginning of a comment. Also, if a macro definition must contain a single $ character, use $$.

"a:target" : "a:prereq"

to

Group recipes begin with [ in the first non-white-space position of a line, and end with ] in the first non-white-space position of a line. Recipe lines in a group recipe need not have a leading tab. make executes a group recipe by feeding it as a single unit to a shell. If you immediately follow the [ at the beginning of a group recipe with one of -, @ or +, they apply to the entire group in the same way that they apply to single recipe lines.

Macro definitions

Macro definitions can appear on the command line or in makefiles. Macro definitions on the command line overrule definitions in makefiles; makefile definitions never overrule command-line definitions. Macro definitions on the command line may not have any white space between the macro name and the = character.

macro := string

macro += string

You can use any amount of white space on both sides of macro operators. make defines the name macro to have the value string and replaces it with that value whenever it is used as $(macro) or ${macro} within the makefile. It is possible to specify a $(macro_name) or ${macro_name} macro expansion, where macro_name contains more $(....) or ${...} macro expansions itself.

Typically, make does not include white space at the beginning and end of string in the definition of macro; however, it never strips white space from macros imported from the environment.

If you want to include white space in a macro definition specified on the make command line, you must enclose the definition in quotes.

make resolves macro definitions in the following order:

1. Macro definitions in the built-in rules.
2. Macro definitions on the command line associated with the -D option.
3. Macro definitions in the startup file.
4. Contents of the environment.
5. Macro definitions in the makefiles (in the order they appear).
6. Macro definitions on the command line without the -D option.

If you specify the -e options, make reads the makefiles before reading the contents of the environment. If you specify the -E option, make does not read the contents of the environment.

If a macro is already defined when make encounters a new definition for it, the new definition replaces the old one. For example, a macro definition for name on the command line overrides a definition for name in the makefile. You can use the -v option to display macro assignments, as make performs them.

$(macro_name:modifier_list:modifier_list:...)

test = D1/D2/d3/a.out f.out d1/k.out

fred : $$@.c
fred : fred.c

fred.o : $$(@:b).c

The runtime macros can be modified by the letters D and F to indicate only the directory portion of the target name or only the file portion of the target name. (The working directory is represented by a dot.) If define.h is the only prerequisite that is newer than the target, the macros $?D and $?F expand to dot ( .) and to define.h.

If you are building a library, $$% stands for the name of the archive member being made. If you are building a normal target, $$% stands for the name of the target currently being made.

$$* stands for the name of the current target being made, but with no suffix.

If you are building a library, $$> stands for the name of the archive library being made. If you are not building a library, $$> is not valid.

Rules

targets [attributes] ruleop [prerequisites]
[;recipe]
{<tab> recipe}

Circular dependencies

There are two types of circular dependencies: within-rule and between-rule.

c.o : a.o b.o c.o

a.o : b:o
b:o : a.o

Typically, make only detects circular dependencies for those targets actually being built. When a circular dependency is encountered, make issues a warning message, removes the offending prerequisite from the list, and continues parsing the makefile. You can use the .CYCLECHECK special target to alter. make's treatment of circular dependencies.

Inference rules

With inference rules you can specify general rules for building files rather than creating a specific rule for each target.

make provides two forms of inference rules: suffix rules and metarules. It includes suffix rules to ensure compatibility with older makefiles. Metarules, however, provide a more general mechanism for specifying make's default behavior. They provide a superset of the functionality of suffix rules.

make searches all metarules before using suffix rules.

make uses the inference rules to infer how it can bring a target up-to-date. A list of inference rules defines the commands to be run. The default startup.mk file contains a set of inference rules for the most common targets. You can specify additional rules in the makefile.

When make finds no explicit target rule to update a target, it checks the inference rules. If make finds an applicable inference rule with an out-of-date prerequisite, it runs on that rule's recipe. See Targets for information about the .DEFAULT special target).

Transitive closure

Metarules provide a mechanism that allows several metarules to chain together to eventually create the target. This mechanism is called transitive closure. For example, if you have metarules:

%.o : %.c
        ... rule body...

%.c : %.y
        ... rule body ...

make file.o

make uses the first metarule to look for file.c. If it can't find an explicit rule to build file.c, it again looks through the metarules and finds the rule that tells it to look for file.y.

% : %.c
        ... rule body ...

make file

causes make to look for file.c. If the metarules were not restricted and file.c did not exist, then make would look for file.c.c, and then file.c.c.c, and so on. Because each metarule is applied only once, this can't happen.)

% : %.o
        recipe 1...
%.o : %c
        recipe 2... 

% : %.c
   recipe 2...   recipe from .REMOVE target for %.o, if not .PRECIOUS
   recipe 1...

The best way to understand how this works is to experiment with little make files with the -v flag specified. This shows you in detail what rules are being searched, when transitive closure is calculated, and what rules are added.

Order of rule generation

Since transitive closure allows make to generate new rules, it is important to understand the order in which this is done:

1. make searches for explicit rules in the order in which they appear, so explicit rules always take precedence.
2. make reads metarules in the order in which they appear in the makefile. The first rule that appears in the makefile is the first one checked.
3. New explicit metarules (as distinct from metarules generated by transitive closure) replace old ones. In other words, if your makefile contains an explicit rule like this one, it replaces the default rule in startup.mk:

   %$O : %.c
           rule1

   If you use the -v option, make prints a warning when it replaces a metarule.
4. When transitive closure is calculated, the new metarules generated are added to the end of the list of possible metarules. Thus, make always finds the explicit rules first, so they take precedence over generated rules. You can use the -v option to see what rules make generates and the order in which they appear.
5. make performs two passes through the rules. On the first pass it tries to find a match with an explicit rule in the makefile; if this does not succeed, make performs a second pass to find a match with an existing file.

Suffix rules

make treats targets that begin with a period and contain no slashes or percent signs as suffix rules. If there is only one period in the target, it is a single suffix inference rule. Targets with two periods are double-suffix inference rules. Suffix rules do not have prerequisites but do have commands associated with them.

When make finds no explicit rule to update a target, it checks the suffix of the target (.s1) to be built against the suffix rules. make examines a prerequisite based on the basename of the target with the second suffix (.s2) appended, and if the target is out of date with respect to this prerequisite, make runs the recipe for that inference rule.

Metarules take precedence over suffix rules.

If the target to be built does not contain a suffix and there is no rule for the target, make checks the single suffix inference rules. The single suffix inference rules define how to build a target if make finds a rule with one of the single suffixes appended. A rule with one suffix .s2 defines how to build target from target.s2. make treats the other suffix (.s1) as null.

.SUFFIXES:

The search algorithm used for suffix rules depends on whether the .POSIX special target is specified. When .POSIX is specified, the following steps describe the search algorithm for suffix rules:

1. Extract the suffix from the target. If that target does not have a suffix, go to step 6.
2. Is it in the .SUFFIXES list? If not, quit the search.
3. If it is in the .SUFFIXES list, look for a double suffix rule that matches the target suffix.
4. If there is a match, extract the base name of the file, add on the second suffix, and determine if the resulting file exists. If the resulting file does not exist, keep searching the double suffix rules.

   If the resulting file does exist, use the recipe for this rule.

5. If a successful match is not made, the inference has failed.
6. If the target did not have a suffix, check the single suffix rules in the order that the suffixes are specified in the .SUFFIXES target.
7. For each single suffix rule, add the suffix to the target name and determine if the resulting file name exists.
8. If the file name exists, execute the recipe that is associated with that suffix rule. If the file name doesn't exist, continue trying the rest of the single suffix rules. If a successful match is not made, the inference has failed.

When the .POSIX special target is not specified, make handles suffix rules in the same manner as traditional implementations of make. The following steps describe the search algorithm for suffix rules in this situation.

1. Extract the suffix from the target. If that target does not have a suffix, go to step 8.
2. Is it in the .SUFFIXES list? If not, then quit the search.
3. If it is in the .SUFFIXES list, look for a double suffix rule that matches the target suffix.
4. If you find one, then extract the base name of the file, add on the second suffix and see if the resulting file exists. If it does, go to step 7. If not, continue with step 5.
5. Is there an inference rule for the resulting file? If yes, run the recipe that is associated with that rule (which should describe how to make the file exist) and go to step 7.
6. Search for the next double-suffix rule that matches the target suffix and return to step 4. If the double-suffix rules are exhausted, then the inference has failed.
7. Use the recipe for the target rule.
8. If the target did not have a suffix, then check the single-suffix rules in the order that the suffixes are specified in the .SUFFIXES target.
9. For each single-suffix rule, add the suffix to the target name and see if the resulting file name exists.
10. If the file exists, then run the recipe that is associated with that suffix rule. If it doesn't exist, continue trying the rest of the single-suffix rules.
11. If a successful match is not made, then the inference has failed.

.suf.a:
         recipe

.SUFFIXES:  .a .c
     echo adding $< to library $@

make "mylib(mem.o)"

adding mem.o to library mylib

Attributes

attribute_list : targets

targets attribute_list : prerequisites

Control macros

make defines a number of control macros that control make's behavior. When there are several ways of doing the same thing, control macros are usually the best. A control macro that has the same function as a special target or attribute also has the same name.

Macros that are said to be defined internally are automatically created by make and can be used with the usual $(name) construct. For example, $(PWD) can be used to obtain the current directory name.

Making libraries

A library is a file containing a collection of object files. To make a library, you specify it as a target with the .LIBRARY attribute and list its prerequisites. The prerequisites should be the object members that are to go into the library.

make tries to handle the old library construct format in a sensible way. When it finds lib(member), it declares the lib portion as a target with the .LIBRARY attribute and the member portion as a prerequisite of the lib target. To make the library properly, old makefile scripts using this format must name the lib as a target and must try to bring it up-to-date. The same thing happens for any target of the form lib((entry)). These targets have an additional feature in that the entry target has the .SYMBOL attribute set automatically.

Conditional expressions

.IF expression
...
 if text ...
.ELSE
... else text ...
.END

.IF expression
... if text ...
.ELSIF expression2
... else if text ...
.ELSE
... else text ...
.END

string

string == string

string != string

The text enclosed in the conditional construct must have the same format that it would have outside the conditional. In particular, make assumes that anything that starts with a tab inside the conditional is a recipe line. This means that you cannot use tabs to indent text inside the conditional (except, of course, for recipe lines, which always begin with tabs).

Files

Environment variables

Localization

Exit values

Usage notes

1. The length of a single makefile script line cannot exceed 32768 characters.
2. The length of an argument string cannot exceed 32768 characters.
3. The length of a macro name is truncated after 256 characters.
4. When the .SETDIR special target is used, make checks the file attributes of targets and prerequisites on every pass through a rule. This can significantly increase the number of system accesses.
5. In a double-byte environment, any character interpreted by make can be a double-byte character, including those in macro definitions and targets.
6. In a double-byte locale, if make encounters an incorrect double-byte sequence, it ends with an error message.

Portability

POSIX.2, X/Open Portability Guide, UNIX systems.

Related information

c89, cc, c++, makedepend

S. I. Feldman, Make - Program for Maintaining Computer Programs, Software-Practice and Experience 9 (no. 4, April 1979):225-65 [Bell Labs, Murray Hill, NJ]