Do not remake the file file even if it is older than its prerequisites, and do not remake anything on account of changes in file. Essentially the file is treated as very old and its rules are ignored. See Avoiding Recompilation of Some Files.
Ensure that the complete output from each recipe is printed in one
uninterrupted sequence. This option is only useful when using the
--jobs
option to run multiple recipes simultaneously
(see Parallel Execution) Without this option output
will be displayed as it is generated by the recipes.
With no type or the type ‘target’, output from the entire recipe of each target is grouped together. With the type ‘line’, output from each line in the recipe is grouped together. With the type ‘recurse’, the output from an entire recursive make is grouped together. With the type ‘none’, no output synchronization is performed. See Output During Parallel Execution.
Print the data base (rules and variable values) that results from reading the makefiles; then execute as usual or as otherwise specified. This also prints the version information given by the ‘-v’ switch (see below). To print the data base without trying to remake any files, use ‘make -qp’. To print the data base of predefined rules and variables, use ‘make -p -f /dev/null’. The data base output contains file name and line number information for recipe and variable definitions, so it can be a useful debugging tool in complex environments.
“Question mode”. Do not run any recipes, or print anything; just return an exit status that is zero if the specified targets are already up to date, one if any remaking is required, or two if an error is encountered. See Instead of Executing Recipes.
Eliminate use of the built-in implicit rules (see Using Implicit Rules). You can still define your own by writing
pattern rules (see Defining and Redefining Pattern
Rules). The ‘-r’ option also clears out the default list of
suffixes for suffix rules (see Old-Fashioned Suffix
Rules). But you can still define your own suffixes with a rule for
.SUFFIXES
, and then define your own suffix rules. Note that only
rules are affected by the -r
option; default variables
remain in effect (see Variables Used by Implicit
Rules); see the ‘-R’ option below.
Eliminate use of the built-in rule-specific variables (see Variables Used by Implicit Rules). You can still define your own, of course. The ‘-R’ option also automatically enables the ‘-r’ option (see above), since it doesn’t make sense to have implicit rules without any definitions for the variables that they use.
Silent operation; do not print the recipes as they are executed. See Recipe Echoing.
Cancel the effect of the ‘-k’ option. This is never necessary
except in a recursive make
where ‘-k’ might be inherited
from the top-level make
via MAKEFLAGS
(see Recursive Use of make
)
or if you set ‘-k’ in MAKEFLAGS
in your environment.
Touch files (mark them up to date without really changing them)
instead of running their recipes. This is used to pretend that the
recipes were done, in order to fool future invocations of
make
. See Instead of Executing Recipes.
Show tracing information for make
execution. Prints the entire
recipe to be executed, even for recipes that are normally silent (due
to .SILENT
or ‘@’). Also prints the makefile name and
line number where the recipe was defined, and information on why the
target is being rebuilt.
Print the version of the make
program plus a copyright, a list
of authors, and a notice that there is no warranty; then exit.
Print a message containing the working directory both before and after
executing the makefile. This may be useful for tracking down errors
from complicated nests of recursive make
commands.
See Recursive Use of make
. (In practice, you
rarely need to specify this option since ‘make’ does it for you;
see The ‘--print-directory’ Option.)
Disable printing of the working directory under -w
.
This option is useful when -w
is turned on automatically,
but you do not want to see the extra messages.
See The ‘--print-directory’ Option.
Pretend that the target file has just been modified. When used
with the ‘-n’ flag, this shows you what would happen if you were
to modify that file. Without ‘-n’, it is almost the same as
running a touch
command on the given file before running
make
, except that the modification time is changed only in the
imagination of make
.
See Instead of Executing Recipes.
Issue a warning message whenever make
sees a reference to an
undefined variable. This can be helpful when you are trying to debug
makefiles which use variables in complex ways.
Certain standard ways of remaking target files are used very often. For
example, one customary way to make an object file is from a C source file
using the C compiler, cc
.
Implicit rules tell make
how to use customary techniques so
that you do not have to specify them in detail when you want to use
them. For example, there is an implicit rule for C compilation. File
names determine which implicit rules are run. For example, C
compilation typically takes a .c file and makes a .o file.
So make
applies the implicit rule for C compilation when it sees
this combination of file name endings.
A chain of implicit rules can apply in sequence; for example, make
will remake a .o file from a .y file by way of a .c file.
The built-in implicit rules use several variables in their recipes so
that, by changing the values of the variables, you can change the way the
implicit rule works. For example, the variable CFLAGS
controls the
flags given to the C compiler by the implicit rule for C compilation.
You can define your own implicit rules by writing pattern rules.
Suffix rules are a more limited way to define implicit rules. Pattern rules are more general and clearer, but suffix rules are retained for compatibility.
| • Using Implicit: | How to use an existing implicit rule to get the recipes for updating a file. | |
| • Catalogue of Rules: | A list of built-in rules. | |
| • Implicit Variables: | How to change what predefined rules do. | |
| • Chained Rules: | How to use a chain of implicit rules. | |
| • Pattern Rules: | How to define new implicit rules. | |
| • Last Resort: | How to define a recipe for rules which cannot find any. | |
| • Suffix Rules: | The old-fashioned style of implicit rule. | |
| • Implicit Rule Search: | The precise algorithm for applying implicit rules. |
Next: Catalogue of Rules, Previous: Implicit Rules, Up: Implicit Rules [Contents][Index]
To allow make
to find a customary method for updating a target
file, all you have to do is refrain from specifying recipes yourself.

Then make
will figure out which implicit rule to use based on
which kind of source file exists or can be made.
For example, suppose the makefile looks like this:
foo : foo.o bar.o cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS)
Because you mention foo.o but do not give a rule for it, make
will automatically look for an implicit rule that tells how to update it.
This happens whether or not the file foo.o currently exists.
If an implicit rule is found, it can supply both a recipe and one or more prerequisites (the source files). You would want to write a rule for foo.o with no recipe if you need to specify additional prerequisites, such as header files, that the implicit rule cannot supply.
Each implicit rule has a target pattern and prerequisite patterns. There may
be many implicit rules with the same target pattern. For example, numerous
rules make ‘.o’ files: one, from a ‘.c’ file with the C compiler;
another, from a ‘.p’ file with the Pascal compiler; and so on. The rule
that actually applies is the one whose prerequisites exist or can be made.
So, if you have a file foo.c, make
will run the C compiler;
otherwise, if you have a file foo.p, make
will run the Pascal
compiler; and so on.
Of course, when you write the makefile, you know which implicit rule you
want make
to use, and you know it will choose that one because you
know which possible prerequisite files are supposed to exist.
See Catalogue of Built-In Rules,
for a catalogue of all the predefined implicit rules.
Above, we said an implicit rule applies if the required prerequisites “exist or can be made”. A file “can be made” if it is mentioned explicitly in the makefile as a target or a prerequisite, or if an implicit rule can be recursively found for how to make it. When an implicit prerequisite is the result of another implicit rule, we say that chaining is occurring. See Chains of Implicit Rules.
In general, make
searches for an implicit rule for each target, and
for each double-colon rule, that has no recipe. A file that is mentioned
only as a prerequisite is considered a target whose rule specifies nothing,
so implicit rule search happens for it. See Implicit Rule Search Algorithm, for the
details of how the search is done.
Note that explicit prerequisites do not influence implicit rule search. For example, consider this explicit rule:
foo.o: foo.p
The prerequisite on foo.p does not necessarily mean that
make
will remake foo.o according to the implicit rule to
make an object file, a .o file, from a Pascal source file, a
.p file. For example, if foo.c also exists, the implicit
rule to make an object file from a C source file is used instead,
because it appears before the Pascal rule in the list of predefined
implicit rules (see Catalogue of Built-In
Rules).
If you do not want an implicit rule to be used for a target that has no recipe, you can give that target an empty recipe by writing a semicolon (see Defining Empty Recipes).
Next: Implicit Variables, Previous: Using Implicit, Up: Implicit Rules [Contents][Index]
Here is a catalogue of predefined implicit rules which are always available unless the makefile explicitly overrides or cancels them. See Canceling Implicit Rules, for information on canceling or overriding an implicit rule. The ‘-r’ or ‘--no-builtin-rules’ option cancels all predefined rules.
This manual only documents the default rules available on POSIX-based
operating systems. Other operating systems, such as VMS, Windows,
OS/2, etc. may have different sets of default rules. To see the full
list of default rules and variables available in your version of GNU
make
, run ‘make -p’ in a directory with no makefile.
Not all of these rules will always be defined, even when the ‘-r’
option is not given. Many of the predefined implicit rules are
implemented in make
as suffix rules, so which ones will be
defined depends on the suffix list (the list of prerequisites of
the special target .SUFFIXES
). The default suffix list is:
.out
, .a
, .ln
, .o
, .c
, .cc
,
.C
, .cpp
, .p
, .f
, .F
, .m
,
.r
, .y
, .l
, .ym
, .lm
, .s
,
.S
, .mod
, .sym
, .def
, .h
,
.info
, .dvi
, .tex
, .texinfo
, .texi
,
.txinfo
, .w
, .ch
.web
, .sh
,
.elc
, .el
. All of the implicit rules described below
whose prerequisites have one of these suffixes are actually suffix
rules. If you modify the suffix list, the only predefined suffix
rules in effect will be those named by one or two of the suffixes that
are on the list you specify; rules whose suffixes fail to be on the
list are disabled. See Old-Fashioned Suffix Rules,
for full details on suffix rules.
n.o is made automatically from n.c with a recipe of the form ‘$(CC) $(CPPFLAGS) $(CFLAGS) -c’.
n.o is made automatically from n.cc, n.cpp, or n.C with a recipe of the form ‘$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c’. We encourage you to use the suffix ‘.cc’ for C++ source files instead of ‘.C’.
n.o is made automatically from n.p with the recipe ‘$(PC) $(PFLAGS) -c’.
n.o is made automatically from n.r, n.F or n.f by running the Fortran compiler. The precise recipe used is as follows:
‘$(FC) $(FFLAGS) -c’.
‘$(FC) $(FFLAGS) $(CPPFLAGS) -c’.
‘$(FC) $(FFLAGS) $(RFLAGS) -c’.
n.f is made automatically from n.r or n.F. This rule runs just the preprocessor to convert a Ratfor or preprocessable Fortran program into a strict Fortran program. The precise recipe used is as follows:
‘$(FC) $(CPPFLAGS) $(FFLAGS) -F’.
‘$(FC) $(FFLAGS) $(RFLAGS) -F’.
n.sym is made from n.def with a recipe of the form ‘$(M2C) $(M2FLAGS) $(DEFFLAGS)’. n.o is made from n.mod; the form is: ‘$(M2C) $(M2FLAGS) $(MODFLAGS)’.
n.o is made automatically from n.s by
running the assembler, as
. The precise recipe is
‘$(AS) $(ASFLAGS)’.
n.s is made automatically from n.S by
running the C preprocessor, cpp
. The precise recipe is
‘$(CPP) $(CPPFLAGS)’.
n is made automatically from n.o by running
the linker (usually called ld
) via the C compiler. The precise
recipe used is ‘$(CC) $(LDFLAGS) n.o $(LOADLIBES) $(LDLIBS)’.
This rule does the right thing for a simple program with only one source file. It will also do the right thing if there are multiple object files (presumably coming from various other source files), one of which has a name matching that of the executable file. Thus,
x: y.o z.o
when x.c, y.c and z.c all exist will execute:
cc -c x.c -o x.o cc -c y.c -o y.o cc -c z.c -o z.o cc x.o y.o z.o -o x rm -f x.o rm -f y.o rm -f z.o
In more complicated cases, such as when there is no object file whose name derives from the executable file name, you must write an explicit recipe for linking.
Each kind of file automatically made into ‘.o’ object files will be automatically linked by using the compiler (‘$(CC)’, ‘$(FC)’ or ‘$(PC)’; the C compiler ‘$(CC)’ is used to assemble ‘.s’ files) without the ‘-c’ option. This could be done by using the ‘.o’ object files as intermediates, but it is faster to do the compiling and linking in one step, so that’s how it’s done.
n.c is made automatically from n.y by running Yacc with the recipe ‘$(YACC) $(YFLAGS)’.
n.c is made automatically from n.l by running Lex. The actual recipe is ‘$(LEX) $(LFLAGS)’.
n.r is made automatically from n.l by running Lex. The actual recipe is ‘$(LEX) $(LFLAGS)’.
The convention of using the same suffix ‘.l’ for all Lex files
regardless of whether they produce C code or Ratfor code makes it
impossible for make
to determine automatically which of the two
languages you are using in any particular case. If make
is
called upon to remake an object file from a ‘.l’ file, it must
guess which compiler to use. It will guess the C compiler, because
that is more common. If you are using Ratfor, make sure make
knows this by mentioning n.r in the makefile. Or, if you
are using Ratfor exclusively, with no C files, remove ‘.c’ from
the list of implicit rule suffixes with:
.SUFFIXES: .SUFFIXES: .o .r .f .l …
n.ln is made from n.c by running lint
.
The precise recipe is ‘$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i’.
The same recipe is used on the C code produced from
n.y or n.l.
n.dvi is made from n.tex with the recipe ‘$(TEX)’. n.tex is made from n.web with ‘$(WEAVE)’, or from n.w (and from n.ch if it exists or can be made) with ‘$(CWEAVE)’. n.p is made from n.web with ‘$(TANGLE)’ and n.c is made from n.w (and from n.ch if it exists or can be made) with ‘$(CTANGLE)’.
n.dvi is made from n.texinfo, n.texi, or n.txinfo, with the recipe ‘$(TEXI2DVI) $(TEXI2DVI_FLAGS)’. n.info is made from n.texinfo, n.texi, or n.txinfo, with the recipe ‘$(MAKEINFO) $(MAKEINFO_FLAGS)’.
Any file n is extracted if necessary from an RCS file named either n,v or RCS/n,v. The precise recipe used is ‘$(CO) $(COFLAGS)’. n will not be extracted from RCS if it already exists, even if the RCS file is newer. The rules for RCS are terminal (see Match-Anything Pattern Rules), so RCS files cannot be generated from another source; they must actually exist.
Any file n is extracted if necessary from an SCCS file named either s.n or SCCS/s.n. The precise recipe used is ‘$(GET) $(GFLAGS)’. The rules for SCCS are terminal (see Match-Anything Pattern Rules), so SCCS files cannot be generated from another source; they must actually exist.
For the benefit of SCCS, a file n is copied from n.sh and made executable (by everyone). This is for shell scripts that are checked into SCCS. Since RCS preserves the execution permission of a file, you do not need to use this feature with RCS.
We recommend that you avoid using of SCCS. RCS is widely held to be superior, and is also free. By choosing free software in place of comparable (or inferior) proprietary software, you support the free software movement.
Usually, you want to change only the variables listed in the table above, which are documented in the following section.
However, the recipes in built-in implicit rules actually use
variables such as COMPILE.c
, LINK.p
, and
PREPROCESS.S
, whose values contain the recipes listed above.
make
follows the convention that the rule to compile a
.x source file uses the variable COMPILE.x
.
Similarly, the rule to produce an executable from a .x
file uses LINK.x
; and the rule to preprocess a
.x file uses PREPROCESS.x
.
Every rule that produces an object file uses the variable
OUTPUT_OPTION
. make
defines this variable either to
contain ‘-o $@’, or to be empty, depending on a compile-time
option. You need the ‘-o’ option to ensure that the output goes
into the right file when the source file is in a different directory,
as when using VPATH
(see Directory Search). However,
compilers on some systems do not accept a ‘-o’ switch for object
files. If you use such a system, and use VPATH
, some
compilations will put their output in the wrong place.
A possible workaround for this problem is to give OUTPUT_OPTION
the value ‘; mv $*.o $@’.
Next: Chained Rules, Previous: Catalogue of Rules, Up: Implicit Rules [Contents][Index]
The recipes in built-in implicit rules make liberal use of certain
predefined variables. You can alter the values of these variables in
the makefile, with arguments to make
, or in the environment to
alter how the implicit rules work without redefining the rules
themselves. You can cancel all variables used by implicit rules with
the ‘-R’ or ‘--no-builtin-variables’ option.
For example, the recipe used to compile a C source file actually says ‘$(CC) -c $(CFLAGS) $(CPPFLAGS)’. The default values of the variables used are ‘cc’ and nothing, resulting in the command ‘cc -c’. By redefining ‘CC’ to ‘ncc’, you could cause ‘ncc’ to be used for all C compilations performed by the implicit rule. By redefining ‘CFLAGS’ to be ‘-g’, you could pass the ‘-g’ option to each compilation. All implicit rules that do C compilation use ‘$(CC)’ to get the program name for the compiler and all include ‘$(CFLAGS)’ among the arguments given to the compiler.
The variables used in implicit rules fall into two classes: those that are
names of programs (like CC
) and those that contain arguments for the
programs (like CFLAGS
). (The “name of a program” may also contain
some command arguments, but it must start with an actual executable program
name.) If a variable value contains more than one argument, separate them
with spaces.
The following tables describe of some of the more commonly-used predefined
variables. This list is not exhaustive, and the default values shown here may
not be what make
selects for your environment. To see the
complete list of predefined variables for your instance of GNU make
you
can run ‘make -p’ in a directory with no makefiles.
Here is a table of some of the more common variables used as names of programs in built-in rules:
AR
AS
CC
CXX
CPP
Program for running the C preprocessor, with results to standard output; default ‘$(CC) -E’.
FC
Program for compiling or preprocessing Fortran and Ratfor programs; default ‘f77’.
M2C
Program to use to compile Modula-2 source code; default ‘m2c’.
PC
CO
GET
LEX
Program to use to turn Lex grammars into source code; default ‘lex’.
YACC
Program to use to turn Yacc grammars into source code; default ‘yacc’.
LINT
MAKEINFO
Program to convert a Texinfo source file into an Info file; default ‘makeinfo’.
TEX
Program to make TeX DVI files from TeX source; default ‘tex’.
TEXI2DVI
Program to make TeX DVI files from Texinfo source; default ‘texi2dvi’.
WEAVE
CWEAVE
TANGLE
CTANGLE
RM
Here is a table of variables whose values are additional arguments for the programs above. The default values for all of these is the empty string, unless otherwise noted.
ARFLAGS
Flags to give the archive-maintaining program; default ‘rv’.
ASFLAGS
Extra flags to give to the assembler (when explicitly invoked on a ‘.s’ or ‘.S’ file).
CFLAGS
Extra flags to give to the C compiler.
CXXFLAGS
Extra flags to give to the C++ compiler.
COFLAGS
Extra flags to give to the RCS co
program.
CPPFLAGS
Extra flags to give to the C preprocessor and programs that use it (the C and Fortran compilers).
FFLAGS
Extra flags to give to the Fortran compiler.
GFLAGS
Extra flags to give to the SCCS get
program.
LDFLAGS
Extra flags to give to compilers when they are supposed to invoke the linker,
‘ld’, such as -L
. Libraries (-lfoo
) should be
added to the LDLIBS
variable instead.
LDLIBS
Library flags or names given to compilers when they are supposed to
invoke the linker, ‘ld’. LOADLIBES
is a deprecated (but
still supported) alternative to LDLIBS
. Non-library linker
flags, such as -L
, should go in the LDFLAGS
variable.
LFLAGS
Extra flags to give to Lex.
YFLAGS
Extra flags to give to Yacc.
PFLAGS
Extra flags to give to the Pascal compiler.
RFLAGS
Extra flags to give to the Fortran compiler for Ratfor programs.
LINTFLAGS
Extra flags to give to lint.
Next: Pattern Rules, Previous: Implicit Variables, Up: Implicit Rules [Contents][Index]
Sometimes a file can be made by a sequence of implicit rules. For example,
a file n.o could be made from n.y by running
first Yacc and then cc
. Such a sequence is called a chain.
If the file n.c exists, or is mentioned in the makefile, no
special searching is required: make
finds that the object file can
be made by C compilation from n.c; later on, when considering
how to make n.c, the rule for running Yacc is
used. Ultimately both n.c and n.o are
updated.
However, even if n.c does not exist and is not mentioned,
make
knows how to envision it as the missing link between
n.o and n.y! In this case, n.c is
called an intermediate file. Once make
has decided to use the
intermediate file, it is entered in the data base as if it had been
mentioned in the makefile, along with the implicit rule that says how to
create it.
Intermediate files are remade using their rules just like all other files. But intermediate files are treated differently in two ways.
The first difference is what happens if the intermediate file does not
exist. If an ordinary file b does not exist, and make
considers a target that depends on b, it invariably creates
b and then updates the target from b. But if b is an
intermediate file, then make
can leave well enough alone. It
won’t bother updating b, or the ultimate target, unless some
prerequisite of b is newer than that target or there is some other
reason to update that target.
The second difference is that if make
does create b
in order to update something else, it deletes b later on after it
is no longer needed. Therefore, an intermediate file which did not
exist before make
also does not exist after make
.
make
reports the deletion to you by printing a ‘rm -f’
command showing which file it is deleting.
Ordinarily, a file cannot be intermediate if it is mentioned in the
makefile as a target or prerequisite. However, you can explicitly mark a
file as intermediate by listing it as a prerequisite of the special target
.INTERMEDIATE
. This takes effect even if the file is mentioned
explicitly in some other way.
You can prevent automatic deletion of an intermediate file by marking it
as a secondary file. To do this, list it as a prerequisite of the
special target .SECONDARY
. When a file is secondary, make
will not create the file merely because it does not already exist, but
make
does not automatically delete the file. Marking a file as
secondary also marks it as intermediate.
You can list the target pattern of an implicit rule (such as ‘%.o’)
as a prerequisite of the special target .PRECIOUS
to preserve
intermediate files made by implicit rules whose target patterns match
that file’s name; see Interrupts.
A chain can involve more than two implicit rules. For example, it is
possible to make a file foo from RCS/foo.y,v by running RCS,
Yacc and cc
. Then both foo.y and foo.c are
intermediate files that are deleted at the end.
No single implicit rule can appear more than once in a chain. This means
that make
will not even consider such a ridiculous thing as making
foo from foo.o.o by running the linker twice. This
constraint has the added benefit of preventing any infinite loop in the
search for an implicit rule chain.
There are some special implicit rules to optimize certain cases that would
otherwise be handled by rule chains. For example, making foo from
foo.c could be handled by compiling and linking with separate
chained rules, using foo.o as an intermediate file. But what
actually happens is that a special rule for this case does the compilation
and linking with a single cc
command. The optimized rule is used in
preference to the step-by-step chain because it comes earlier in the
ordering of rules.
Next: Last Resort, Previous: Chained Rules, Up: Implicit Rules [Contents][Index]
You define an implicit rule by writing a pattern rule. A pattern rule looks like an ordinary rule, except that its target contains the character ‘%’ (exactly one of them). The target is considered a pattern for matching file names; the ‘%’ can match any nonempty substring, while other characters match only themselves. The prerequisites likewise use ‘%’ to show how their names relate to the target name.
Thus, a pattern rule ‘%.o : %.c’ says how to make any file stem.o from another file stem.c.
Note that expansion using ‘%’ in pattern rules occurs after any variable or function expansions, which take place when the makefile is read. See How to Use Variables, and Functions for Transforming Text.
| • Pattern Intro: | An introduction to pattern rules. | |
| • Pattern Examples: | Examples of pattern rules. | |
| • Automatic Variables: | How to use automatic variables in the recipe of implicit rules. | |
| • Pattern Match: | How patterns match. | |
| • Match-Anything Rules: | Precautions you should take prior to defining rules that can match any target file whatever. | |
| • Canceling Rules: | How to override or cancel built-in rules. |
Next: Pattern Examples, Previous: Pattern Rules, Up: Pattern Rules [Contents][Index]
A pattern rule contains the character ‘%’ (exactly one of them) in the target; otherwise, it looks exactly like an ordinary rule. The target is a pattern for matching file names; the ‘%’ matches any nonempty substring, while other characters match only themselves.
For example, ‘%.c’ as a pattern matches any file name that ends in ‘.c’. ‘s.%.c’ as a pattern matches any file name that starts with ‘s.’, ends in ‘.c’ and is at least five characters long. (There must be at least one character to match the ‘%’.) The substring that the ‘%’ matches is called the stem.
‘%’ in a prerequisite of a pattern rule stands for the same stem that was matched by the ‘%’ in the target. In order for the pattern rule to apply, its target pattern must match the file name under consideration and all of its prerequisites (after pattern substitution) must name files that exist or can be made. These files become prerequisites of the target.
Thus, a rule of the form
%.o : %.c ; recipe…
specifies how to make a file n.o, with another file n.c as its prerequisite, provided that n.c exists or can be made.
There may also be prerequisites that do not use ‘%’; such a prerequisite attaches to every file made by this pattern rule. These unvarying prerequisites are useful occasionally.
A pattern rule need not have any prerequisites that contain ‘%’, or in fact any prerequisites at all. Such a rule is effectively a general wildcard. It provides a way to make any file that matches the target pattern. See Last Resort.
More than one pattern rule may match a target. In this case
make
will choose the “best fit” rule. See How Patterns Match.
Pattern rules may have more than one target. Unlike normal rules,
this does not act as many different rules with the same prerequisites
and recipe. If a pattern rule has multiple targets, make
knows
that the rule’s recipe is responsible for making all of the targets.
The recipe is executed only once to make all the targets. When
searching for a pattern rule to match a target, the target patterns of
a rule other than the one that matches the target in need of a rule
are incidental: make
worries only about giving a recipe and
prerequisites to the file presently in question. However, when this
file’s recipe is run, the other targets are marked as having been
updated themselves.
Next: Automatic Variables, Previous: Pattern Intro, Up: Pattern Rules [Contents][Index]
Here are some examples of pattern rules actually predefined in
make
. First, the rule that compiles ‘.c’ files into ‘.o’
files:
%.o : %.c $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@
defines a rule that can make any file x.o from x.c. The recipe uses the automatic variables ‘$@’ and ‘$<’ to substitute the names of the target file and the source file in each case where the rule applies (see Automatic Variables).
Here is a second built-in rule:
% :: RCS/%,v $(CO) $(COFLAGS) $<
defines a rule that can make any file x whatsoever from a corresponding file x,v in the sub-directory RCS. Since the target is ‘%’, this rule will apply to any file whatever, provided the appropriate prerequisite file exists. The double colon makes the rule terminal, which means that its prerequisite may not be an intermediate file (see Match-Anything Pattern Rules).
This pattern rule has two targets:
%.tab.c %.tab.h: %.y bison -d $<
This tells make
that the recipe ‘bison -d x.y’ will
make both x.tab.c and x.tab.h. If the file
foo depends on the files parse.tab.o and scan.o
and the file scan.o depends on the file parse.tab.h,
when parse.y is changed, the recipe ‘bison -d parse.y’
will be executed only once, and the prerequisites of both
parse.tab.o and scan.o will be satisfied. (Presumably
the file parse.tab.o will be recompiled from parse.tab.c
and the file scan.o from scan.c, while foo is
linked from parse.tab.o, scan.o, and its other
prerequisites, and it will execute happily ever after.)
Next: Pattern Match, Previous: Pattern Examples, Up: Pattern Rules [Contents][Index]
Suppose you are writing a pattern rule to compile a ‘.c’ file into a ‘.o’ file: how do you write the ‘cc’ command so that it operates on the right source file name? You cannot write the name in the recipe, because the name is different each time the implicit rule is applied.
What you do is use a special feature of make
, the automatic
variables. These variables have values computed afresh for each rule that
is executed, based on the target and prerequisites of the rule. In this
example, you would use ‘$@’ for the object file name and ‘$<’
for the source file name.
It’s very important that you recognize the limited scope in which
automatic variable values are available: they only have values within
the recipe. In particular, you cannot use them anywhere
within the target list of a rule; they have no value there and will
expand to the empty string. Also, they cannot be accessed directly
within the prerequisite list of a rule. A common mistake is
attempting to use $@
within the prerequisites list; this will
not work. However, there is a special feature of GNU make
,
secondary expansion (see Secondary Expansion), which will allow
automatic variable values to be used in prerequisite lists.
Here is a table of automatic variables:
$@
The file name of the target of the rule. If the target is an archive member, then ‘$@’ is the name of the archive file. In a pattern rule that has multiple targets (see Introduction to Pattern Rules), ‘$@’ is the name of whichever target caused the rule’s recipe to be run.
$%
The target member name, when the target is an archive member. See Archives. For example, if the target is foo.a(bar.o) then ‘$%’ is bar.o and ‘$@’ is foo.a. ‘$%’ is empty when the target is not an archive member.
$<
The name of the first prerequisite. If the target got its recipe from an implicit rule, this will be the first prerequisite added by the implicit rule (see Implicit Rules).
$?
The names of all the prerequisites that are newer than the target, with spaces between them. For prerequisites which are archive members, only the named member is used (see Archives).
$^
The names of all the prerequisites, with spaces between them. For
prerequisites which are archive members, only the named member is used
(see Archives). A target has only one prerequisite on each other file
it depends on, no matter how many times each file is listed as a
prerequisite. So if you list a prerequisite more than once for a target,
the value of $^
contains just one copy of the name. This list
does not contain any of the order-only prerequisites; for those
see the ‘$|’ variable, below.
$+
This is like ‘$^’, but prerequisites listed more than once are duplicated in the order they were listed in the makefile. This is primarily useful for use in linking commands where it is meaningful to repeat library file names in a particular order.
$|
The names of all the order-only prerequisites, with spaces between them.
$*
The stem with which an implicit rule matches (see How Patterns Match). If the target is dir/a.foo.b and the target pattern is a.%.b then the stem is dir/foo. The stem is useful for constructing names of related files.
In a static pattern rule, the stem is part of the file name that matched the ‘%’ in the target pattern.
In an explicit rule, there is no stem; so ‘$*’ cannot be determined
in that way. Instead, if the target name ends with a recognized suffix
(see Old-Fashioned Suffix Rules), ‘$*’ is set to
the target name minus the suffix. For example, if the target name is
‘foo.c’, then ‘$*’ is set to ‘foo’, since ‘.c’ is a
suffix. GNU make
does this bizarre thing only for compatibility
with other implementations of make
. You should generally avoid
using ‘$*’ except in implicit rules or static pattern rules.
If the target name in an explicit rule does not end with a recognized suffix, ‘$*’ is set to the empty string for that rule.
‘$?’ is useful even in explicit rules when you wish to operate on only the prerequisites that have changed. For example, suppose that an archive named lib is supposed to contain copies of several object files. This rule copies just the changed object files into the archive:
lib: foo.o bar.o lose.o win.o ar r lib $?
Of the variables listed above, four have values that are single file
names, and three have values that are lists of file names. These seven
have variants that get just the file’s directory name or just the file
name within the directory. The variant variables’ names are formed by
appending ‘D’ or ‘F’, respectively. These variants are
semi-obsolete in GNU make
since the functions dir
and
notdir
can be used to get a similar effect (see Functions for File Names). Note, however, that the
‘D’ variants all omit the trailing slash which always appears in
the output of the dir
function. Here is a table of the variants:
The directory part of the file name of the target, with the trailing slash removed. If the value of ‘$@’ is dir/foo.o then ‘$(@D)’ is dir. This value is . if ‘$@’ does not contain a slash.
The file-within-directory part of the file name of the target. If the value of ‘$@’ is dir/foo.o then ‘$(@F)’ is foo.o. ‘$(@F)’ is equivalent to ‘$(notdir $@)’.
The directory part and the file-within-directory part of the stem; dir and foo in this example.
The directory part and the file-within-directory part of the target archive member name. This makes sense only for archive member targets of the form archive(member) and is useful only when member may contain a directory name. (See Archive Members as Targets.)
The directory part and the file-within-directory part of the first prerequisite.
Lists of the directory parts and the file-within-directory parts of all prerequisites.
Lists of the directory parts and the file-within-directory parts of all prerequisites, including multiple instances of duplicated prerequisites.
Lists of the directory parts and the file-within-directory parts of all prerequisites that are newer than the target.
Note that we use a special stylistic convention when we talk about these
automatic variables; we write “the value of ‘$<’”, rather than
“the variable <
” as we would write for ordinary variables
such as objects
and CFLAGS
. We think this convention
looks more natural in this special case. Please do not assume it has a
deep significance; ‘$<’ refers to the variable named <
just
as ‘$(CFLAGS)’ refers to the variable named CFLAGS
.
You could just as well use ‘$(<)’ in place of ‘$<’.
Next: Match-Anything Rules, Previous: Automatic Variables, Up: Pattern Rules [Contents][Index]
A target pattern is composed of a ‘%’ between a prefix and a suffix, either or both of which may be empty. The pattern matches a file name only if the file name starts with the prefix and ends with the suffix, without overlap. The text between the prefix and the suffix is called the stem. Thus, when the pattern ‘%.o’ matches the file name test.o, the stem is ‘test’. The pattern rule prerequisites are turned into actual file names by substituting the stem for the character ‘%’. Thus, if in the same example one of the prerequisites is written as ‘%.c’, it expands to ‘test.c’.
When the target pattern does not contain a slash (and it usually does not), directory names in the file names are removed from the file name before it is compared with the target prefix and suffix. After the comparison of the file name to the target pattern, the directory names, along with the slash that ends them, are added on to the prerequisite file names generated from the pattern rule’s prerequisite patterns and the file name. The directories are ignored only for the purpose of finding an implicit rule to use, not in the application of that rule. Thus, ‘e%t’ matches the file name src/eat, with ‘src/a’ as the stem. When prerequisites are turned into file names, the directories from the stem are added at the front, while the rest of the stem is substituted for the ‘%’. The stem ‘src/a’ with a prerequisite pattern ‘c%r’ gives the file name src/car.
A pattern rule can be used to build a given file only if there is a target pattern that matches the file name, and all prerequisites in that rule either exist or can be built. The rules you write take precedence over those that are built in. Note however, that a rule whose prerequisites actually exist or are mentioned always takes priority over a rule with prerequisites that must be made by chaining other implicit rules.
It is possible that more than one pattern rule will meet these
criteria. In that case, make
will choose the rule with the
shortest stem (that is, the pattern that matches most specifically).
If more than one pattern rule has the shortest stem, make
will
choose the first one found in the makefile.
This algorithm results in more specific rules being preferred over more generic ones; for example:
%.o: %.c $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@ %.o : %.f $(COMPILE.F) $(OUTPUT_OPTION) $< lib/%.o: lib/%.c $(CC) -fPIC -c $(CFLAGS) $(CPPFLAGS) $< -o $@
Given these rules and asked to build bar.o where both
bar.c and bar.f exist, make
will choose the first
rule and compile bar.c into bar.o. In the same
situation where bar.c does not exist, then make
will
choose the second rule and compile bar.f into bar.o.
If make
is asked to build lib/bar.o and both
lib/bar.c and lib/bar.f exist, then the third rule will
be chosen since the stem for this rule (‘bar’) is shorter than
the stem for the first rule (‘lib/bar’). If lib/bar.c
does not exist then the third rule is not eligible and the second rule
will be used, even though the stem is longer.
Next: Canceling Rules, Previous: Pattern Match, Up: Pattern Rules [Contents][Index]
When a pattern rule’s target is just ‘%’, it matches any file name
whatever. We call these rules match-anything rules. They are very
useful, but it can take a lot of time for make
to think about them,
because it must consider every such rule for each file name listed either
as a target or as a prerequisite.
Suppose the makefile mentions foo.c. For this target, make
would have to consider making it by linking an object file foo.c.o,
or by C compilation-and-linking in one step from foo.c.c, or by
Pascal compilation-and-linking from foo.c.p, and many other
possibilities.
We know these possibilities are ridiculous since foo.c is a C source
file, not an executable. If make
did consider these possibilities,
it would ultimately reject them, because files such as foo.c.o and
foo.c.p would not exist. But these possibilities are so
numerous that make
would run very slowly if it had to consider
them.
To gain speed, we have put various constraints on the way make
considers match-anything rules. There are two different constraints that
can be applied, and each time you define a match-anything rule you must
choose one or the other for that rule.
One choice is to mark the match-anything rule as terminal by defining it with a double colon. When a rule is terminal, it does not apply unless its prerequisites actually exist. Prerequisites that could be made with other implicit rules are not good enough. In other words, no further chaining is allowed beyond a terminal rule.
For example, the built-in implicit rules for extracting sources from RCS
and SCCS files are terminal; as a result, if the file foo.c,v does
not exist, make
will not even consider trying to make it as an
intermediate file from foo.c,v.o or from RCS/SCCS/s.foo.c,v.
RCS and SCCS files are generally ultimate source files, which should not be
remade from any other files; therefore, make
can save time by not
looking for ways to remake them.
If you do not mark the match-anything rule as terminal, then it is non-terminal. A non-terminal match-anything rule cannot apply to a file name that indicates a specific type of data. A file name indicates a specific type of data if some non-match-anything implicit rule target matches it.
For example, the file name foo.c matches the target for the pattern
rule ‘%.c : %.y’ (the rule to run Yacc). Regardless of whether this
rule is actually applicable (which happens only if there is a file
foo.y), the fact that its target matches is enough to prevent
consideration of any non-terminal match-anything rules for the file
foo.c. Thus, make
will not even consider trying to make
foo.c as an executable file from foo.c.o, foo.c.c,
foo.c.p, etc.
The motivation for this constraint is that non-terminal match-anything rules are used for making files containing specific types of data (such as executable files) and a file name with a recognized suffix indicates some other specific type of data (such as a C source file).
Special built-in dummy pattern rules are provided solely to recognize certain file names so that non-terminal match-anything rules will not be considered. These dummy rules have no prerequisites and no recipes, and they are ignored for all other purposes. For example, the built-in implicit rule
%.p :
exists to make sure that Pascal source files such as foo.p match a specific target pattern and thereby prevent time from being wasted looking for foo.p.o or foo.p.c.
Dummy pattern rules such as the one for ‘%.p’ are made for every suffix listed as valid for use in suffix rules (see Old-Fashioned Suffix Rules).
Previous: Match-Anything Rules, Up: Pattern Rules [Contents][Index]
You can override a built-in implicit rule (or one you have defined yourself) by defining a new pattern rule with the same target and prerequisites, but a different recipe. When the new rule is defined, the built-in one is replaced. The new rule’s position in the sequence of implicit rules is determined by where you write the new rule.
You can cancel a built-in implicit rule by defining a pattern rule with the same target and prerequisites, but no recipe. For example, the following would cancel the rule that runs the assembler:
%.o : %.s
Next: Suffix Rules, Previous: Pattern Rules, Up: Implicit Rules [Contents][Index]
You can define a last-resort implicit rule by writing a terminal match-anything pattern rule with no prerequisites (see Match-Anything Rules). This is just like any other pattern rule; the only thing special about it is that it will match any target. So such a rule’s recipe is used for all targets and prerequisites that have no recipe of their own and for which no other implicit rule applies.
For example, when testing a makefile, you might not care if the source files contain real data, only that they exist. Then you might do this:
%:: touch $@
to cause all the source files needed (as prerequisites) to be created automatically.
You can instead define a recipe to be used for targets for which there
are no rules at all, even ones which don’t specify recipes. You do
this by writing a rule for the target .DEFAULT
. Such a rule’s
recipe is used for all prerequisites which do not appear as targets in
any explicit rule, and for which no implicit rule applies. Naturally,
there is no .DEFAULT
rule unless you write one.
If you use .DEFAULT
with no recipe or prerequisites:
.DEFAULT:
the recipe previously stored for .DEFAULT
is cleared. Then
make
acts as if you had never defined .DEFAULT
at all.
If you do not want a target to get the recipe from a match-anything
pattern rule or .DEFAULT
, but you also do not want any recipe
to be run for the target, you can give it an empty recipe
(see Defining Empty Recipes).
You can use a last-resort rule to override part of another makefile. See Overriding Part of Another Makefile.
Next: Implicit Rule Search, Previous: Last Resort, Up: Implicit Rules [Contents][Index]
Suffix rules are the old-fashioned way of defining implicit rules for
make
. Suffix rules are obsolete because pattern rules are more
general and clearer. They are supported in GNU make
for
compatibility with old makefiles. They come in two kinds:
double-suffix and single-suffix.
A double-suffix rule is defined by a pair of suffixes: the target suffix and the source suffix. It matches any file whose name ends with the target suffix. The corresponding implicit prerequisite is made by replacing the target suffix with the source suffix in the file name. A two-suffix rule whose target and source suffixes are ‘.o’ and ‘.c’ is equivalent to the pattern rule ‘%.o : %.c’.
A single-suffix rule is defined by a single suffix, which is the source suffix. It matches any file name, and the corresponding implicit prerequisite name is made by appending the source suffix. A single-suffix rule whose source suffix is ‘.c’ is equivalent to the pattern rule ‘% : %.c’.
Suffix rule definitions are recognized by comparing each rule’s target
against a defined list of known suffixes. When make
sees a rule
whose target is a known suffix, this rule is considered a single-suffix
rule. When make
sees a rule whose target is two known suffixes
concatenated, this rule is taken as a double-suffix rule.
For example, ‘.c’ and ‘.o’ are both on the default list of
known suffixes. Therefore, if you define a rule whose target is
‘.c.o’, make
takes it to be a double-suffix rule with source
suffix ‘.c’ and target suffix ‘.o’. Here is the old-fashioned
way to define the rule for compiling a C source file:
.c.o: $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@ $<
Suffix rules cannot have any prerequisites of their own. If they have any, they are treated as normal files with funny names, not as suffix rules. Thus, the rule:
.c.o: foo.h $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@ $<
tells how to make the file .c.o from the prerequisite file foo.h, and is not at all like the pattern rule:
%.o: %.c foo.h $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@ $<
which tells how to make ‘.o’ files from ‘.c’ files, and makes all ‘.o’ files using this pattern rule also depend on foo.h.
Suffix rules with no recipe are also meaningless. They do not remove previous rules as do pattern rules with no recipe (see Canceling Implicit Rules). They simply enter the suffix or pair of suffixes concatenated as a target in the data base.
The known suffixes are simply the names of the prerequisites of the special
target .SUFFIXES
. You can add your own suffixes by writing a rule
for .SUFFIXES
that adds more prerequisites, as in:
.SUFFIXES: .hack .win
which adds ‘.hack’ and ‘.win’ to the end of the list of suffixes.
If you wish to eliminate the default known suffixes instead of just adding
to them, write a rule for .SUFFIXES
with no prerequisites. By
special dispensation, this eliminates all existing prerequisites of
.SUFFIXES
. You can then write another rule to add the suffixes you
want. For example,
.SUFFIXES: # Delete the default suffixes .SUFFIXES: .c .o .h # Define our suffix list
The ‘-r’ or ‘--no-builtin-rules’ flag causes the default list of suffixes to be empty.
The variable SUFFIXES
is defined to the default list of suffixes
before make
reads any makefiles. You can change the list of suffixes
with a rule for the special target .SUFFIXES
, but that does not alter
this variable.
Previous: Suffix Rules, Up: Implicit Rules [Contents][Index]
Here is the procedure make
uses for searching for an implicit rule
for a target t. This procedure is followed for each double-colon
rule with no recipe, for each target of ordinary rules none of which have
a recipe, and for each prerequisite that is not the target of any rule. It
is also followed recursively for prerequisites that come from implicit
rules, in the search for a chain of rules.
Suffix rules are not mentioned in this algorithm because suffix rules are converted to equivalent pattern rules once the makefiles have been read in.
For an archive member target of the form ‘archive(member)’, the following algorithm is run twice, first using the entire target name t, and second using ‘(member)’ as the target t if the first run found no rule.
If all prerequisites exist or ought to exist, or there are no prerequisites, then this rule applies.
.DEFAULT
, if any,
applies. In that case, give t the same recipe that
.DEFAULT
has. Otherwise, there is no recipe for t.
Once a rule that applies has been found, for each target pattern of the rule other than the one that matched t or n, the ‘%’ in the pattern is replaced with s and the resultant file name is stored until the recipe to remake the target file t is executed. After the recipe is executed, each of these stored file names are entered into the data base and marked as having been updated and having the same update status as the file t.
When the recipe of a pattern rule is executed for t, the automatic variables are set corresponding to the target and prerequisites. See Automatic Variables.
Next: Extending make, Previous: Implicit Rules, Up: Top [Contents][Index]
make
to Update Archive FilesArchive files are files containing named sub-files called
members; they are maintained with the program ar
and their
main use is as subroutine libraries for linking.
| • Archive Members: | Archive members as targets. | |
| • Archive Update: | The implicit rule for archive member targets. | |
| • Archive Pitfalls: | Dangers to watch out for when using archives. | |
| • Archive Suffix Rules: | You can write a special kind of suffix rule for updating archives. |
Next: Archive Update, Previous: Archives, Up: Archives [Contents][Index]
An individual member of an archive file can be used as a target or
prerequisite in make
. You specify the member named member in
archive file archive as follows:
archive(member)
This construct is available only in targets and prerequisites, not in
recipes! Most programs that you might use in recipes do not support
this syntax and cannot act directly on archive members. Only
ar
and other programs specifically designed to operate on
archives can do so. Therefore, valid recipes to update an archive
member target probably must use ar
. For example, this rule
says to create a member hack.o in archive foolib by
copying the file hack.o:
foolib(hack.o) : hack.o ar cr foolib hack.o
In fact, nearly all archive member targets are updated in just this way
and there is an implicit rule to do it for you. Please note: The
‘c’ flag to ar
is required if the archive file does not
already exist.
To specify several members in the same archive, you can write all the member names together between the parentheses. For example:
foolib(hack.o kludge.o)
is equivalent to:
foolib(hack.o) foolib(kludge.o)
You can also use shell-style wildcards in an archive member reference. See Using Wildcard Characters in File Names. For example, ‘foolib(*.o)’ expands to all existing members of the foolib archive whose names end in ‘.o’; perhaps ‘foolib(hack.o) foolib(kludge.o)’.
Next: Archive Pitfalls, Previous: Archive Members, Up: Archives [Contents][Index]
Recall that a target that looks like a(m) stands for the member named m in the archive file a.
When make
looks for an implicit rule for such a target, as a special
feature it considers implicit rules that match (m), as well as
those that match the actual target a(m).
This causes one special rule whose target is (%) to match. This rule updates the target a(m) by copying the file m into the archive. For example, it will update the archive member target foo.a(bar.o) by copying the file bar.o into the archive foo.a as a member named bar.o.
When this rule is chained with others, the result is very powerful. Thus, ‘make "foo.a(bar.o)"’ (the quotes are needed to protect the ‘(’ and ‘)’ from being interpreted specially by the shell) in the presence of a file bar.c is enough to cause the following recipe to be run, even without a makefile:
cc -c bar.c -o bar.o ar r foo.a bar.o rm -f bar.o
Here make
has envisioned the file bar.o as an intermediate
file. See Chains of Implicit Rules.
Implicit rules such as this one are written using the automatic variable ‘$%’. See Automatic Variables.
An archive member name in an archive cannot contain a directory name, but
it may be useful in a makefile to pretend that it does. If you write an
archive member target foo.a(dir/file.o), make
will perform
automatic updating with this recipe:
ar r foo.a dir/file.o
which has the effect of copying the file dir/file.o into a member
named file.o. In connection with such usage, the automatic variables
%D
and %F
may be useful.
| • Archive Symbols: | How to update archive symbol directories. |
Previous: Archive Update, Up: Archive Update [Contents][Index]
An archive file that is used as a library usually contains a special member
named __.SYMDEF that contains a directory of the external symbol
names defined by all the other members. After you update any other
members, you need to update __.SYMDEF so that it will summarize the
other members properly. This is done by running the ranlib
program:
ranlib archivefile
Normally you would put this command in the rule for the archive file, and make all the members of the archive file prerequisites of that rule. For example,
libfoo.a: libfoo.a(x.o) libfoo.a(y.o) … ranlib libfoo.a
The effect of this is to update archive members x.o, y.o,
etc., and then update the symbol directory member __.SYMDEF by
running ranlib
. The rules for updating the members are not shown
here; most likely you can omit them and use the implicit rule which copies
files into the archive, as described in the preceding section.
This is not necessary when using the GNU ar
program, which
updates the __.SYMDEF member automatically.
Next: Archive Suffix Rules, Previous: Archive Update, Up: Archives [Contents][Index]
It is important to be careful when using parallel execution (the
-j
switch; see Parallel Execution) and archives.
If multiple ar
commands run at the same time on the same archive
file, they will not know about each other and can corrupt the file.
Possibly a future version of make
will provide a mechanism to
circumvent this problem by serializing all recipes that operate on the
same archive file. But for the time being, you must either write your
makefiles to avoid this problem in some other way, or not use -j
.
Previous: Archive Pitfalls, Up: Archives [Contents][Index]
You can write a special kind of suffix rule for dealing with archive
files. See Suffix Rules, for a full explanation of suffix rules.
Archive suffix rules are obsolete in GNU make
, because pattern
rules for archives are a more general mechanism (see Archive Update). But they are retained for compatibility with other
make
s.
To write a suffix rule for archives, you simply write a suffix rule using the target suffix ‘.a’ (the usual suffix for archive files). For example, here is the old-fashioned suffix rule to update a library archive from C source files:
.c.a: $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o $(AR) r $@ $*.o $(RM) $*.o
This works just as if you had written the pattern rule:
(%.o): %.c $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o $(AR) r $@ $*.o $(RM) $*.o
In fact, this is just what make
does when it sees a suffix rule
with ‘.a’ as the target suffix. Any double-suffix rule
‘.x.a’ is converted to a pattern rule with the target
pattern ‘(%.o)’ and a prerequisite pattern of ‘%.x’.
Since you might want to use ‘.a’ as the suffix for some other kind
of file, make
also converts archive suffix rules to pattern rules
in the normal way (see Suffix Rules). Thus a double-suffix rule
‘.x.a’ produces two pattern rules: ‘(%.o):
%.x’ and ‘%.a: %.x’.
make
GNU make
provides many advanced capabilities, including many
useful functions. However, it does not contain a complete programming
language and so it has limitations. Sometimes these limitations can be
overcome through use of the shell
function to invoke a separate
program, although this can be inefficient.
In cases where the built-in capabilities of GNU make
are
insufficient to your requirements there are two options for extending
make
. On systems where it’s provided, you can utilize GNU
Guile as an embedded scripting language (see GNU
Guile Integration). On systems which support dynamically loadable
objects, you can write your own extension in any language (which can
be compiled into such an object) and load it to provide extended
capabilities (see The load
Directive).
| • Guile Integration: | Using Guile as an embedded scripting language. | |
| • Loading Objects: | Loading dynamic objects as extensions. |
Next: Loading Objects, Previous: Extending make, Up: Extending make [Contents][Index]
GNU make
may be built with support for GNU Guile as an embedded
extension language. Guile implements the Scheme language. A review
of GNU Guile and the Scheme language and its features is beyond the
scope of this manual: see the documentation for GNU Guile and Scheme.
You can determine if make
contains support for Guile by
examining the .FEATURES
variable; it will contain the word
guile if Guile support is available.
The Guile integration provides one new make
function: guile
.
The guile
function takes one argument which is first expanded
by make
in the normal fashion, then passed to the GNU Guile
evaluator. The result of the evaluator is converted into a string and
used as the expansion of the guile
function in the makefile.
In addition, GNU make
exposes Guile procedures for use in Guile
scripts.
| • Guile Types: | Converting Guile types to make strings.
| |
| • Guile Interface: | Invoking make functions from Guile.
| |
| • Guile Example: | Example using Guile in make .
|
Next: Guile Interface, Previous: Guile Integration, Up: Guile Integration [Contents][Index]
There is only one “data type” in make
: a string. GNU Guile,
on the other hand, provides a rich variety of different data types.
An important aspect of the interface between make
and GNU Guile
is the conversion of Guile data types into make
strings.
This conversion is relevant in two places: when a makefile invokes the
guile
function to evaluate a Guile expression, the result of
that evaluation must be converted into a make string so it can be
further evaluated by make
. And secondly, when a Guile script
invokes one of the procedures exported by make
the argument
provided to the procedure must be converted into a string.
The conversion of Guile types into make
strings is as below:
#f
False is converted into the empty string: in make
conditionals
the empty string is considered false.
#t
True is converted to the string ‘#t’: in make
conditionals
any non-empty string is considered true.
symbol
number
A symbol or number is converted into the string representation of that symbol or number.
character
A printable character is converted to the same character.
string
A string containing only printable characters is converted to the same string.
list
A list is converted recursively according to the above rules. This
implies that any structured list will be flattened (that is, a result
of ‘'(a b (c d) e)’ will be converted to the make
string
‘a b c d e’).
other
Any other Guile type results in an error. In future versions of
make
, other Guile types may be converted.
The translation of ‘#f’ (to the empty string) and ‘#t’ (to
the non-empty string ‘#t’) is designed to allow you to use Guile
boolean results directly as make
boolean conditions. For
example:
$(if $(guile (access? "myfile" R_OK)),$(info myfile exists))
As a consequence of these conversion rules you must consider the
result of your Guile script, as that result will be converted into a
string and parsed by make
. If there is no natural result for
the script (that is, the script exists solely for its side-effects),
you should add ‘#f’ as the final expression in order to avoid
syntax errors in your makefile.
Next: Guile Example, Previous: Guile Types, Up: Guile Integration [Contents][Index]
make
In addition to the guile
function available in makefiles,
make
exposes some procedures for use in your Guile scripts. At
startup make
creates a new Guile module, gnu make
, and
exports these procedures as public interfaces from that module:
gmk-expand
This procedure takes a single argument which is converted into a
string. The string is expanded by make
using normal
make
expansion rules. The result of the expansion is converted
into a Guile string and provided as the result of the procedure.
gmk-eval
This procedure takes a single argument which is converted into a
string. The string is evaluated by make
as if it were a
makefile. This is the same capability available via the eval
function (see Eval Function). The result of the gmk-eval
procedure is always the empty string.
Note that gmk-eval
is not quite the same as using
gmk-expand
with the eval
function: in the latter case
the evaluated string will be expanded twice; first by
gmk-expand
, then again by the eval
function.
Previous: Guile Interface, Up: Guile Integration [Contents][Index]
make
Here is a very simple example using GNU Guile to manage writing to a
file. These Guile procedures simply open a file, allow writing to the
file (one string per line), and close the file. Note that because we
cannot store complex values such as Guile ports in make
variables, we’ll keep the port as a global variable in the Guile
interpreter.
You can create Guile functions easily using define
/endef
to create a Guile script, then use the guile
function to
internalize it:
define GUILEIO ;; A simple Guile IO library for GNU make (define MKPORT #f) (define (mkopen name mode) (set! MKPORT (open-file name mode)) #f) (define (mkwrite s) (display s MKPORT) (newline MKPORT) #f) (define (mkclose) (close-port MKPORT) #f) #f endef # Internalize the Guile IO functions $(guile $(GUILEIO))
If you have a significant amount of Guile support code, you might
consider keeping it in a different file (e.g., guileio.scm) and
then loading it in your makefile using the guile
function:
$(guile (load "guileio.scm"))
An advantage to this method is that when editing guileio.scm, your editor will understand that this file contains Scheme syntax rather than makefile syntax.
Now you can use these Guile functions to create files. Suppose you need to operate on a very large list, which cannot fit on the command line, but the utility you’re using accepts the list as input as well:
prog: $(PREREQS) @$(guile (mkopen "tmp.out" "w")) \ $(foreach X,$^,$(guile (mkwrite "$(X)"))) \ $(guile (mkclose)) $(LINK) < tmp.out
A more comprehensive suite of file manipulation procedures is possible
of course. You could, for example, maintain multiple output files at
the same time by choosing a symbol for each one and using it as the
key to a hash table, where the value is a port, then returning the
symbol to be stored in a make
variable.
Previous: Guile Integration, Up: Extending make [Contents][Index]
|
Many operating systems provide a facility for dynamically loading
compiled objects. If your system provides this facility, GNU
make
can make use of it to load dynamic objects at runtime,
providing new capabilities which may then be invoked by your makefile.
The load
directive is used to load a dynamic object. Once the
object is loaded, a “setup” function will be invoked to allow the
object to initialize itself and register new facilities with GNU
make
. A dynamic object might include new make
functions,
for example, and the “setup” function would register them with GNU
make
’s function handling system.
| • load Directive: | Loading dynamic objects as extensions. | |
| • Remaking Loaded Objects: | How loaded objects get remade. | |
| • Loaded Object API: | Programmatic interface for loaded objects. | |
| • Loaded Object Example: | Example of a loaded object |
Next: Remaking Loaded Objects, Previous: Loading Objects, Up: Loading Objects [Contents][Index]
load
DirectiveObjects are loaded into GNU make
by placing the load
directive into your makefile. The syntax of the load
directive
is as follows:
load object-file …
or:
load object-file(symbol-name) …
The file object-file is dynamically loaded by GNU make
.
If object-file does not include a directory path then it is
first looked for in the current directory. If it is not found there,
or a directory path is included, then system-specific paths will be
searched. If the load fails for any reason, make
will print a
message and exit.
If the load succeeds make
will invoke an initializing function.
If symbol-name is provided, it will be used as the name of the initializing function.
If no symbol-name is provided, the initializing function name is
created by taking the base file name of object-file, up to the
first character which is not a valid symbol name character
(alphanumerics and underscores are valid symbol name characters). To
this prefix will be appended the suffix _gmk_setup
.
More than one object file may be loaded with a single load
directive, and both forms of load
arguments may be used in the
same directive.
The initializing function will be provided the file name and line
number of the invocation of the load
operation. It should
return a value of type int
, which must be 0
on failure
and non-0
on success. If the return value is -1
, then
GNU make will not attempt to rebuild the object file
(see How Loaded Objects Are Remade).
For example:
load ../mk_funcs.so
will load the dynamic object ../mk_funcs.so. After the object
is loaded, make
will invoke the function (assumed to be defined
by the shared object) mk_funcs_gmk_setup
.
On the other hand:
load ../mk_funcs.so(init_mk_func)
will load the dynamic object ../mk_funcs.so. After the object
is loaded, make
will invoke the function init_mk_func
.
Regardless of how many times an object file appears in a load
directive, it will only be loaded (and its setup function will only
be invoked) once.
After an object has been successfully loaded, its file name is
appended to the .LOADED
variable.
If you would prefer that failure to load a dynamic object not be
reported as an error, you can use the -load
directive instead
of load
. GNU make
will not fail and no message will be
generated if an object fails to load. The failed object is not added
to the .LOADED
variable, which can then be consulted to
determine if the load was successful.
Next: Loaded Object API, Previous: load Directive, Up: Loading Objects [Contents][Index]
Loaded objects undergo the same re-make procedure as makefiles
(see How Makefiles Are Remade). If any
loaded object is recreated, then make
will start from scratch
and re-read all the makefiles, and reload the object files again. It
is not necessary for the loaded object to do anything special to
support this.
It’s up to the makefile author to provide the rules needed for rebuilding the loaded object.
Next: Loaded Object Example, Previous: Remaking Loaded Objects, Up: Loading Objects [Contents][Index]
|
To be useful, loaded objects must be able to interact with GNU
make
. This interaction includes both interfaces the loaded
object provides to makefiles and also interfaces make
provides
to the loaded object to manipulate make
’s operation.
The interface between loaded objects and make
is defined by the
gnumake.h C header file. All loaded objects written in C
should include this header file. Any loaded object not written in C
will need to implement the interface defined in this header file.
Typically, a loaded object will register one or more new GNU
make
functions using the gmk_add_function
routine from
within its setup function. The implementations of these make
functions may make use of the gmk_expand
and gmk_eval
routines to perform their tasks, then optionally return a string as
the result of the function expansion.
Every dynamic extension should define the global symbol
plugin_is_GPL_compatible
to assert that it has been licensed
under a GPL-compatible license. If this symbol does not exist,
make
emits a fatal error and exits when it tries to load your
extension.
The declared type of the symbol should be int
. It does not need
to be in any allocated section, though. The code merely asserts that
the symbol exists in the global scope. Something like this is enough:
int plugin_is_GPL_compatible;
gmk_floc
This structure represents a filename/location pair. It is provided
when defining items, so GNU make
can inform the user later
where the definition occurred if necessary.
There is currently one way for makefiles to invoke operations provided
by the loaded object: through the make
function call
interface. A loaded object can register one or more new functions
which may then be invoked from within the makefile in the same way as
any other function.
Use gmk_add_function
to create a new make
function. Its
arguments are as follows:
name
The function name. This is what the makefile should use to invoke the function. The name must be between 1 and 255 characters long and it may only contain alphanumeric, period (‘.’), dash (‘-’), and underscore (‘_’) characters. It may not begin with a period.
func_ptr
A pointer to a function that make
will invoke when it expands
the function in a makefile. This function must be defined by the
loaded object.
min_args
The minimum number of arguments the function will accept. Must be
between 0 and 255. GNU make
will check this and fail before
invoking func_ptr
if the function was invoked with too few
arguments.
max_args
The maximum number of arguments the function will accept. Must be
between 0 and 255. GNU make
will check this and fail before
invoking func_ptr
if the function was invoked with too few
arguments. If the value is 0, then any number of arguments is
accepted. If the value is greater than 0, then it must be greater
than or equal to min_args
.
flags
Flags that specify how this function will operate; the desired flags
should be OR’d together. If the GMK_FUNC_NOEXPAND
flag is
given then the function arguments will not be expanded before the
function is called; otherwise they will be expanded first.
A function registered with make
must match the
gmk_func_ptr
type. It will be invoked with three parameters:
name
(the name of the function), argc
(the number of
arguments to the function), and argv
(an array of pointers to
arguments to the function). The last pointer (that is,
argv[argc]
) will be null (0
).
The return value of the function is the result of expanding the
function. If the function expands to nothing the return value may be
null. Otherwise, it must be a pointer to a string created with
gmk_alloc
. Once the function returns, make
owns this
string and will free it when appropriate; it cannot be accessed by the
loaded object.
make
FacilitiesThere are some facilities exported by GNU make
for use by
loaded objects. Typically these would be run from within the
setup function and/or the functions registered via
gmk_add_function
, to retrieve or modify the data make
works with.
gmk_expand
This function takes a string and expands it using make
expansion rules. The result of the expansion is returned in a
nil-terminated string buffer. The caller is responsible for calling
gmk_free
with a pointer to the returned buffer when done.
gmk_eval
This function takes a buffer and evaluates it as a segment of makefile
syntax. This function can be used to define new variables, new rules,
etc. It is equivalent to using the eval
make
function.
Note that there is a difference between gmk_eval
and calling
gmk_expand
with a string using the eval
function: in
the latter case the string will be expanded twice; once by
gmk_expand
and then again by the eval
function. Using
gmk_eval
the buffer is only expanded once, at most (as it’s
read by the make
parser).
Some systems allow for different memory management schemes. Thus you
should never pass memory that you’ve allocated directly to any
make
function, nor should you attempt to directly free any
memory returned to you by any make
function. Instead, use the
gmk_alloc
and gmk_free
functions.
In particular, the string returned to make
by a function
registered using gmk_add_function
must be allocated
using gmk_alloc
, and the string returned from the make
gmk_expand
function must be freed (when no longer
needed) using gmk_free
.
gmk_alloc
Return a pointer to a newly-allocated buffer. This function will
always return a valid pointer; if not enough memory is available
make
will exit.
gmk_free
Free a buffer returned to you by make
. Once the
gmk_free
function returns the string will no longer be valid.
Previous: Loaded Object API, Up: Loading Objects [Contents][Index]
Let’s suppose we wanted to write a new GNU make
function that
would create a temporary file and return its name. We would like our
function to take a prefix as an argument. First we can write the
function in a file mk_temp.c:
#include <stdlib.h> #include <stdlib.h> #include <stdio.h> #include <string.h> #include <unistd.h> #include <errno.h> #include <gnumake.h> int plugin_is_GPL_compatible; char * gen_tmpfile(const char *nm, int argc, char **argv) { int fd; /* Compute the size of the filename and allocate space for it. */ int len = strlen (argv[0]) + 6 + 1; char *buf = gmk_alloc (len); strcpy (buf, argv[0]); strcat (buf, "XXXXXX"); fd = mkstemp(buf); if (fd >= 0) { /* Don't leak the file descriptor. */ close (fd); return buf; } /* Failure. */ fprintf (stderr, "mkstemp(%s) failed: %s\n", buf, strerror (errno)); gmk_free (buf); return NULL; } int mk_temp_gmk_setup () { /* Register the function with make name "mk-temp". */ gmk_add_function ("mk-temp", gen_tmpfile, 1, 1, 1); return 1; }
Next, we will write a makefile that can build this shared object, load it, and use it:
all: @echo Temporary file: $(mk-temp tmpfile.) load mk_temp.so mk_temp.so: mk_temp.c $(CC) -shared -fPIC -o $ $<
On MS-Windows, due to peculiarities of how shared objects are
produced, the compiler needs to scan the import library produced
when building make
, typically called
libgnumake-version.dll.a, where version is the
version of the load object API. So the recipe to produce a shared
object will look on Windows like this (assuming the API version is 1):
mk_temp.dll: mk_temp.c $(CC) -shared -o $ $< -lgnumake-1
Now when you run make
you’ll see something like:
$ make cc -shared -fPIC -o mk_temp.so mk_temp.c Temporary filename: tmpfile.A7JEwd
Next: Missing, Previous: Extending make, Up: Top [Contents][Index]
make
Here is a summary of the features of GNU make
, for comparison
with and credit to other versions of make
. We consider the
features of make
in 4.2 BSD systems as a baseline. If you are
concerned with writing portable makefiles, you should not use the
features of make
listed here, nor the ones in Missing.
Many features come from the version of make
in System V.
VPATH
variable and its special meaning.
See Searching Directories for Prerequisites.
This feature exists in System V make
, but is undocumented.
It is documented in 4.3 BSD make
(which says it mimics System V’s
VPATH
feature).
MAKEFLAGS
to recursive
invocations of make
.
See Communicating Options to a Sub-make
.
$%
is set to the member name
in an archive reference. See Automatic Variables.
$@
, $*
, $<
, $%
,
and $?
have corresponding forms like $(@F)
and
$(@D)
. We have generalized this to $^
as an obvious
extension. See Automatic Variables.
make
, these options actually do something.
make
via the variable
MAKE
even if ‘-n’, ‘-q’ or ‘-t’ is specified.
See Recursive Use of make
.
make
, because the
general feature of rule chaining (see Chains of
Implicit Rules) allows one pattern rule for installing members in an
archive (see Archive Update) to be sufficient.
The following features were inspired by various other versions of
make
. In some cases it is unclear exactly which versions inspired
which others.
make
.
We’re not sure who invented it first, but it’s been spread around a bit.
See Defining and Redefining Pattern Rules.
make
for AT&T Eighth Edition Research Unix, and later by Andrew Hume of
AT&T Bell Labs in his mk
program (where he terms it
“transitive closure”). We do not really know if
we got this from either of them or thought it up ourselves at the
same time. See Chains of Implicit Rules.
$^
containing a list of all prerequisites
of the current target. We did not invent this, but we have no idea who
did. See Automatic Variables. The automatic variable
$+
is a simple extension of $^
.
make
) was (as far as we know)
invented by Andrew Hume in mk
.
See Instead of Executing Recipes.
make
and similar programs, though not in the
System V or BSD implementations. See Recipe Execution.
make
by the
patsubst
function before the alternate syntax was implemented
for compatibility with SunOS 4. It is not altogether clear who
inspired whom, since GNU make
had patsubst
before SunOS
4 was released.
make
. See Appending More Text to Variables.
make
.
See Archive Members.
-include
directive to include makefiles with no error for a
nonexistent file comes from SunOS 4 make
. (But note that SunOS 4
make
does not allow multiple makefiles to be specified in one
-include
directive.) The same feature appears with the name
sinclude
in SGI make
and perhaps others.
!=
shell assignment operator exists in many BSD of
make
and is purposefully implemented here to behave identically
to those implementations.
make
’s integration of GNU
Guile.
The remaining features are inventions new in GNU make
:
make
.
MAKE
to recursive make
invocations.
See Recursive Use of make
.
define
.
See Defining Multi-Line Variables.
.PHONY
.
Andrew Hume of AT&T Bell Labs implemented a similar feature with a
different syntax in his mk
program. This seems to be a case of
parallel discovery. See Phony Targets.
This feature has been implemented numerous times in various versions
of make
; it seems a natural extension derived from the features
of the C preprocessor and similar macro languages and is not a
revolutionary concept. See Conditional Parts of Makefiles.
MAKEFILES
.
make
, they must begin with
‘.’ and not contain any ‘/’ characters.
make
recursion using the
variable MAKELEVEL
. See Recursive Use of make
.
MAKECMDGOALS
. See Arguments to Specify the Goals.
vpath
search.
See Searching Directories for Prerequisites.
make
has a very, very limited form of this
functionality in that it will check out SCCS files for makefiles.
make
.
See Loading Dynamic Objects.
Next: Makefile Conventions, Previous: Features, Up: Top [Contents][Index]
The make
programs in various other systems support a few features
that are not implemented in GNU make
. The POSIX.2 standard
(IEEE Standard 1003.2-1992) which specifies make
does not
require any of these features.
This feature was not put into GNU make
because of the
non-modularity of putting knowledge into make
of the internal
format of archive file symbol tables.
See Updating Archive Symbol Directories.
make
;
they refer to the SCCS file that corresponds
to the file one would get without the ‘~’. For example, the
suffix rule ‘.c~.o’ would make the file n.o from
the SCCS file s.n.c. For complete coverage, a whole
series of such suffix rules is required.
See Old-Fashioned Suffix Rules.
In GNU make
, this entire series of cases is handled by two
pattern rules for extraction from SCCS, in combination with the
general feature of rule chaining.
See Chains of Implicit Rules.
make
, files found by VPATH
search (see Searching Directories for
Prerequisites) have their names changed inside recipes. We feel it
is much cleaner to always use automatic variables and thus make this
feature obsolete.
make
s, the automatic variable $*
appearing in
the prerequisites of a rule has the amazingly strange “feature” of
expanding to the full name of the target of that rule. We cannot
imagine what went on in the minds of Unix make
developers to do
this; it is utterly inconsistent with the normal definition of $*
.
make
s, implicit rule search (see Using Implicit Rules) is apparently done for all
targets, not just those without recipes. This means you can
do:
foo.o: cc -c foo.c
and Unix make
will intuit that foo.o depends on
foo.c.
We feel that such usage is broken. The prerequisite properties of
make
are well-defined (for GNU make
, at least),
and doing such a thing simply does not fit the model.
make
does not include any built-in implicit rules for
compiling or preprocessing EFL programs. If we hear of anyone who is
using EFL, we will gladly add them.
make
, a suffix rule can be specified
with no recipe, and it is treated as if it had an empty recipe
(see Empty Recipes). For example:
.c.a:
will override the built-in .c.a suffix rule.
We feel that it is cleaner for a rule without a recipe to always simply
add to the prerequisite list for the target. The above example can be
easily rewritten to get the desired behavior in GNU make
:
.c.a: ;
make
invoke the shell with the ‘-e’ flag,
except under ‘-k’ (see Testing the Compilation of a
Program). The ‘-e’ flag tells the shell to exit as soon as any
program it runs returns a nonzero status. We feel it is cleaner to
write each line of the recipe to stand on its own and not require this
special treatment.
Next: Quick Reference, Previous: Missing, Up: Top [Contents][Index]
This describes conventions for writing the Makefiles for GNU programs. Using Automake will help you write a Makefile that follows these conventions. For more information on portable Makefiles, see POSIX and Portable Make Programming in Autoconf.
| • Makefile Basics: | General conventions for Makefiles. | |
| • Utilities in Makefiles: | Utilities to be used in Makefiles. | |
| • Command Variables: | Variables for specifying commands. | |
| • DESTDIR: | Supporting staged installs. | |
| • Directory Variables: | Variables for installation directories. | |
| • Standard Targets: | Standard targets for users. | |
| • Install Command Categories: | Three categories of commands in the ‘install’ rule: normal, pre-install and post-install. |
Next: Utilities in Makefiles, Up: Makefile Conventions [Contents][Index]
Every Makefile should contain this line:
SHELL = /bin/sh
to avoid trouble on systems where the SHELL
variable might be
inherited from the environment. (This is never a problem with GNU
make
.)
Different make
programs have incompatible suffix lists and
implicit rules, and this sometimes creates confusion or misbehavior. So
it is a good idea to set the suffix list explicitly using only the
suffixes you need in the particular Makefile, like this:
.SUFFIXES: .SUFFIXES: .c .o
The first line clears out the suffix list, the second introduces all suffixes which may be subject to implicit rules in this Makefile.
Don’t assume that . is in the path for command execution. When you need to run programs that are a part of your package during the make, please make sure that it uses ./ if the program is built as part of the make or $(srcdir)/ if the file is an unchanging part of the source code. Without one of these prefixes, the current search path is used.
The distinction between ./ (the build directory) and $(srcdir)/ (the source directory) is important because users can build in a separate directory using the ‘--srcdir’ option to configure. A rule of the form:
foo.1 : foo.man sedscript sed -f sedscript foo.man > foo.1
will fail when the build directory is not the source directory, because foo.man and sedscript are in the source directory.
When using GNU make
, relying on ‘VPATH’ to find the source
file will work in the case where there is a single dependency file,
since the make
automatic variable ‘$<’ will represent the
source file wherever it is. (Many versions of make
set ‘$<’
only in implicit rules.) A Makefile target like
foo.o : bar.c $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
should instead be written as
foo.o : bar.c $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
in order to allow ‘VPATH’ to work correctly. When the target has multiple dependencies, using an explicit ‘$(srcdir)’ is the easiest way to make the rule work well. For example, the target above for foo.1 is best written as:
foo.1 : foo.man sedscript sed -f $(srcdir)/sedscript $(srcdir)/foo.man > $@
GNU distributions usually contain some files which are not source files—for example, Info files, and the output from Autoconf, Automake, Bison or Flex. Since these files normally appear in the source directory, they should always appear in the source directory, not in the build directory. So Makefile rules to update them should put the updated files in the source directory.
However, if a file does not appear in the distribution, then the Makefile should not put it in the source directory, because building a program in ordinary circumstances should not modify the source directory in any way.
Try to make the build and installation targets, at least (and all their
subtargets) work correctly with a parallel make
.
Next: Command Variables, Previous: Makefile Basics, Up: Makefile Conventions [Contents][Index]
Write the Makefile commands (and any shell scripts, such as
configure
) to run under sh
(both the traditional Bourne
shell and the POSIX shell), not csh
. Don’t use any
special features of ksh
or bash
, or POSIX features
not widely supported in traditional Bourne sh
.
The configure
script and the Makefile rules for building and
installation should not use any utilities directly except these:
awk cat cmp cp diff echo egrep expr false grep install-info ln ls mkdir mv printf pwd rm rmdir sed sleep sort tar test touch tr true
Compression programs such as gzip
can be used in the
dist
rule.
Generally, stick to the widely-supported (usually POSIX-specified) options and features of these programs. For example, don’t use ‘mkdir -p’, convenient as it may be, because a few systems don’t support it at all and with others, it is not safe for parallel execution. For a list of known incompatibilities, see Portable Shell Programming in Autoconf.
It is a good idea to avoid creating symbolic links in makefiles, since a few file systems don’t support them.
The Makefile rules for building and installation can also use compilers
and related programs, but should do so via make
variables so that the
user can substitute alternatives. Here are some of the programs we
mean:
ar bison cc flex install ld ldconfig lex make makeinfo ranlib texi2dvi yacc
Use the following make
variables to run those programs:
$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX) $(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
When you use ranlib
or ldconfig
, you should make sure
nothing bad happens if the system does not have the program in question.
Arrange to ignore an error from that command, and print a message before
the command to tell the user that failure of this command does not mean
a problem. (The Autoconf ‘AC_PROG_RANLIB’ macro can help with
this.)
If you use symbolic links, you should implement a fallback for systems that don’t have symbolic links.
Additional utilities that can be used via Make variables are:
chgrp chmod chown mknod
It is ok to use other utilities in Makefile portions (or scripts) intended only for particular systems where you know those utilities exist.
Next: DESTDIR, Previous: Utilities in Makefiles, Up: Makefile Conventions [Contents][Index]
Makefiles should provide variables for overriding certain commands, options, and so on.
In particular, you should run most utility programs via variables.
Thus, if you use Bison, have a variable named BISON
whose default
value is set with ‘BISON = bison’, and refer to it with
$(BISON)
whenever you need to use Bison.
File management utilities such as ln
, rm
, mv
, and
so on, need not be referred to through variables in this way, since users
don’t need to replace them with other programs.
Each program-name variable should come with an options variable that is
used to supply options to the program. Append ‘FLAGS’ to the
program-name variable name to get the options variable name—for
example, BISONFLAGS
. (The names CFLAGS
for the C
compiler, YFLAGS
for yacc, and LFLAGS
for lex, are
exceptions to this rule, but we keep them because they are standard.)
Use CPPFLAGS
in any compilation command that runs the
preprocessor, and use LDFLAGS
in any compilation command that
does linking as well as in any direct use of ld
.
If there are C compiler options that must be used for proper
compilation of certain files, do not include them in CFLAGS
.
Users expect to be able to specify CFLAGS
freely themselves.
Instead, arrange to pass the necessary options to the C compiler
independently of CFLAGS
, by writing them explicitly in the
compilation commands or by defining an implicit rule, like this:
CFLAGS = -g ALL_CFLAGS = -I. $(CFLAGS) .c.o: $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
Do include the ‘-g’ option in CFLAGS
, because that is not
required for proper compilation. You can consider it a default
that is only recommended. If the package is set up so that it is
compiled with GCC by default, then you might as well include ‘-O’
in the default value of CFLAGS
as well.
Put CFLAGS
last in the compilation command, after other variables
containing compiler options, so the user can use CFLAGS
to
override the others.
CFLAGS
should be used in every invocation of the C compiler,
both those which do compilation and those which do linking.
Every Makefile should define the variable INSTALL
, which is the
basic command for installing a file into the system.
Every Makefile should also define the variables INSTALL_PROGRAM
and INSTALL_DATA
. (The default for INSTALL_PROGRAM
should
be $(INSTALL)
; the default for INSTALL_DATA
should be
${INSTALL} -m 644
.) Then it should use those variables as the
commands for actual installation, for executables and non-executables
respectively. Minimal use of these variables is as follows:
$(INSTALL_PROGRAM) foo $(bindir)/foo $(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
However, it is preferable to support a DESTDIR
prefix on the
target files, as explained in the next section.
It is acceptable, but not required, to install multiple files in one command, with the final argument being a directory, as in:
$(INSTALL_PROGRAM) foo bar baz $(bindir)
Next: Directory Variables, Previous: Command Variables, Up: Makefile Conventions [Contents][Index]
DESTDIR
: Support for Staged InstallsDESTDIR
is a variable prepended to each installed target file,
like this:
$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo $(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
The DESTDIR
variable is specified by the user on the make
command line as an absolute file name. For example:
make DESTDIR=/tmp/stage install
DESTDIR
should be supported only in the install*
and
uninstall*
targets, as those are the only targets where it is
useful.
If your installation step would normally install /usr/local/bin/foo and /usr/local/lib/libfoo.a, then an installation invoked as in the example above would install /tmp/stage/usr/local/bin/foo and /tmp/stage/usr/local/lib/libfoo.a instead.
Prepending the variable DESTDIR
to each target in this way
provides for staged installs, where the installed files are not
placed directly into their expected location but are instead copied
into a temporary location (DESTDIR
). However, installed files
maintain their relative directory structure and any embedded file names
will not be modified.
You should not set the value of DESTDIR
in your Makefile
at all; then the files are installed into their expected locations by
default. Also, specifying DESTDIR
should not change the
operation of the software in any way, so its value should not be
included in any file contents.
DESTDIR
support is commonly used in package creation. It is
also helpful to users who want to understand what a given package will
install where, and to allow users who don’t normally have permissions
to install into protected areas to build and install before gaining
those permissions. Finally, it can be useful with tools such as
stow
, where code is installed in one place but made to appear
to be installed somewhere else using symbolic links or special mount
operations. So, we strongly recommend GNU packages support
DESTDIR
, though it is not an absolute requirement.
Next: Standard Targets, Previous: DESTDIR, Up: Makefile Conventions [Contents][Index]
Installation directories should always be named by variables, so it is easy to install in a nonstandard place. The standard names for these variables and the values they should have in GNU packages are described below. They are based on a standard file system layout; variants of it are used in GNU/Linux and other modern operating systems.
Installers are expected to override these values when calling
make
(e.g., make prefix=/usr install or
configure
(e.g., configure --prefix=/usr). GNU
packages should not try to guess which value should be appropriate for
these variables on the system they are being installed onto: use the
default settings specified here so that all GNU packages behave
identically, allowing the installer to achieve any desired layout.
All installation directories, and their parent directories, should be created (if necessary) before they are installed into.
These first two variables set the root for the installation. All the other installation directories should be subdirectories of one of these two, and nothing should be directly installed into these two directories.
prefix
A prefix used in constructing the default values of the variables listed
below. The default value of prefix
should be /usr/local.
When building the complete GNU system, the prefix will be empty and
/usr will be a symbolic link to /.
(If you are using Autoconf, write it as ‘<EMAIL_ADDRESS>Running ‘make install’ with a different value of prefix
from
the one used to build the program should not recompile the
program.
exec_prefix
A prefix used in constructing the default values of some of the
variables listed below. The default value of exec_prefix
should
be $(prefix)
.
(If you are using Autoconf, write it as ‘<EMAIL_ADDRESS>Generally, $(exec_prefix)
is used for directories that contain
machine-specific files (such as executables and subroutine libraries),
while $(prefix)
is used directly for other directories.
Running ‘make install’ with a different value of exec_prefix
from the one used to build the program should not recompile the
program.
Executable programs are installed in one of the following directories.
bindir
The directory for installing executable programs that users can run. This should normally be /usr/local/bin, but write it as $(exec_prefix)/bin. (If you are using Autoconf, write it as ‘<EMAIL_ADDRESS>sbindir
The directory for installing executable programs that can be run from the shell, but are only generally useful to system administrators. This should normally be /usr/local/sbin, but write it as $(exec_prefix)/sbin. (If you are using Autoconf, write it as ‘<EMAIL_ADDRESS>libexecdir
The directory for installing executable programs to be run by other programs rather than by users. This directory should normally be /usr/local/libexec, but write it as $(exec_prefix)/libexec. (If you are using Autoconf, write it as ‘<EMAIL_ADDRESS>The definition of ‘libexecdir’ is the same for all packages, so you should install your data in a subdirectory thereof. Most packages install their data under $(libexecdir)/package-name/, possibly within additional subdirectories thereof, such as $(libexecdir)/package-name/machine/version.
Data files used by the program during its execution are divided into categories in two ways.
This makes for six different possibilities. However, we want to discourage the use of architecture-dependent files, aside from object files and libraries. It is much cleaner to make other data files architecture-independent, and it is generally not hard.
Here are the variables Makefiles should use to specify directories to put these various kinds of files in:
The root of the directory tree for read-only architecture-independent data files. This should normally be /usr/local/share, but write it as $(prefix)/share. (If you are using Autoconf, write it as ‘<EMAIL_ADDRESS>‘datadir’’s default value is based on this variable; so are ‘infodir’, ‘mandir’, and others.
The directory for installing idiosyncratic read-only architecture-independent data files for this program. This is usually the same place as ‘datarootdir’, but we use the two separate variables so that you can move these program-specific files without altering the location for Info files, man pages, etc.
This should normally be /usr/local/share, but write it as $(datarootdir). (If you are using Autoconf, write it as ‘<EMAIL_ADDRESS>The definition of ‘datadir’ is the same for all packages, so you should install your data in a subdirectory thereof. Most packages install their data under $(datadir)/package-name/.
The directory for installing read-only data files that pertain to a single machine–that is to say, files for configuring a host. Mailer and network configuration files, /etc/passwd, and so forth belong here. All the files in this directory should be ordinary ASCII text files. This directory should normally be /usr/local/etc, but write it as $(prefix)/etc. (If you are using Autoconf, write it as ‘<EMAIL_ADDRESS>Do not install executables here in this directory (they probably belong in $(libexecdir) or $(sbindir)). Also do not install files that are modified in the normal course of their use (programs whose purpose is to change the configuration of the system excluded). Those probably belong in $(localstatedir).
The directory for installing architecture-independent data files which the programs modify while they run. This should normally be /usr/local/com, but write it as $(prefix)/com. (If you are using Autoconf, write it as ‘<EMAIL_ADDRESS>The directory for installing data files which the programs modify while they run, and that pertain to one specific machine. Users should never need to modify files in this directory to configure the package’s operation; put such configuration information in separate files that go in $(datadir) or $(sysconfdir). $(localstatedir) should normally be /usr/local/var, but write it as $(prefix)/var. (If you are using Autoconf, write it as ‘<EMAIL_ADDRESS>The directory for installing data files which the programs modify
while they run, that pertain to one specific machine, and which need
not persist longer than the execution of the program—which is
generally long-lived, for example, until the next reboot. PID files
for system daemons are a typical use. In addition, this directory
should not be cleaned except perhaps at reboot, while the general
/tmp (TMPDIR
) may be cleaned arbitrarily. This should
normally be /var/run, but write it as
$(localstatedir)/run. Having it as a separate variable allows
the use of /run if desired, for example. (If you are using
Autoconf 2.70 or later, write it as ‘<EMAIL_ADDRESS>These variables specify the directory for installing certain specific types of files, if your program has them. Every GNU package should have Info files, so every program needs ‘infodir’, but not all need ‘libdir’ or ‘lispdir’.
The directory for installing header files to be included by user programs with the C ‘#include’ preprocessor directive. This should normally be /usr/local/include, but write it as $(prefix)/include. (If you are using Autoconf, write it as ‘<EMAIL_ADDRESS>Most compilers other than GCC do not look for header files in directory
/usr/local/include. So installing the header files this way is
only useful with GCC. Sometimes this is not a problem because some
libraries are only really intended to work with GCC. But some libraries
are intended to work with other compilers. They should install their
header files in two places, one specified by includedir
and one
specified by oldincludedir
.
The directory for installing ‘#include’ header files for use with compilers other than GCC. This should normally be /usr/include. (If you are using Autoconf, you can write it as ‘<EMAIL_ADDRESS>The Makefile commands should check whether the value of
oldincludedir
is empty. If it is, they should not try to use
it; they should cancel the second installation of the header files.
A package should not replace an existing header in this directory unless
the header came from the same package. Thus, if your Foo package
provides a header file foo.h, then it should install the header
file in the oldincludedir
directory if either (1) there is no
foo.h there or (2) the foo.h that exists came from the Foo
package.
To tell whether foo.h came from the Foo package, put a magic
string in the file—part of a comment—and grep
for that string.
The directory for installing documentation files (other than Info) for this package. By default, it should be /usr/local/share/doc/yourpkg, but it should be written as $(datarootdir)/doc/yourpkg. (If you are using Autoconf, write it as ‘<EMAIL_ADDRESS>The yourpkg subdirectory, which may include a version number, prevents collisions among files with common names, such as README.
The directory for installing the Info files for this package. By
default, it should be /usr/local/share/info, but it should be
written as $(datarootdir)/info. (If you are using Autoconf,
write it as ‘<EMAIL_ADDRESS>infodir
is separate from
docdir
for compatibility with existing practice.
Directories for installing documentation files in the particular
format. They should all be set to $(docdir)
by default. (If
you are using Autoconf, write them as ‘@htmldir@’,
‘@dvidir@’, etc.) Packages which supply several translations
of their documentation should install them in
‘$(htmldir)/’ll, ‘$(pdfdir)/’ll, etc. where
ll is a locale abbreviation such as ‘en’ or ‘pt_BR’.
The directory for object files and libraries of object code. Do not
install executables here, they probably ought to go in $(libexecdir)
instead. The value of libdir
should normally be
/usr/local/lib, but write it as $(exec_prefix)/lib.
(If you are using Autoconf, write it as ‘<EMAIL_ADDRESS>The directory for installing any Emacs Lisp files in this package. By default, it should be /usr/local/share/emacs/site-lisp, but it should be written as $(datarootdir)/emacs/site-lisp.
If you are using Autoconf, write the default as ‘@lispdir@’. In order to make ‘@lispdir@’ work, you need the following lines in your configure.ac file:
lispdir='${datarootdir}/emacs/site-lisp' AC_SUBST(lispdir)
The directory for installing locale-specific message catalogs for this package. By default, it should be /usr/local/share/locale, but it should be written as $(datarootdir)/locale. (If you are using Autoconf, write it as ‘<EMAIL_ADDRESS>This directory usually has a subdirectory per locale.
Unix-style man pages are installed in one of the following:
The top-level directory for installing the man pages (if any) for this package. It will normally be /usr/local/share/man, but you should write it as $(datarootdir)/man. (If you are using Autoconf, write it as ‘<EMAIL_ADDRESS>The directory for installing section 1 man pages. Write it as $(mandir)/man1.
The directory for installing section 2 man pages. Write it as $(mandir)/man2
Don’t make the primary documentation for any GNU software be a man page. Write a manual in Texinfo instead. Man pages are just for the sake of people running GNU software on Unix, which is a secondary application only.
The file name extension for the installed man page. This should contain a period followed by the appropriate digit; it should normally be ‘.1’.
The file name extension for installed section 1 man pages.
The file name extension for installed section 2 man pages.
Use these names instead of ‘manext’ if the package needs to install man pages in more than one section of the manual.
And finally, you should set the following variable:
The directory for the sources being compiled. The value of this
variable is normally inserted by the configure
shell script.
(If you are using Autoconf, use ‘srcdir =<EMAIL_ADDRESS>For example:
# Common prefix for installation directories. # NOTE: This directory must exist when you start the install. prefix = /usr/local datarootdir = $(prefix)/share datadir = $(datarootdir) exec_prefix = $(prefix) # Where to put the executable for the command `gcc'. bindir = $(exec_prefix)/bin # Where to put the directories used by the compiler. libexecdir = $(exec_prefix)/libexec # Where to put the Info files. infodir = $(datarootdir)/info
If your program installs a large number of files into one of the
standard user-specified directories, it might be useful to group them
into a subdirectory particular to that program. If you do this, you
should write the install
rule to create these subdirectories.
Do not expect the user to include the subdirectory name in the value of any of the variables listed above. The idea of having a uniform set of variable names for installation directories is to enable the user to specify the exact same values for several different GNU packages. In order for this to be useful, all the packages must be designed so that they will work sensibly when the user does so.
At times, not all of these variables may be implemented in the current release of Autoconf and/or Automake; but as of Autoconf 2.60, we believe all of them are. When any are missing, the descriptions here serve as specifications for what Autoconf will implement. As a programmer, you can either use a development version of Autoconf or avoid using these variables until a stable release is made which supports them.
Next: Install Command Categories, Previous: Directory Variables, Up: Makefile Conventions [Contents][Index]
All GNU programs should have the following targets in their Makefiles:
Compile the entire program. This should be the default target. This target need not rebuild any documentation files; Info files should normally be included in the distribution, and DVI (and other documentation format) files should be made only when explicitly asked for.
By default, the Make rules should compile and link with ‘-g’, so that executable programs have debugging symbols. Otherwise, you are essentially helpless in the face of a crash, and it is often far from easy to reproduce with a fresh build.
Compile the program and copy the executables, libraries, and so on to the file names where they should reside for actual use. If there is a simple test to verify that a program is properly installed, this target should run that test.
Do not strip executables when installing them. This helps eventual
debugging that may be needed later, and nowadays disk space is cheap
and dynamic loaders typically ensure debug sections are not loaded during
normal execution. Users that need stripped binaries may invoke the
install-strip
target to do that.
If possible, write the install
target rule so that it does not
modify anything in the directory where the program was built, provided
‘make all’ has just been done. This is convenient for building the
program under one user name and installing it under another.
The commands should create all the directories in which files are to be
installed, if they don’t already exist. This includes the directories
specified as the values of the variables prefix
and
exec_prefix
, as well as all subdirectories that are needed.
One way to do this is by means of an installdirs
target
as described below.
Use ‘-’ before any command for installing a man page, so that
make
will ignore any errors. This is in case there are systems
that don’t have the Unix man page documentation system installed.
The way to install Info files is to copy them into $(infodir)
with $(INSTALL_DATA)
(see Command Variables), and then run
the install-info
program if it is present. install-info
is a program that edits the Info dir file to add or update the
menu entry for the given Info file; it is part of the Texinfo package.
Here is a sample rule to install an Info file that also tries to
handle some additional situations, such as install-info
not
being present.
do-install-info: foo.info installdirs $(NORMAL_INSTALL) # Prefer an info file in . to one in srcdir. if test -f foo.info; then d=.; \ else d="$(srcdir)"; fi; \ $(INSTALL_DATA) $$d/foo.info \ "$(DESTDIR)$(infodir)/foo.info" # Run install-info only if it exists. # Use `if' instead of just prepending `-' to the # line so we notice real errors from install-info. # Use `$(SHELL) -c' because some shells do not # fail gracefully when there is an unknown command. $(POST_INSTALL) if $(SHELL) -c 'install-info --version' \ >/dev/null 2>&1; then \ install-info --dir-file="$(DESTDIR)$(infodir)/dir" \ "$(DESTDIR)$(infodir)/foo.info"; \ else true; fi
When writing the install
target, you must classify all the
commands into three categories: normal ones, pre-installation
commands and post-installation commands. See Install Command Categories.
These targets install documentation in formats other than Info;
they’re intended to be called explicitly by the person installing the
package, if that format is desired. GNU prefers Info files, so these
must be installed by the install
target.
When you have many documentation files to install, we recommend that
you avoid collisions and clutter by arranging for these targets to
install in subdirectories of the appropriate installation directory,
such as htmldir
. As one example, if your package has multiple
manuals, and you wish to install HTML documentation with many files
(such as the “split” mode output by makeinfo --html
), you’ll
certainly want to use subdirectories, or two nodes with the same name
in different manuals will overwrite each other.
Please make these install-format
targets invoke the
commands for the format target, for example, by making
format a dependency.
Delete all the installed files—the copies that the ‘install’ and ‘install-*’ targets create.
This rule should not modify the directories where compilation is done, only the directories where files are installed.
The uninstallation commands are divided into three categories, just like the installation commands. See Install Command Categories.
Like install
, but strip the executable files while installing
them. In simple cases, this target can use the install
target in
a simple way:
install-strip: $(MAKE) INSTALL_PROGRAM='$(INSTALL_PROGRAM) -s' \ install
But if the package installs scripts as well as real executables, the
install-strip
target can’t just refer to the install
target; it has to strip the executables but not the scripts.
install-strip
should not strip the executables in the build
directory which are being copied for installation. It should only strip
the copies that are installed.
Normally we do not recommend stripping an executable unless you are sure the program has no bugs. However, it can be reasonable to install a stripped executable for actual execution while saving the unstripped executable elsewhere in case there is a bug.
Delete all files in the current directory that are normally created by building the program. Also delete files in other directories if they are created by this makefile. However, don’t delete the files that record the configuration. Also preserve files that could be made by building, but normally aren’t because the distribution comes with them. There is no need to delete parent directories that were created with ‘mkdir -p’, since they could have existed anyway.
Delete .dvi files here if they are not part of the distribution.
Delete all files in the current directory (or created by this makefile) that are created by configuring or building the program. If you have unpacked the source and built the program without creating any other files, ‘make distclean’ should leave only the files that were in the distribution. However, there is no need to delete parent directories that were created with ‘mkdir -p’, since they could have existed anyway.
Like ‘clean’, but may refrain from deleting a few files that people normally don’t want to recompile. For example, the ‘mostlyclean’ target for GCC does not delete libgcc.a, because recompiling it is rarely necessary and takes a lot of time.
Delete almost everything that can be reconstructed with this Makefile.
This typically includes everything deleted by distclean
, plus
more: C source files produced by Bison, tags tables, Info files, and
so on.
The reason we say “almost everything” is that running the command
‘make maintainer-clean’ should not delete configure even
if configure can be remade using a rule in the Makefile. More
generally, ‘make maintainer-clean’ should not delete anything
that needs to exist in order to run configure and then begin to
build the program. Also, there is no need to delete parent
directories that were created with ‘mkdir -p’, since they could
have existed anyway. These are the only exceptions;
maintainer-clean
should delete everything else that can be
rebuilt.
The ‘maintainer-clean’ target is intended to be used by a maintainer of the package, not by ordinary users. You may need special tools to reconstruct some of the files that ‘make maintainer-clean’ deletes. Since these files are normally included in the distribution, we don’t take care to make them easy to reconstruct. If you find you need to unpack the full distribution again, don’t blame us.
To help make users aware of this, the commands for the special
maintainer-clean
target should start with these two:
@echo 'This command is intended for maintainers to use; it' @echo 'deletes files that may need special tools to rebuild.'
Update a tags table for this program.
Generate any Info files needed. The best way to write the rules is as follows:
info: foo.info foo.info: foo.texi chap1.texi chap2.texi $(MAKEINFO) $(srcdir)/foo.texi
You must define the variable MAKEINFO
in the Makefile. It should
run the makeinfo
program, which is part of the Texinfo
distribution.
Normally a GNU distribution comes with Info files, and that means the Info files are present in the source directory. Therefore, the Make rule for an info file should update it in the source directory. When users build the package, ordinarily Make will not update the Info files because they will already be up to date.
Generate documentation files in the given format. These targets
should always exist, but any or all can be a no-op if the given output
format cannot be generated. These targets should not be dependencies
of the all
target; the user must manually invoke them.
Here’s an example rule for generating DVI files from Texinfo:
dvi: foo.dvi foo.dvi: foo.texi chap1.texi chap2.texi $(TEXI2DVI) $(srcdir)/foo.texi
You must define the variable TEXI2DVI
in the Makefile. It
should run the program texi2dvi
, which is part of the Texinfo
distribution. (texi2dvi
uses TeX to do the real work of
formatting. TeX is not distributed with Texinfo.) Alternatively,
write only the dependencies, and allow GNU make
to provide the
command.
Here’s another example, this one for generating HTML from Texinfo:
html: foo.html foo.html: foo.texi chap1.texi chap2.texi $(TEXI2HTML) $(srcdir)/foo.texi
Again, you would define the variable TEXI2HTML
in the Makefile;
for example, it might run makeinfo --no-split --html
(makeinfo
is part of the Texinfo distribution).
Create a distribution tar file for this program. The tar file should be set up so that the file names in the tar file start with a subdirectory name which is the name of the package it is a distribution for. This name can include the version number.
For example, the distribution tar file of GCC version 1.40 unpacks into a subdirectory named gcc-1.40.
The easiest way to do this is to create a subdirectory appropriately
named, use ln
or cp
to install the proper files in it, and
then tar
that subdirectory.
Compress the tar file with gzip
. For example, the actual
distribution file for GCC version 1.40 is called gcc-1.40.tar.gz.
It is ok to support other free compression formats as well.
The dist
target should explicitly depend on all non-source files
that are in the distribution, to make sure they are up to date in the
distribution.
See Making Releases in GNU Coding Standards.
Perform self-tests (if any). The user must build the program before running the tests, but need not install the program; you should write the self-tests so that they work when the program is built but not installed.
The following targets are suggested as conventional names, for programs in which they are useful.
installcheck
Perform installation tests (if any). The user must build and install the program before running the tests. You should not assume that $(bindir) is in the search path.
installdirs
It’s useful to add a target named ‘installdirs’ to create the directories where files are installed, and their parent directories. There is a script called mkinstalldirs which is convenient for this; you can find it in the Gnulib package. You can use a rule like this:
# Make sure all installation directories (e.g. $(bindir)) # actually exist by making them if necessary. installdirs: mkinstalldirs $(srcdir)/mkinstalldirs $(bindir) $(datadir) \ $(libdir) $(infodir) \ $(mandir)
or, if you wish to support DESTDIR
(strongly encouraged),
# Make sure all installation directories (e.g. $(bindir)) # actually exist by making them if necessary. installdirs: mkinstalldirs $(srcdir)/mkinstalldirs \ $(DESTDIR)$(bindir) $(DESTDIR)$(datadir) \ $(DESTDIR)$(libdir) $(DESTDIR)$(infodir) \ $(DESTDIR)$(mandir)
This rule should not modify the directories where compilation is done. It should do nothing but create installation directories.
Previous: Standard Targets, Up: Makefile Conventions [Contents][Index]
When writing the install
target, you must classify all the
commands into three categories: normal ones, pre-installation
commands and post-installation commands.
Normal commands move files into their proper places, and set their modes. They may not alter any files except the ones that come entirely from the package they belong to.
Pre-installation and post-installation commands may alter other files; in particular, they can edit global configuration files or data bases.
Pre-installation commands are typically executed before the normal commands, and post-installation commands are typically run after the normal commands.
The most common use for a post-installation command is to run
install-info
. This cannot be done with a normal command, since
it alters a file (the Info directory) which does not come entirely and
solely from the package being installed. It is a post-installation
command because it needs to be done after the normal command which
installs the package’s Info files.
Most programs don’t need any pre-installation commands, but we have the feature just in case it is needed.
To classify the commands in the install
rule into these three
categories, insert category lines among them. A category line
specifies the category for the commands that follow.
A category line consists of a tab and a reference to a special Make variable, plus an optional comment at the end. There are three variables you can use, one for each category; the variable name specifies the category. Category lines are no-ops in ordinary execution because these three Make variables are normally undefined (and you should not define them in the makefile).
Here are the three possible category lines, each with a comment that explains what it means:
$(PRE_INSTALL) # Pre-install commands follow. $(POST_INSTALL) # Post-install commands follow. $(NORMAL_INSTALL) # Normal commands follow.
If you don’t use a category line at the beginning of the install
rule, all the commands are classified as normal until the first category
line. If you don’t use any category lines, all the commands are
classified as normal.
These are the category lines for uninstall
:
$(PRE_UNINSTALL) # Pre-uninstall commands follow. $(POST_UNINSTALL) # Post-uninstall commands follow. $(NORMAL_UNINSTALL) # Normal commands follow.
Typically, a pre-uninstall command would be used for deleting entries from the Info directory.
If the install
or uninstall
target has any dependencies
which act as subroutines of installation, then you should start
each dependency’s commands with a category line, and start the
main target’s commands with a category line also. This way, you can
ensure that each command is placed in the right category regardless of
which of the dependencies actually run.
Pre-installation and post-installation commands should not run any programs except for these:
[ basename bash cat chgrp chmod chown cmp cp dd diff echo egrep expand expr false fgrep find getopt grep gunzip gzip hostname install install-info kill ldconfig ln ls md5sum mkdir mkfifo mknod mv printenv pwd rm rmdir sed sort tee test touch true uname xargs yes
The reason for distinguishing the commands in this way is for the sake of making binary packages. Typically a binary package contains all the executables and other files that need to be installed, and has its own method of installing them—so it does not need to run the normal installation commands. But installing the binary package does need to execute the pre-installation and post-installation commands.
Programs to build binary packages work by extracting the
pre-installation and post-installation commands. Here is one way of
extracting the pre-installation commands (the -s option to
make
is needed to silence messages about entering
subdirectories):
make -s -n install -o all \ PRE_INSTALL=pre-install \ POST_INSTALL=post-install \ NORMAL_INSTALL=normal-install \ | gawk -f pre-install.awk
where the file pre-install.awk could contain this:
$0 ~ /^(normal-install|post-install)[ \t]*$/ {on = 0} on {print $0} $0 ~ /^pre-install[ \t]*$/ {on = 1}
Next: Error Messages, Previous: Makefile Conventions, Up: Top [Contents][Index]
This appendix summarizes the directives, text manipulation functions,
and special variables which GNU make
understands.
See Special Targets, Catalogue of Built-In Rules,
and Summary of Options,
for other summaries.
Here is a summary of the directives GNU make
recognizes:
define variable
define variable =
define variable :=
define variable ::=
define variable +=
define variable ?=
endef
Define multi-line variables.
See Multi-Line.
undefine variable
Undefining variables.
See Undefine Directive.
ifdef variable
ifndef variable
ifeq (a,b)
ifeq "a" "b"
ifeq 'a' 'b'
ifneq (a,b)
ifneq "a" "b"
ifneq 'a' 'b'
else
endif
Conditionally evaluate part of the makefile.
See Conditionals.
include file
-include file
sinclude file
Include another makefile.
See Including Other Makefiles.
override variable-assignment
Define a variable, overriding any previous definition, even one from
the command line.
See The override
Directive.
export
Tell make
to export all variables to child processes by default.
See Communicating Variables to a Sub-make
.
export variable
export variable-assignment
unexport variable
Tell make
whether or not to export a particular variable to child
processes.
See Communicating Variables to a Sub-make
.
private variable-assignment
Do not allow this variable assignment to be inherited by prerequisites.
See Suppressing Inheritance.
vpath pattern path
Specify a search path for files matching a ‘%’ pattern.
See The vpath
Directive.
vpath pattern
Remove all search paths previously specified for pattern.
vpath
Remove all search paths previously specified in any vpath
directive.
Here is a summary of the built-in functions (see Functions):
$(subst from,to,text)
Replace from with to in text.
See Functions for String Substitution and Analysis.
$(patsubst pattern,replacement,text)
Replace words matching pattern with replacement in text.
See Functions for String Substitution and Analysis.
$(strip string)
Remove excess whitespace characters from string.
See Functions for String Substitution and Analysis.
$(findstring find,text)
Locate find in text.
See Functions for String Substitution and Analysis.
$(filter pattern…,text)
Select words in text that match one of the pattern words.
See Functions for String Substitution and Analysis.
$(filter-out pattern…,text)
Select words in text that do not match any of the pattern words.
See Functions for String Substitution and Analysis.
$(sort list)
Sort the words in list lexicographically, removing duplicates.
See Functions for String Substitution and Analysis.
$(word n,text)
Extract the nth word (one-origin) of text.
See Functions for String Substitution and Analysis.
$(words text)
Count the number of words in text.
See Functions for String Substitution and Analysis.
$(wordlist s,e,text)
Returns the list of words in text from s to e.
See Functions for String Substitution and Analysis.
$(firstword names…)
Extract the first word of names.
See Functions for String Substitution and Analysis.
$(lastword names…)
Extract the last word of names.
See Functions for String Substitution and Analysis.
$(dir names…)
Extract the directory part of each file name.
See Functions for File Names.
$(notdir names…)
Extract the non-directory part of each file name.
See Functions for File Names.
$(suffix names…)
Extract the suffix (the last ‘.’ and following characters) of each file name.
See Functions for File Names.
$(basename names…)
Extract the base name (name without suffix) of each file name.
See Functions for File Names.
$(addsuffix suffix,names…)
Append suffix to each word in names.
See Functions for File Names.
$(addprefix prefix,names…)
Prepend prefix to each word in names.
See Functions for File Names.
$(join list1,list2)
Join two parallel lists of words.
See Functions for File Names.
$(wildcard pattern…)
Find file names matching a shell file name pattern (not a
‘%’ pattern).
See The Function wildcard
.
$(realpath names…)
For each file name in names, expand to an absolute name that
does not contain any .
, ..
, nor symlinks.
See Functions for File Names.
$(abspath names…)
For each file name in names, expand to an absolute name that
does not contain any .
or ..
components, but preserves
symlinks.
See Functions for File Names.
$(error text…)
When this function is evaluated, make
generates a fatal error
with the message text.
See Functions That Control Make.
$(warning text…)
When this function is evaluated, make
generates a warning with
the message text.
See Functions That Control Make.
$(shell command)
Execute a shell command and return its output.
See The shell
Function.
$(origin variable)
Return a string describing how the make
variable variable was
defined.
See The origin
Function.
$(flavor variable)
Return a string describing the flavor of the make
variable
variable.
See The flavor
Function.