Reading Makefiles and the Environment

Next, make reads in a default makefile that typically contains predefined macro definitions, target entries for implicit rules, and additional rules, such as the rule for retrieving SCCS files. If present, make uses the file make.rules in the current directory; otherwise it reads the file /usr/share/lib/make/make.rules, which contains the standard definitions and rules. Use the directive:

in your local make.rules file to include them.

Next, make imports variables from the environment (unless the -e option is in effect), and treats them as defined macros. Because make uses the most recent definition it encounters, a macro definition in the makefile normally overrides an environment variable of the same name. When -e is in effect, however, environment variables are read in after all makefiles have been read. In that case, the environment variables take precedence over definitions in the makefile.

Next, make reads any makefiles you specify with -f, or one of makefile or Makefile as described above and then the state file, in the local directory if it exists. If the makefile contains a .KEEP_STATE_FILE target, then it reads the state file that follows the target. Refer to special target .KEEP_STATE_FILE for details.

Next (after reading the environment if -e is in effect), make reads in any macro definitions supplied as command line arguments. These override macro definitions in the makefile and the environment both, but only for the make command itself.

make exports environment variables, using the most recently defined value. Macro definitions supplied on the command line are not normally exported, unless the macro is also an environment variable.

make does not export macros defined in the makefile. If an environment variable is set, and a macro with the same name is defined on the command line, make exports its value as defined on the command line. Unless -e is in effect, macro definitions within the makefile take precedence over those imported from the environment.

The macros MAKEFLAGS, MAKE, SHELL, HOST_ARCH, HOST_MACH, and TARGET_MACH are special cases. See Special-Purpose Macros below for details.

Makefile Target Entries

The first line contains the name of a target, or a space-separated list of target names, terminated with a colon or double colon. If a list of targets is given, this is equivalent to having a separate entry of the same form for each target. The colon(s) can be followed by a dependency, or a dependency list. make checks this list before building the target. The dependency list can be terminated with a semicolon ( ;), which in turn can be followed by a single Bourne shell command. Subsequent lines in the target entry begin with a TAB and contain Bourne shell commands. These commands comprise the rule for building the target.

Shell commands can be continued across input lines by escaping the NEWLINE with a backslash (\). The continuing line must also start with a TAB.

To rebuild a target, make expands macros, strips off initial TAB characters and either executes the command directly (if it contains no shell metacharacters), or passes each command line to a Bourne shell for execution.

The first non-empty line that does not begin with a TAB or # begins another target or macro definition.

Special Characters

Global

Targets and Dependencies

Macros

Rules

Special-Function Targets

Clearing Special Targets

.DEFAULT, .SCCS_GET, and .SUFFIXES

Command Dependencies

Hidden Dependencies

Macros

define macros. macro is the name of the macro, and value, which consists of all characters up to a comment character or unescaped NEWLINE, is the value. make strips both leading and trailing white space in accepting the value.

Subsequent references to the macro, of the forms: $(name) or ${name} are replaced by value. The parentheses or brackets can be omitted in a reference to a macro with a single-character name.

Macro references can contain references to other macros, in which case nested references are expanded first.

Suffix Replacement Macro References

where string1 is either a suffix, or a word to be replaced in the macro definition, and string2 is the replacement suffix or word. Words in a macro value are separated by SPACE, TAB, and escaped NEWLINE characters.

Pattern Replacement Macro References

where op is the existing (old) prefix and os is the existing (old) suffix, np and ns are the new prefix and new suffix, respectively, and the pattern matched by % (a string of zero or more characters), is carried forward from the value being replaced. For example:

sets the value of DEBUG to tmp/fabricate−g.

Notice that pattern replacement macro references cannot be used in the dependency list of a pattern matching rule; the % characters are not evaluated independently. Also, any number of % metacharacters can appear after the equal-sign.

Appending to a Macro

Special-Purpose Macros

Notice that flags passed by way of MAKEFLAGS are only displayed when the -d, or -dd options are in effect.

The MAKE macro is another special case. It has the value make by default, and temporarily overrides the -n option for any line in which it is referred to. This allows nested invocations of make written as:

to run recursively, with the -n flag in effect for all commands but make. This lets you use make -n to test an entire hierarchy of makefiles.

For compatibility with the 4.2 BSD make, the MFLAGS macro is set from the MAKEFLAGS variable by prepending a -. MFLAGS is not exported automatically.

The SHELL macro, when set to a single-word value such as /usr/bin/csh, indicates the name of an alternate shell to use. The default is /bin/sh. Notice that make executes commands that contain no shell metacharacters itself. Built-in commands, such as dirs in the C shell, are not recognized unless the command line includes a metacharacter (for instance, a semicolon). This macro is neither imported from, nor exported to the environment, regardless of -e. To be sure it is set properly, you must define this macro within every makefile that requires it.

The syntax of the VPATH macro is:

VPATH specifies a list of directories to search for the files, which are targets or dependencies, when make is executed. VPATH is also used in order to search for the include files mentioned in the particular makefile.

When processing a target or a dependency or an include directive, make checks the existence of the file with the same name in the current directory. If the file is found to be missing, make searches for this file in the list of directories presented in VPATH (like the PATH variable in the shell). Unlike the PATH variable, VPATH is used in order to search for the files with relative pathnames. When make attempts to apply implicit rules to the target, it also searches for the dependency files using VPATH.

When the file is found using VPATH, internal macros $@, @<, $?, $*, and their alternative forms (with D or F appended) are set in accordance with the name derived from VPATH. For instance, if the target subdir/foo.o is found in the directory /aaa/bbb using VPATH, then the value of the internal macro $@ for this target is /aaa/bbb/subdir/foo.o.

If a target or a dependency file is found using VPATH, then any occurrences of the word that is the same as the target name in the subsequent rules are replaced with the actual name of the target derived from VPATH.

For example:

If file.c is found in ./subdir, then the command

are executed.

The following macros are provided for use with cross-compilation:

Dynamic Macros

To refer to the $@ dynamic macro within a dependency list, precede the reference with an additional $ character (as in, $$@). Because make assigns $< and $* as it would for implicit rules (according to the suffixes list and the directory contents), they can be unreliable when used within explicit target entries.

These macros can be modified to apply either to the filename part, or the directory part of the strings they stand for, by adding an upper case F or D, respectively (and enclosing the resulting name in parentheses or braces). Thus, $(@D) refers to the directory part of the string $@; if there is no directory part, . is assigned. $(@F) refers to the filename part.

Conditional Macro Definitions

indicates that when processing any of the targets listed and their dependencies, macro is to be set to the value supplied. Notice that if a conditional macro is referred to in a dependency list, the $ must be delayed (use $$ instead). Also, target-list can contain a % pattern, in which case the macro is conditionally defined for all targets encountered that match the pattern. A pattern replacement reference can be used within the value.

You can temporarily append to a macros value with a conditional definition of the form:

Predefined Macros

Implicit Rules

Pattern Matching Rules

is a pattern matching rule, in which tp is a target prefix, ts is a target suffix, dp is a dependency prefix, and ds is a dependency suffix (any of which can be null). The % stands for a basename of zero or more characters that is matched in the target, and is used to construct the name of a dependency. When make encounters a match in its search for an implicit rule, it uses the rule in that target entry to build the target from the dependency file. Pattern-matching implicit rules typically make use of the $@ and $< dynamic macros as placeholders for the target and dependency names. Other, regular dependencies can occur in the dependency list; however, none of the regular dependencies can contain %. An entry of the form:

is a valid pattern matching rule.

Suffix Rules

The target entry for a suffix rule takes the form:

where Ts is the suffix of the target, Ds is the suffix of the dependency file, and rule is the rule for building a target in the class. Both Ds and Ts must appear in the suffixes list. (A suffix need not begin with a . to be recognized.)

A suffix rule with only one suffix describes how to build a target having a null (or no) suffix from a dependency file with the indicated suffix. For instance, the .c rule could be used to build an executable program named file from a C source file named file.c. If a target with a null suffix has an explicit dependency, make omits the search for a suffix rule.

make reads in the standard set of implicit rules from the file /usr/share/lib/make/make.rules, unless -r is in effect, or there is a make.rules file in the local directory that does not include that file.

The Suffixes List

A tilde (~) indicates that if a dependency file with the indicated suffix (minus the ~) is under SCCS its most recent version should be retrieved, if necessary, before the target is processed.

Library Maintenance

refers to a member, or a space-separated list of members, in an ar(1) library.

The dependency of the library member on the corresponding file must be given as an explicit entry in the makefile. This can be handled by a pattern matching rule of the form:

where .s is the suffix of the member; this suffix is typically .o for object libraries.

A target name of the form:

refers to the member of a randomized object library that defines the entry point named symbol.

Command Execution

make invokes the shell with the -e (exit-on-errors) argument. Thus, with semicolon-separated command sequences, execution of the later commands depends on the success of the former. This behavior can be overridden by starting the command line with a -, or by writing a shell script that returns a non-zero status only as it finds appropriate.

Bourne Shell Constructs

Although composed of several input lines, the escaped NEWLINE characters insure that make treats them all as one (shell) command line.

To use the Bourne shell for control structure for loops, use a command line of the form:

To refer to a shell variable, use a double-dollar-sign ($$). This prevents expansion of the dollar-sign by make.

Command Substitutions

The command is executed only once, standard error output is discarded, and NEWLINE characters are replaced with SPACEs. If the command has a non-zero exit status, make halts with an error.

To capture the output of a shell command in a macro reference, use a reference of the form:

where MACRO is the name of a macro containing a valid Bourne shell command line. In this case, the command is executed whenever the reference is evaluated. As with shell command substitutions, the reference is replaced with the standard output of the command. If the command has a non-zero exit status, make halts with an error.

In contrast to commands in rules, the command is not subject for macro substitution; therefore, a dollar sign ( $) need not be replaced with a double dollar sign ( $$).

Signals

/usr/xpg4/bin/make