![[Previous]](../prev.gif) |
![[Contents]](../contents.gif) |
![[Next]](../next.gif) |
|
|
|
Maintain, update, and regenerate groups of programs (POSIX)
make [-einpqrst] [-f makefile]... [-k | -S]
[macro=name...] [target_name...]
The make utility is used to maintain current versions of files by resolving time dependencies. If the file that make is examining (i.e. the target) is older than the file(s) on which it depends (i.e. the prerequisites), then make executes a list of shell commands associated with the target to create or update the target.
 |
This document describes the POSIX-defined behavior of make. Specific make implementations will have extensions, for which you should consult the usage messages and original man page for the version of the utility you are using. To be guaranteed a portable makefile (one that will behave correctly under any POSIX-compliant make implementation), you should restrict the features used to those documented here, and you should put a .POSIX target in as the first non-comment line of the makefile. If this target is not put in, the behavior of make is implementation-defined and none of the information in this document necessarily applies (though typically it will apply regardless of the presence of .POSIX). The make shipped with QNX is currently a port of GNU's make and therefore supports many extensions to the POSIX behavior. The full, original documentation for GNU make is available from the Free Software Foundation. |
To control what make does, the utility references specifications (rules) consisting of a target, prerequisites, and a list of shell commands to be executed when a prerequisite is newer than the target. To simplify maintenance of programs, make has a collection of default macros and inference rules allowing it to identify the proper procedures required to update targets based on minimal information. (If the -r is given the builtin rules will not be used.)
Here's a simple example. Suppose you have a file named myprog.c and you wish to compile it to produce the executable program myprog. To do this, you would simply enter the command:
make myprog
|
This works even in the absence of a makefile. The alternative of using the cc utility would produce an executable named a.out by default. Using make for compiling single-source executables is a convenient shortcut. |
The make utility attempts to perform the actions required to ensure that the specified target(s) are up-to-date. A target is considered out-of-date if it is older than any of its prerequisites. The make utility treats all prerequisites as targets themselves and recursively ensures that they are up-to-date. The utility examines the modified times of files to determine whether they are out-of-date.
After all the prerequisites of a target are ensured to be up-to-date, and if the target is out-of-date, the shell commands associated with the target entry are executed. If no shell commands are listed for the target, it is treated as up-to-date.
The section that follows is an alphabetical reference for make containing these topics: (numbers indicate the suggested order of reading for first-time users of make)
|
If you're a first-time make user, you should read the topics flagged with a number in the order given. By reading these sections, as well as the examples section, you should be able to construct simple, but useful makefiles. The other topics will help you create more powerful, flexible, and easier-to-maintain makefiles. If you're familiar with other make implementations, you should read all the topics in detail in order to use make to its best advantage and to avoid surprises. |
If not already ignored, make traps SIGHUP, SIGTERM, SIGINT, and SIGQUIT and removes the current target unless it is a directory or a prerequisite of the special .PRECIOUS target. After cleaning up, make exits if the signal received was SIGQUIT. Otherwise, make resets the signal handler to the default and sends itself the signal that it received. The default action is taken for all other signals.
The POSIX default inference rules and macros for make consist of the the following:
If a user-supplied makefile redefines any of the default rules or macros, the result is unspecified.
The following briefly outlines the form of macro assignments and rule specifications. For more details, see "Makefile Syntax," "Macros," "Targets," and "Special Targets."
macro=value
target:prerequisite...
shell command
shell command
.
.
.
The set of default rules will have the same effect as if the following rules were present:
.SUFFIXES: .o .c .y .l .a .sh MAKE = make AR = wlib ARFLAGS = -b -c YACC = yacc YFLAGS = LEX = lex LFLAGS = LDFLAGS = CC = cc CFLAGS =
.c:
$(CC) $(CFLAGS) $(LDFLAGS) -o $@ $<
.sh:
cp $< $@
chmod a+x $@
.c.o:
$(CC) $(CFLAGS) -c $<
.y.o:
$(YACC) $(YFLAGS) $<
$(CC) $(CFLAGS) -c y.tab.c
rm -f y.tab.c
mv y.tab.o $@
.l.o:
$(LEX) $(LFLAGS) $<
$(CC) $(CFLAGS) -c lexy.yy.c
rm -f lex.yy.c
mv lex.yy.o $@
.y.c:
$(YACC) $(YFLAGS) $<
mv y.tab.c $@
.l.c:
$(LEX) $(LFLAGS) $<
mv lex.yy.c $@
.c.a:
$(CC) -c $(CFLAGS) $<
$(AR) $(ARFLAGS) $@ $*.o
rm -f $*.o
The make utility uses the suffixes of a target and its prerequisites to infer how a target can be made up-to-date. A list of suffix rules defines the commands to be executed (e.g. cc -c would typically be executed to turn a file ending in a .c suffix into a file ending in a .o suffix). By default, make contains a builtin set of inference rules. Additional rules can be specified in the explicit makefile, or any of the builtin rules can be redefined.
Inference rules are intimately tied to the .SUFFIXES: special target. Each entry in the .SUFFIXES: special target defines a suffix to a filename that may be used to build another file. The inference rules then define how to actually build one file from another. These files are related, in that they must share a common basename, but have different suffixes (e.g. test.c and test.o).
For each of the suffixes specified, make looks for a suffix rule. The suffix rule to update a target with a suffix of .s1 from a prerequisite with a suffix of .s2 is specified as a target .s2.s1.
For example, if the target suffix was .o and the source suffix was .c, the rule .c.o: specifies the command required to create a .o target file from a .c prerequisite.
When no explicit rule is found to update a target, the inference rules are checked. The suffix of the target (.s1) to be built is compared to the list of suffixes specified by the .SUFFIXES special target. If the .s1 suffix exists, the suffix rules are searched in the order defined by the order of suffixes in .SUFFIXES for a .s2.s1 rule. A check is made for the target name $*.s2. If this exists and if the file ending in .s2 is out-of-date with respect to the file ending in .s1, then the commands for the .s2.s1 rule are executed.
If the target to be built doesn't contain a suffix, and there's no rule for the target, the single-suffix rules are checked. The single-suffix rules define how a target is to be built if make finds a target with one of the single suffixes appended. A rule with one suffix (.s2) is the definition of how to build target from target.s2 (e.g. the suffix rule .c: will be used to invoke the commands necessary to compile and link files ending in .c when a C source file is specified without its suffix and no rule is found, as in "make test").
Several dynamically maintained macros are useful as abbreviations within rules. It's best not to define them explicitly.
The $< and $* macros are normally used for inference rules. They may not be reliable when used within explicit target command lines. The internal macros may be suffixed with D and F to specify the Directory and Filename components. For example:
${*D},${@F}
If there is no directory in the name, dot (.) is supplied.
Macro definitions are in the form:
The value of string2 is defined as all characters up to a comment character (#) or a newline character. The newline is ignored when preceded by a backslash (\). An escaped \newline character in the file followed by any white space on the following line will be mapped to a single space.
Subsequent appearances of $(string1) or ${string1} are replaced by string2. See "Macro Expansion" for more details. The parentheses or braces are optional if string1 is a single character. The macro $$ is replaced by the single character $.
Macro assignments come from the sources listed below. If a macro name already exists at the time it is being processed, the newer definition replaces the existing definition unless it is marked as unchangeable. The order is as follows:
If the -e option is present, the last two steps are reversed.
The SHELL macro is treated specially. It is provided by make and is set to the pathname of the Shell command language interpreter (/bin/sh). The SHELL environment variable is always ignored. If SHELL is defined in the explicit makefile or is specified on the command line, then it replaces the original value.
If you have defined a macro as follows:
string1=string2
then subsequent appearances of $(string1) or ${string1} are replaced by string2. If string1 is a single character, the parentheses or braces are optional.
Macros can appear anywhere in the makefile and are evaluated when used. Macros used in targets or prerequisites are evaluated when the makefile is being read. All other macros are evaluated when commands are executed. Macros used within macros are evaluated only when the new macro itself is evaluated. For example:
OBJSALL = $(OBJS1) $(OBJS2)
OBJS1 = a.o b.o c.o
OBJS2 = x.o y.o z.o
$(OBJSALL) will become a.o b.o c.o x.o y.o z.o
The optional form $(string1[:subst1=[subst2]]) can be used to replace all non-overlapping occurrences of subst1 with subst2 when the macro substitution is performed. The occurrence of subst1 must be a suffix at the end of a word in string1. It is as though the sed expression of the following form had been used:
s/\(.*\)subst1\([<blank><newline>]\)/\1subst2\2/g
For example, using the macros defined above, you could create a list of source files (assuming they're all C source files) with the following:
SRCS = $(OBJSALL:o=c)
$(SRCS) will become a.c b.c c.c x.c y.c z.c
Once make has brought all the prerequisites up-to-date, it executes the list of specified shell commands. These commands are processed one line at a time. Command processing is done by writing the command to the standard output (except where noted otherwise) and then executing the command. Commands are executed by passing the command line to the shell in the same manner as the system() function.
The environment for the shell command being executed contains all of the variables in the environment of make. The macros from the command line to make and the MAKEFLAGS variable are added to the environment, overwriting any variable with the same name.
By default, when make receives a nonzero status from the execution of a shell command, it terminates with an error message to standard error.
All errors found while executing the command are ignored if any of the following conditions is true:
The command is not written to standard output before it is executed if any of the following conditions are true:
If the -n option is present, make writes only the command line to standard output and does not execute the command. The only exceptions are if the command prefix contains a plus sign (+) or if the line contains the string $(MAKE).
The -n option is always added to MAKEFLAGS. This allows a recursive make -n target to be used to see all of the actions that would be performed on the target.
If the -k option is present, make terminates processing the commands for the current target if an error occurs executing one of the commands, but continues working on other targets that don't depend on the current target.
|
If the -t option is present, make writes the command line to standard output. But instead of executing the command, make updates the modified time of the target as though touch target had been executed. (See the touch utility.) This can be dangerous when sources are maintained by more than one person. |
For more details on command lines and command prefixes, see "Targets."
The makefile(s) may contain a mixture of comment lines, macro definitions, include lines, and target lines including special targets and suffix rules. Lines may be continued across input lines by escaping the newline with a backslash (\).
Anything after a pound sign (#) is considered a comment and is stripped from the line, including spaces immediately before the #. If the # is inside a quoted string, it isn't treated as a comment. Completely blank lines are ignored.
An include line is used to include the text of another makefile. It consists of the word include with no leading blanks, followed by spaces and by the name of the file to be included at this line. Macros in the name of the file being included are expanded before the file is included. Files that are included may be nested. An example of an include line is:
include my_defaults.mk
For more details on the other different line types, see the following topics: "Targets," "Macros," "Special Targets," and "Suffix Rules."
The make utility has the ability to invoke itself. This can be extremely useful for special circumstances, such as making a library in another directory before linking a program that requires it.
When make is processing commands, if the command prefix contains a plus (+) the command will always be executed, even if the -n option is present. See "Targets" for details.
Here's a commonly seen makefile construct that demonstrates the use of a recursive make:
program: libdir/example.lib
...
libdir/example.lib:
+cd $(@D);$(MAKE) $(@F)
Targets that begin with a period and don't contain any slashes are treated as suffix rules. If there is only one period in the target, it is a single suffix rule. Targets with two periods are double suffix rules.
Suffix rules don't have prerequisites, but do have commands associated with them. See "Inference Rules." For examples of the default rules, see "Default Rules and Macros."
Suffix rules can be redefined or canceled. A target that matches an existing suffix target overwrites the old suffix rule. If no commands are given, the rule is never used.
A target entry in the makefile has the following format:
target... : [prerequisite...] [; command]
tabshell_command
tabshell_command
.
.
.
Any line that doesn't have leading tab (other than macro definitions) is a "target" line. Target lines consist of one or more filenames (or macros that expand into same) called targets, followed by a colon (:). The colon is followed by a list of prerequisite files. The prerequisite list may be terminated with a semicolon (;), which may be followed by a shell command.
A line in a makefile that starts with a tab character is a shell line or rule. This line is associated with the current target entry. A sequence of commands may be associated with a single target entry. Shell lines may have any combination of the following characters to the left of the command as a command prefix:
Only one target rule for any given target may contain commands. However, if the same target is named in multiple target rules, the prerequisites named will be added together to form a complete prerequisite list.
The prerequisites are those from which a target is constructed. They in turn may be targets of other prerequisites. In general, for a particular target file, each of its prerequisite files is "made" to ensure that each is up-to-date with respect to its prerequisites.
The modification time of the target is compared to the modification time of each prerequisite file. If the target is older than the prerequisite, then one or more of the prerequisites have changed, and the target must be constructed. This checking is done recursively, so that all prerequisites of prerequisites of prerequisites ad infinitum are up-to-date.
To reconstruct a target, make expands macros, strips off initial white space, and passes each rule to a shell for execution.
For target lines, macros are expanded as the makefile is read. Command lines have macro expansion delayed until the line is to be executed.
The make utility comes with a set of builtin macro definitions and rules. If the -r option is specified, the "builtin" rules aren't used and the suffix list is cleared.
You can specify additional rules in a user-specified makefile. Targets, rules, and macros of the same name are overwritten by the user-specified file. By default, the ./makefile file is used. If ./makefile isn't found, the file ./Makefile is then tried.
The -f option directs make to ignore ./makefile and ./Makefile and use the specified argument as a makefile instead. If the - argument is specified, standard input is used. More than one additional makefile can be used by specifying multiple -f options. Using -f multiple times performs a concatenation of all the makefiles in a left-to-right order.
See "Makefile Syntax" for more details.
make test.o
Typing this in the absence of a makefile (or with a makefile that doesn't mention the test.o file) will use the builtin suffixes list and inference rules to determine the name of the source file and, if necessary, to run the proper command to create or rebuild the test.o file.
Suppose you have the source files test1.c, test2.c, and test3.c. The first two files include the headers <hdr1.h> and <hdr2.h>, and these files are all linked together to produce the program myprog. Here's what a simple makefile describing this could look like:
# Samplemakefile1
myprog: test1.o test2.o test3.o
test1.o: hdr1.h hdr2.h
test2.o: hdr1.h hdr2.h
test3.o:
You could compile and link myprog by entering:
make myprog
Or since myprog is the first target, you could simply enter:
make
If you wanted to see what commands need to be executed without actually executing them, you could type:
make -n
Using macros, the myprog makefile could be simplified to:
# Samplemakefile2
OBJS=test1.o test2.o test3.o
HDRS=hdr1.h hdr2.h
myprog: $(OBJS)
test1.o: $(HDRS)
test2.o: $(HDRS)
This makefile is functionally identical to the previous example. It's not significantly better, just slightly more generalized.
We can further simplify the makefile by using the builtin inference rules and macros, as follows:
# Samplemakefile3
OBJS=test1.o test2.o test3.o
HDRS=hdr1.h hdr2.h
myprog: $(OBJS)
test1.o test2.o: $(HDRS)
As you can see, this makefile is short and to-the-point. Again, this is functionally equivalent to the previous examples.
Using this makefile, you can customize the compilation from the make command line by setting the appropriate macros:
make CFLAGS=-Oaxt
which increases the optimization level of the compile.
You can also direct the linker to produce a linkmap:
make LDFLAGS=-M
Of course, any of these macro assignments could be "hard-coded" in the makefile, but it's often convenient to override the defaults from the command line for special needs.
After make has started and the MAKEFLAGS variable has been read, all of the options except -d, -f, and -p are added to the MAKEFLAGS macro. The MAKEFLAGS macro is passed into the environment as an environment variable for all child processes.
When the -q has been specified, the exit status has the following significance:
When the -q has not been specified, exit status is
Andrew Oram and Steve Talbott, Managing Projects with make, O'Reilly and Associates, 1991.
|
|
|