[Previous] [Contents] [Next]

make

Maintain, update, and regenerate groups of programs (POSIX)

Syntax:

make [-einpqrst] [-f makefile]... [-k | -S]
     [macro=name...] [target_name...] 

Options:

-e
Cause environment variables to override macro assignments within makefiles.
-f makefile
Use the description file makefile. If the pathname is the dash character (-), the standard input is used. If there are multiple instances of this option, they are processed in the order specified.
-i
Ignore error codes returned by commands. This is equivalent to the special .IGNORE: target.
-k
If a non-ignored error occurs while executing the commands to bring a target up-to-date, abandon work on the current target, but continue with targets that don't depend on the current target. This is the opposite of -S. If both -k and -S are specified, the last one specified is used.
-n
No-execution mode. Print commands, but don't execute them. However, lines preceded by a plus sign (+) prefix or containing the string $(make) are executed. Lines beginning with an @ are printed.
-p
Write to standard output the complete set of macro definitions and target descriptions.
-q
Question mode. The make utility returns a zero or nonzero status code, depending on whether or not the target file is up-to-date. Targets aren't updated if this option is specified.
-r
Clear the suffix list and don't use the default inference rules.
-s
Be silent. Don't print command lines before executing them. This is equivalent to the special .SILENT: target.
-S
Undo the effect of the -k option. Stop processing when a nonzero exit status is returned by a command. If both -k and -S are specified, the last one specified is used. This option overrides the presence of the k flag in the MAKEFLAGS environment variable.
-t
Touch the target files, changing only the file date, rather than performing the rules to reconstruct them.
target_name
The target to bring up-to-date. If no target is specified, make uses the first target defined in the first makefile encountered.
macro=name
Macro definition. This definition remains fixed for the make invocation. It overrides any regular definitions for the specified macro within the makefiles and from the environment. This definition is inherited by subordinate make sessions but acts as an environment variable for these. That is, depending on the -e setting, it may be overridden by a makefile definition.

Description:

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.


Note:

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

Note: 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)


Note: 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.

Signals

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.

Default Rules and Macros

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 and Macros

.SUFFIXES: .o .c .y .l .a .sh

MAKE =     make
AR =       wlib

ARFLAGS =  -b -c
YACC =     yacc
YFLAGS =
LEX =      lex
LFLAGS =
LDFLAGS =
CC =       cc
CFLAGS =   

Single Suffix Rules

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

.sh:
        cp $< $@
        chmod a+x $@

Double Suffix Rules

.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

Inference Rules

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").

Internal Macros

Several dynamically maintained macros are useful as abbreviations within rules. It's best not to define them explicitly.

$*
The basename of the current target.
$<
The name of the current dependency file.
$@
The name of the current target.
$?
The names of prerequisites that are younger than the target.
$%
Evaluated only when the current target is an archive library member of the form libname(member.o). When this is the case, $@ evaluates to libname and $% evaluates to member.o.

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 Definition

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:

  1. macros specified on the command line are added and marked as unchangeable
  2. macros defined in the make "builtin" rules (the default.mk file) are used
  3. the contents of the environment are added to the macro table in the order defined in the environment
  4. macros defined in the explicit makefile(s); multiple makefiles are processed in the order specified

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.

Macro Expansion

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

Makefile Execution

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.


Note: 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."

Makefile Syntax

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."

Recursive Make

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)

Special Macros

MAKEFLAGS
This macro has the set of options provided to make as its value. If this is set as an environment variable, the set of options is processed before any command-line options. This macro may be explicitly passed to nested makes, but it is also available to these invocations as an environment variable. The -f and -d flags aren't recorded in this macro.
$
This macro translates to a dollar sign. Thus you can use $$ in the makefile to represent a single $.

Special Targets

.DEFAULT:
The default is used to process a target when there is no other entry for it, and no implicit rule for building it. The make utility ignores all prerequisites for the default target.
.IGNORE:
Nonzero error codes returned from commands are ignored. Specifying this in a makefile is the same as specifying -i on the command line.
.POSIX
This target must be specified before the first non-comment line in the makefile to instruct the make implementation to interpret the file according to the POSIX behavior documented here.
.PRECIOUS:
Prerequisites of this special target aren't removed if make receives a signal. Subsequent occurrences of .PRECIOUS: add to the list of precious files. There are no commands associated with the .PRECIOUS: special target.
.SILENT:
Commands aren't echoed before they're executed. Specifying this in a makefile is the same as specifying -s on the command line.
.SUFFIXES:
The suffixes list for selecting implicit rules. Specifying this target with prerequisites adds these to the end of the suffixes list. Specifying it with no prerequisites clears the list. To change the order of the suffixes list, you must specify a suffixes target with no prerequisites (clear the list) then specify a suffixes target which specifies the suffixes in the desired order.

Suffix Rules

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.

Targets

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:

@
won't echo the command line, except if -n is used
-
make will ignore the exit code of the command; without this, make terminates when a nonzero exit code is returned
+
make executes the command even if -n was specified

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.

Using makefiles

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.

Examples:

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.

Environment variables:

MAKEFLAGS
This environment variable, if it exists, is read by the make utility, and is treated as a set of option characters to be used as the default options. Command-line options to make have precedence over these options.

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.

SHELL
The value of the SHELL environment variable is always ignored. All other environment variables are used as macros as defined in the section "Macro Definition," above.

Exit status:

When the -q has been specified, the exit status has the following significance:

0
Successful.
1
The target was not up-to-date.
>1
An error occurred.

When the -q has not been specified, exit status is

0
Successful.
>0
An error occurred.

See also:

gmake

Andrew Oram and Steve Talbott, Managing Projects with make, O'Reilly and Associates, 1991.


[Previous] [Contents] [Next]