@c Combine the variable and function indices:
@synindex vr fn
-@c Combine the program and function indices:
-@synindex pg fn
+@c Combine the program and concept indices:
+@synindex pg cp
+
+@tex
+% trying for a two-level index
+\def\doindex#1{\message{FNORD!!!}\edef\indexname{#1}\parsearg\singleindexer}
+\def\singleindexer #1{\message{frobozzing :{#1}:}\message{}\frobozz{#1}}
+\def\frobozz[#1,#2]{\message{frobozzed :{#1}:{#2}:}\message{}\dosubind{\indexname}{#1}{#2}}
+
+@end tex
@ifinfo
This file documents the GNU Make utility, which determines
get this information with the command @samp{make --version -f /dev/null}.
Be sure also to include the type of machine and operating system you are
using. If possible, include the contents of the file @file{config.h}
-that is generated by the configuration process.@c !!! make this real
+that is generated by the configuration process.
Non-bug suggestions are always welcome as well. If you have questions
about things that are unclear in the documentation or are just obscure
@noindent
We split each long line into two lines using a backslash-newline; this is
like using one long line, but is easier to read.
+@cindex continuation lines
+@cindex @code{\} (backslash), for continuation lines
+@cindex backslash (@code{\}), for continuation lines
+@cindex quoting newline, in makefile
+@cindex newline, quoting, in makefile
To use this makefile to create the executable file called @file{edit},
type:
Errors in Commands}, to see how to cause @code{make} to ignore errors
from @code{rm}.
@cindex @code{clean} target
-@pindex rm @r{(shell command)}
+@cindex @code{rm} (shell command)
@node How Make Works, Variables Simplify, Simple Makefile, Introduction
@comment node-name, next, previous, up
length in later chapters.@refill
@itemize @bullet
-@cindex rule, explicit (definition of)
-@cindex explicit rule (definition of)
+@cindex rule, explicit, definition of
+@cindex explicit rule, definition of
@item
An @dfn{explicit rule} says when and how to remake one or more files,
called the rule's targets. It lists the other files that the targets
@dfn{depend on}, and may also give commands to use to create or update
the targets. @xref{Rules, ,Writing Rules}.
-@cindex rule, implicit (definition of)
-@cindex implicit rule (definition of)
+@cindex rule, implicit, definition of
+@cindex implicit rule, definition of
@item
An @dfn{implicit rule} says when and how to remake a class of files
based on their names. It describes how a target may depend on a file
@node Makefile Names, Include, Makefile Contents, Makefiles
@section What Name to Give Your Makefile
-@cindex makefile names
-@cindex names of makefiles
-@cindex default makefile names
-@cindex file names of makefiles
+@cindex makefile name
+@cindex name of makefile
+@cindex default makefile name
+@cindex file name of makefile
@c following paragraph rewritten to avoid overfull hbox
By default, when @code{make} looks for the makefile, it tries the
following names, in order: @file{GNUmakefile}, @file{makefile}
and @file{Makefile}.@refill
-@pindex Makefile
-@pindex GNUmakefile
-@pindex makefile
+@findex Makefile
+@findex GNUmakefile
+@findex makefile
@cindex @code{README}
Normally you should call your makefile either @file{makefile} or
@cindex specifying makefile name
@cindex makefile name, how to specify
@cindex name of makefile, how to specify
-@cindex file names of makefiles, how to specify
+@cindex file name of makefile, how to specify
@node Include, MAKEFILES Variable, Makefile Names, Makefiles
@section Including Other Makefiles
@cindex including other makefiles
-@cindex makefiles, including
+@cindex makefile, including
@findex include
The @code{include} directive tells @code{make} to suspend reading the
@var{filenames} can contain shell file name patterns.
@cindex shell file name pattern (in @code{include})
@cindex shell wildcards (in @code{include})
-@cindex wildcards (in @code{include})
+@cindex wildcard, in @code{include}
Extra spaces are allowed and ignored at the beginning of the line, but
a tab is not allowed. (If the line begins with a tab, it will be
@cindex dependencies, automatic generation
@cindex @code{-I}
+@cindex @code{--include-dir}
If the specified name does not start with a slash, and the file is not
found in the current directory, several other directories are searched.
-First, any directories you have specified with the @samp{-I} option are
-searched
-(@pxref{Options Summary, ,Summary of Options}).
-Then the following directories (if they
-exist) are searched, in this order: @file{/usr/gnu/include},
-@file{/usr/local/include}, @file{/usr/include}.
-If an included makefile cannot be found in any of these directories, a
-warning message is generated, but it is not a fatal error; processing
-of the makefile containing the @code{include} continues.@refill
-@pindex /usr/gnu/include
-@pindex /usr/local/include
-@pindex /usr/include
+First, any directories you have specified with the @samp{-I} or
+@samp{--include-dir} option are searched
+(@pxref{Options Summary, ,Summary of Options}).
+Then the following directories (if they exist)
+are searched, in this order:
+@file{@var{prefix}/include} (normally @file{/usr/local/include})
+@file{/usr/gnu/include},
+@file{/usr/local/include}, @file{/usr/include}. If an included makefile
+cannot be found in any of these directories, a warning message is
+generated, but it is not a fatal error; processing of the makefile
+containing the @code{include} continues.@refill
+@findex /usr/gnu/include
+@findex /usr/local/include
+@findex /usr/include
@node MAKEFILES Variable, Remaking Makefiles, Include, Makefiles
@section The Variable @code{MAKEFILES}
-@cindex makefiles (@code{MAKEFILES} variable)
+@cindex makefile, and @code{MAKEFILES} variable
@cindex including (@code{MAKEFILES} variable)
@vindex MAKEFILES
@cindex updating makefiles
@cindex remaking makefiles
-@cindex makefiles, remaking of
+@cindex makefile, remaking of
Sometimes makefiles can be remade from other files, such as RCS or SCCS
files. If a makefile can be remade from other files, you probably want
@code{make} to get an up-to-date version of the makefile to read in.
remake makefiles which are specified as double-colon targets but have no
dependencies.@refill
-If you do not specify any makefiles to be read with @samp{-f} options,
-@code{make} will try the default makefile names;
-@pxref{Makefile Names, ,What Name to Give Your Makefile}.
-Unlike makefiles explicitly requested with @samp{-f} options,
+If you do not specify any makefiles to be read with @samp{-f} or
+@samp{--file} options, @code{make} will try the default makefile names;
+@pxref{Makefile Names, ,What Name to Give Your Makefile}. Unlike
+makefiles explicitly requested with @samp{-f} or @samp{--file} options,
@code{make} is not certain that these makefiles should exist. However,
if a default makefile does not exist but can be created by running
@code{make} rules, you probably want the rules to be run so that the
@section Overriding Part of Another Makefile
@cindex overriding makefiles
-@cindex makefiles, overriding
+@cindex makefile, overriding
Sometimes it is useful to have a makefile that is mostly just like
another makefile. You can often use the @samp{include} directive to
include one in the other, and add more targets or variable definitions.
appear on the same line, with a semicolon. Either way, the effect is the
same. @xref{Commands, ,Writing the Commands in Rules}.
-@cindex dollar signs in rules
-@cindex @code{$} in rules
-@cindex rules, and @code{$}
+@cindex dollar sign (@code{$}) in rules
+@cindex @code{$}, in rules
+@cindex rule, and @code{$}
Because dollar signs are used to start variable references, if you really
want a dollar sign in a rule you must write two of them, @samp{$$}
(@pxref{Using Variables, ,How to Use Variables}).
@cindex file name with wildcards
@cindex globbing (wildcards)
-@cindex * (wildcard character)
-@cindex ? (wildcard character)
-@cindex [@dots{}] (wildcard characters)
+@cindex @code{*} (wildcard character)
+@cindex @code{?} (wildcard character)
+@cindex @code{[@dots{}]} (wildcard characters)
A single file name can specify many files using @dfn{wildcard characters}.
The wildcard characters in @code{make} are @samp{*}, @samp{?} and
@samp{[@dots{}]}, the same as in the Bourne shell. For example, @file{*.c}
rm -f *.o
@end group
@end example
-@pindex rm @r{(shell command)}
+@cindex @code{rm} (shell command)
Wildcards are also useful in the dependencies of a rule. With the
following rule in the makefile, @samp{make print} will print all the
@end example
@cindex @code{print} target
-@pindex lpr @r{(shell command)}
-@pindex touch @r{(shell command)}
+@cindex @code{lpr} (shell command)
+@cindex @code{touch} (shell command)
@noindent
This rule uses @file{print} as an empty target file; see @ref{Empty
Targets, ,Empty Target Files to Record Events}. (The automatic variable
@vindex VPATH
@findex vpath
@cindex vpath
+@c !!! s/search path/search path for dependencies (@code{VPATH})/
@cindex search path for dependencies (@code{VPATH})
@cindex directory search (@code{VPATH})
directories to be searched, just like the search path used in the
@code{VPATH} variable.
-@code{make} handles multiple @code{vpath} directives in the order in
-which they appear in the makefile; multiple directives with the same
-pattern are independent of each other.
-
-@need 750
-Thus,
-
-@example
-@group
-vpath %.c foo
-vpath % blish
-vpath %.c bar
-@end group
-@end example
-
-@noindent
-will look for a file ending in @samp{.c} in @file{foo}, then
-@file{blish}, then @file{bar}, while
-
-@example
-@group
-vpath %.c foo:bar
-vpath % blish
-@end group
-@end example
-
-@noindent
-will look for a file ending in @samp{.c} in @file{foo}, then
-@file{bar}, then @file{blish}.
-
@item vpath @var{pattern}
Clear out the search path associated with @var{pattern}.
end in @code{.h}. (If there is no @samp{%}, the pattern must match the
dependency exactly, which is not useful very often.)
+@cindex @code{%}, quoting in @code{vpath}
+@cindex @code{%}, quoting with @code{\} (backslash)
+@cindex @code{\} (backslash), to quote @code{%}
+@cindex backslash (@code{\}), to quote @code{%}
+@cindex quoting @code{%}, in @code{vpath}
@samp{%} characters in a @code{vpath} directive's pattern can be quoted
with preceding backslashes (@samp{\}). Backslashes that would otherwise
quote @samp{%} characters can be quoted with more backslashes.
If several @code{vpath} patterns match the dependency file's name, then
@code{make} processes each matching @code{vpath} directive one by one,
-searching all the directories mentioned in each directive. The @code{vpath}
-directives are processed in the order in which they appear in the makefiles.
+searching all the directories mentioned in each directive. @code{make}
+handles multiple @code{vpath} directives in the order in which they
+appear in the makefile; multiple directives with the same pattern are
+independent of each other.
+
+@need 750
+Thus,
+
+@example
+@group
+vpath %.c foo
+vpath % blish
+vpath %.c bar
+@end group
+@end example
+
+@noindent
+will look for a file ending in @samp{.c} in @file{foo}, then
+@file{blish}, then @file{bar}, while
+
+@example
+@group
+vpath %.c foo:bar
+vpath % blish
+@end group
+@end example
+
+@noindent
+will look for a file ending in @samp{.c} in @file{foo}, then
+@file{bar}, then @file{blish}.
@node Commands/Search, Implicit/Search, Selective Search, Directory Search
@subsection Writing Shell Commands with Directory Search
-@cindex shell commands, and directory search
+@cindex shell command, and directory search
+@c !!! s/directory search/& (VPATH)/
@cindex directory search, and shell commands
When a dependency is found in another directory through directory search,
@noindent
(The variable @code{CFLAGS} exists so you can specify flags for C
-compilation by implicit rule; we use it here for consistency so it will
+compilation by implicit rules; we use it here for consistency so it will
affect all C compilations uniformly;
@pxref{Implicit Variables, ,Variables Used by Implicit Rules}.)
@cindex @code{VPATH}, and implicit rules
@cindex directory search, and implicit rules
@cindex search path, and implicit rules
-@cindex implicit rules, and directory search
-@cindex implicit rules, and @code{VPATH}
+@cindex implicit rule, and directory search
+@cindex implicit rule, and @code{VPATH}
+@cindex rule, implicit, and directory search
+@cindex rule, implicit, and @code{VPATH}
The search through the directories specified in @code{VPATH} or with
@code{vpath} happens also during consideration of implicit rules
When a dependency's name has the form @samp{-l@var{name}}, @code{make}
handles it specially by searching for the file @file{lib@var{name}.a} in
-the directories @file{/lib}, @file{/usr/lib}, and @file{/usr/local/lib},
-and then using matching @code{vpath} search paths and the @code{VPATH}
-search path.@refill
+the current directory, in directories specified by matching @code{vpath}
+search paths and the @code{VPATH} search path, and then in the
+directories @file{/lib}, @file{/usr/lib}, and @file{@var{prefix}/lib}
+(normally @file{/usr/local/lib}).
For example,
Because the @code{rm} command does not create a file named @file{clean},
probably no such file will ever exist. Therefore, the @code{rm} command
will be executed every time you say @samp{make clean}.
-@pindex rm @r{(shell command)}
+@cindex @code{rm} (shell command)
@findex .PHONY
The phony target will cease to work if anything ever does create a file
first one in the makefile, it is common to make this a phony target named
@samp{all} and give it, as dependencies, all the individual programs. For
example:
-@cindex @code{all}
@example
all : prog1 prog2 prog3
object files, the difference files, and the file @file{program}:
@example
+.PHONY: cleanall cleanobj cleandiff
+
cleanall : cleanobj cleandiff
rm program
@cindex force targets
@cindex targets, force
@cindex @code{FORCE}
-@cindex rules, no commands or dependencies
+@cindex rule, no commands or dependencies
If a rule has no dependencies or commands, and the target of the rule
is a nonexistent file, then @code{make} imagines this target to have
touch print
@end example
@cindex @code{print} target
-@pindex lpr @r{(shell command)}
-@pindex touch @r{(shell command)}
+@cindex @code{lpr} (shell command)
+@cindex @code{touch} (shell command)
@noindent
With this rule, @samp{make print} will execute the @code{lpr} command if
@item .DEFAULT
The commands specified for @code{.DEFAULT} are used for any target for
-which no rules are found (either explicit rules or implicit rules). If
-@code{.DEFAULT} commands are specified, every file mentioned as a
-dependency, but not as a target in a rule, will have these commands
-executed on its behalf. @xref{Search Algorithm, ,Implicit Rule Search
-Algorithm}.
+which no rules are found (either explicit rules or implicit rules).
+@xref{Last Resort}. If @code{.DEFAULT} commands are specified, every
+file mentioned as a dependency, but not as a target in a rule, will have
+these commands executed on its behalf. @xref{Search Algorithm,
+,Implicit Rule Search Algorithm}.
@findex .PRECIOUS
@item .PRECIOUS
@cindex precious targets
+@cindex preserving with @code{.PRECIOUS}
The targets which @code{.PRECIOUS} depends on are given this special
treatment: if @code{make} is killed or interrupted during the
@cindex multiple targets
@cindex several targets in a rule
@cindex targets, multiple
-@cindex rules, with multiple targets
+@cindex rule, with multiple targets
A rule with multiple targets is equivalent to writing many rules, each with
one target, and all identical aside from that. The same commands apply to
@noindent
Here we assume the hypothetical program @code{generate} makes two
types of output, one if given @samp{-big} and one if given
-@samp{-little}.@refill
+@samp{-little}.
+@xref{Text Functions, ,Functions for String Substitution and Analysis},
+for an explanation of the @code{subst} function.
@end itemize
Suppose you would like to vary the dependencies according to the target,
@section Multiple Rules for One Target
@cindex multiple rules for one target
@cindex several rules for one target
-@cindex rules, multiple for one target
+@cindex rule, multiple for one target
@cindex target, multiple rules for one
One file can be the target of several rules. All the dependencies
@node Static Pattern, Multiple Rules, Multiple Targets, Rules
@section Static Pattern Rules
-@cindex static pattern rules
-@cindex rules, static pattern
+@cindex static pattern rule
+@cindex rule, static pattern
@cindex pattern rules, static (not implicit)
@cindex varying dependencies
-@cindex dependencies, varying
+@cindex dependencies, varying (static pattern)
@dfn{Static pattern rules} are rules which specify multiple targets and
construct the dependency names for each target based on the target name.
ordinary rules (@pxref{Wildcards, ,Using Wildcard Characters in File
Names}).
+@cindex target pattern, static (not implicit)
+@cindex stem
The @var{target-pattern} and @var{dep-patterns} say how to compute the
dependencies of each target. Each target is matched against the
@var{target-pattern} to extract a part of the target name, called the
the pattern @samp{%.o}, with @samp{foo} as the stem. The targets
@file{foo.c} and @file{foo.out} do not match that pattern.@refill
+@cindex dependency pattern, static (not implicit)
The dependency names for each target are made by substituting the stem
for the @samp{%} in each dependency pattern. For example, if one
dependency pattern is @file{%.c}, then substitution of the stem
to write a dependency pattern that does not contain @samp{%}; then this
dependency is the same for all targets.
-@cindex backslash (@code{\}), to quote @code{%}
-@cindex @code{\} (backslash), to quote @code{%}
-@cindex quoting @code{%} with @code{\}
+@cindex @code{%}, quoting in static pattern
@cindex @code{%}, quoting with @code{\} (backslash)
+@cindex @code{\} (backslash), to quote @code{%}
+@cindex backslash (@code{\}), to quote @code{%}
+@cindex quoting @code{%}, in static pattern
@samp{%} characters in pattern rules can be quoted with preceding
backslashes (@samp{\}). Backslashes that would otherwise quote @samp{%}
characters can be quoted with more backslashes. Backslashes that quote
$(filter %.elc,$(files)): %.elc: %.el
emacs -f batch-byte-compile $<
@end example
-@pindex emacs
@noindent
Here the result of @samp{$(filter %.o,$(files))} is @file{bar.o lose.o},
@w{@samp{$(filter %.elc,$(files))}} is @file{foo.elc}, so that file is
made from @file{foo.el}.@refill
+Another example shows how to use @code{$*} in static pattern rules:
+@vindex $*@r{, and static pattern}
+
+@example
+@group
+bigoutput littleoutput : %output : text.g
+ generate text.g -$* > $@@
+@end group
+@end example
+
+@noindent
+When the @code{generate} command is run, @code{$*} will expand to the
+stem, either @samp{big} or @samp{little}.
+
@node Static versus Implicit, , Static Usage, Static Pattern
@subsection Static Pattern Rules versus Implicit Rules
-@cindex rules, static pattern versus implicit
-@cindex static pattern rules, versus implicit
+@cindex rule, static pattern versus implicit
+@cindex static pattern rule, versus implicit
A static pattern rule has much in common with an implicit rule defined as a
pattern rule (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}).
@node Double-Colon, , Multiple Rules, Rules
@section Double-Colon Rules
@cindex double-colon rules
-@cindex rules, double-colon (@code{::})
+@cindex rule, double-colon (@code{::})
@cindex multiple rules for one target (@code{::})
@cindex @code{::} rules (double-colon)
@cindex echoing of commands
@cindex silent operation
@cindex @code{@@} (in commands)
-@cindex command echoing
+@cindex commands, echoing
@cindex printing of commands
Normally @code{make} prints each command line before it is executed.
@cindex @code{-n}
@cindex @code{--just-print}
+@cindex @code{--dry-run}
+@cindex @code{--recon}
When @code{make} is given the flag @samp{-n} or @samp{--just-print},
echoing is all that happens, no execution. @xref{Options Summary,
,Summary of Options}. In this case and only this case, even the
@cindex @code{-s}
@cindex @code{--silent}
+@cindex @code{--quiet}
@findex .SILENT
The @samp{-s} or @samp{--silent}
flag to @code{make} prevents all echoing, as if all commands
@node Execution, Parallel, Echoing, Commands
@section Command Execution
-@cindex command execution
-@cindex execution of commands
-@cindex shell command execution
+@cindex commands, execution
+@cindex execution, of commands
+@cindex shell command, execution
@vindex SHELL @r{(command execution)}
When it is time to execute commands to update a target, they are executed
by making a new subshell for each line. (In practice, @code{make} may
take shortcuts that do not affect the results.)
-@pindex cd @r{(shell command)}
+@cindex @code{cd} (shell command)
@strong{Please note:} this implies that shell commands such as
@code{cd} that set variables local to each process will not affect the
following command lines. If you want to use @code{cd} to affect the
@cindex commands, quoting newlines in
@cindex backslash (@code{\}), in commands
@cindex @code{\} (backslash), in commands
-@cindex quoting newlines in commands
+@cindex quoting newline, in commands
+@cindex newline, quoting, in commands
If you would like to split a single shell command into multiple lines of
text, you must use a backslash at the end of all but the last subline.
Such a sequence of lines is combined into a single line, by deleting the
@section Parallel Execution
@cindex commands, execution in parallel
@cindex parallel execution
-@cindex execution in parallel
+@cindex execution, in parallel
@cindex job slots
@cindex @code{-j}
@cindex @code{--jobs}
-rm -f *.o
@end group
@end example
-@pindex rm @r{(shell command)}
+@cindex @code{rm} (shell command)
@noindent
This causes @code{rm} to continue even if it is unable to remove a file.
@cindex interrupt
@cindex signal
@cindex deletion of target files
-@cindex targets, deleting on interrupt
+@cindex target, deleting on interrupt
@cindex killing (interruption)
If @code{make} gets a fatal signal while a command is executing, it may
$(MAKE) -C subdir
@end example
@cindex @code{-C}
+@cindex @code{--directory}
You can write recursive @code{make} commands just by copying this example,
but there are many things to know about how they work and why, and about
how the sub-@code{make} relates to the top-level @code{make}.
+@c !!! example of many subdirs + many subdir targets
+
@menu
* MAKE Variable:: The special effects of using @samp{$(MAKE)}.
* Variables/Recursion:: How to communicate variables to a sub-@code{make}.
is @samp{cd subdir; /bin/make}. If you use a special version of
@code{make} to run the top-level makefile, the same special version will be
executed for recursive invocations.
-@pindex cd @r{(shell command)}
+@cindex @code{cd} (shell command)
Also, any arguments that define variable values are added to @code{MAKE},
so the sub-@code{make} gets them too. Thus, if you do @samp{make
require executing the command, and @samp{-t} says not to execute
commands.@refill
@cindex @code{-t}, and recursion
-@cindex recursion, and @code{-t}
+@cindex recursion, and @code{-t}
+@cindex @code{--touch}, and recursion
The special feature makes this do what you want: whenever a command
line of a rule contains the variable @code{MAKE}, the flags @samp{-t},
@xref{Options Summary, ,Summary of Options}.
@cindex @code{-C}, and recursion
-@cindex recursion, and @code{-C}
@cindex @code{-f}, and recursion
-@cindex recursion, and @code{-f}
@cindex @code{-I}, and recursion
-@cindex recursion, and @code{-I}
@cindex @code{-o}, and recursion
-@cindex recursion, and @code{-o}
@cindex @code{-W}, and recursion
+@cindex @code{--directory}, and recursion
+@cindex @code{--file}, and recursion
+@cindex @code{--include-dir}, and recursion
+@cindex @code{--old-file}, and recursion
+@cindex @code{--assume-old}, and recursion
+@cindex @code{--assume-new}, and recursion
+@cindex @code{--new-file}, and recursion
+@cindex recursion, and @code{-C}
+@cindex recursion, and @code{-f}
+@cindex recursion, and @code{-I}
+@cindex recursion, and @code{-o}
@cindex recursion, and @code{-W}
The options @samp{-C}, @samp{-f}, @samp{-I}, @samp{-o}, and @samp{-W}
are not put into @code{MAKEFLAGS}; these options are not passed down.@refill
@cindex @code{-j}, and recursion
+@cindex @code{--jobs}, and recursion
@cindex recursion, and @code{-j}
+@cindex job slots, and recursion
The @samp{-j} option is a special case
(@pxref{Parallel, ,Parallel Execution}). If you set
it to some numeric value, @samp{-j 1} is always put into
when processing is completed.
@cindex @code{-C}, and @code{-w}
+@cindex @code{--directory}, and @code{--print-directory}
@cindex recursion, and @code{-w}
@cindex @code{-w}, and @code{-C}
@cindex @code{-w}, and recursion
+@cindex @code{--print-directory}, and @code{--directory}
+@cindex @code{--print-directory}, and recursion
Normally, you do not need to specify this option because @samp{make}
does it for you: @samp{-w} is turned on automatically when you use the
@samp{-C} option, and in sub-@code{make}s (unless you also use
mv y.tab.c $@@
endef
@end example
-@pindex yacc
+@cindex @code{yacc}
@noindent
Here @code{run-yacc} is the name of the variable being defined;
@code{.DEFAULT} special target; @pxref{Implicit Rules} and
@pxref{Last Resort, ,Defining Last-Resort Default Rules}).@refill
-You may be inclined to define empty command strings for targets that
-are not actual files, but only exist so that their dependencies can be
-remade. However, this is not the best way to do that, because its
-commands may not be run if the target file actually does exist.
+You may be inclined to define empty command strings for targets that are
+not actual files, but only exist so that their dependencies can be
+remade. However, this is not the best way to do that, because the
+dependencies may not be remade properly if the target file actually does exist.
@xref{Phony Targets, ,Phony Targets}, for a better way to do this.
@node Using Variables, Conditionals, Commands, Top
@section Basics of Variable References
@cindex variables, how to reference
@cindex reference to variables
-@cindex @code{$} (variables)
-@cindex dollar sign (@code{$}), and variables
+@cindex @code{$}, in variable reference
+@cindex dollar sign (@code{$}), in variable reference
To substitute a variable's value, write a dollar sign followed by the name
of the variable in parentheses or braces: either @samp{$(foo)} or
@example
@group
foo = c
-prog.o : prog.c
- $(foo)$(foo) -$(foo) prog.c
+prog.o : prog.$(foo)
+ $(foo)$(foo) -$(foo) prog.$(foo)
@end group
@end example
@cindex variables, computed names
@cindex variables, nested references
@cindex variables, @samp{$} in name
-@cindex @code{$} in variable name
-@cindex dollar sign (@code{$}) in variable name
+@cindex @code{$}, in variable name
+@cindex dollar sign (@code{$}), in variable name
Computed variable names are a complicated concept needed only for
sophisticated makefile programming. For most purposes you need not
This restriction could be removed in the future if that change is shown
to be a good idea.
+You can also use computed variable names in the left-hand side of a
+variable assignment, or in a @code{define} directive, as in:
+
+@example
+dir = foo
+$(dir)_sources := $(wildcard $(dir)/*.c)
+define $(dir)_print
+lpr $($(dir)_sources)
+endef
+@end example
+
+@noindent
+This example defines the variables @samp{dir}, @samp{foo_sources}, and
+@samp{foo_print}.
+
Note that @dfn{nested variable references} are quite different from
@dfn{recursively expanded variables}
(@pxref{Flavors, ,The Two Flavors of Variables}), though both are
@node Values, Setting, Advanced, Using Variables
@section How Variables Get Their Values
@cindex variables, how they get their values
-@cindex values, how variables get them
+@cindex value, how a variable gets it
Variables can get values in several different ways:
definitions can contain variable references which will be expanded before
the definition is made. @xref{Flavors, ,The Two Flavors of Variables}.
+The variable name may contain function and variable references, which
+are expanded when the line is read to find the actual variable name to use.
+
There is no limit on the length of the value of a variable except the
amount of swapping space on the computer. When a variable definition is
long, it is a good idea to break it into several lines by inserting
@section The @code{override} Directive
@findex override
@cindex overriding with @code{override}
-@cindex variables, overriding
+@cindex variable, overriding
If a variable has been set with a command argument (@pxref{Overriding, ,Overriding Variables}),
then ordinary assignments in the makefile are ignored. If you want to set
@findex endef
@cindex verbatim variable definition
@cindex defining variables verbatim
-@cindex variables, defining verbatim
+@cindex variable, defining verbatim
Another way to set the value of a variable is to use the @code{define}
directive. This directive has an unusual syntax which allows newline
the word @code{endef}. Aside from this difference in syntax, @code{define}
works just like @samp{=}: it creates a recursively-expanded variable
(@pxref{Flavors, ,The Two Flavors of Variables}).
+The variable name may contain function and variable references, which
+are expanded when the directive is read to find the actual variable name
+to use.
@example
define two-lines
@node Environment, , Defining, Using Variables
@section Variables from the Environment
-@cindex variables, environment
+@cindex variable, environment
@cindex environment
Variables in @code{make} can come from the environment in which
@code{make} is run. Every environment variable that @code{make} sees when
Note that @code{ifdef} only tests whether a variable has a value. It
does not expand the variable to see if that value is nonempty.
Consequently, tests using @code{ifdef} return true for all definitions
-except those like @code{foo =}. To test for an empty value, use
-@w{@code{ifeq ($(foo),)}}.
+except those like @code{foo =}. To test for an empty value, use
+@w{@code{ifeq ($(foo),)}}. For example,
+
+@example
+bar =
+foo = $(bar)
+ifdef foo
+frobozz = yes
+else
+frobozz = no
+endif
+@end example
+
+@noindent
+sets @samp{frobozz} to @samp{yes}, while:
+
+@example
+foo =
+ifdef foo
+frobozz = yes
+else
+frobozz = no
+endif
+@end example
+
+@noindent
+sets @samp{frobozz} to @samp{no}.
@item ifndef @var{variable-name}
If the variable @var{variable-name} has an empty value, the
@node Syntax of Functions, Text Functions, , Functions
@section Function Call Syntax
-@cindex @code{$} (function call)
+@cindex @code{$}, in function call
+@cindex dollar sign (@code{$}), in function call
@cindex arguments of functions
@cindex functions, syntax of
@var{replacement} also contains a @samp{%}, the @samp{%} is replaced
by the text that matched the @samp{%} in @var{pattern}.@refill
-@cindex backslash (@code{\}), to quote @samp{%}
-@cindex @code{\} (backslash), to quote @samp{%}
-@cindex quoting @code{%} in @code{patsubst}
@cindex @code{%}, quoting in @code{patsubst}
+@cindex @code{%}, quoting with @code{\} (backslash)
+@cindex @code{\} (backslash), to quote @code{%}
+@cindex backslash (@code{\}), to quote @code{%}
+@cindex quoting @code{%}, in @code{patsubst}
@samp{%} characters in @code{patsubst} function invocations can be
quoted with preceding backslashes (@samp{\}). Backslashes that would
otherwise quote @samp{%} characters can be quoted with more backslashes.
@item $(wildcard @var{pattern})
@findex wildcard
-@cindex wildcards, function
+@cindex wildcard, function
The argument @var{pattern} is a file name pattern, typically containing
wildcard characters (as in shell file name patterns). The result of
@code{wildcard} is a space-separated list of the names of existing files
@node Origin Function, Shell Function, Foreach Function, Functions
@section The @code{origin} Function
@findex origin
-@cindex variables, origin of
+@cindex variable, origin of
@cindex origin of variable
The @code{origin} function is unlike most other functions in that it does
@node Shell Function, , Origin Function, Functions
@section The @code{shell} Function
@findex shell
-@cindex command expansion
+@cindex commands, expansion
@cindex backquotes
-@cindex shell commands, function for
+@cindex shell command, function for
The @code{shell} function is unlike any other function except the
@code{wildcard} function
@node Makefile Arguments, Goals, , Running
@section Arguments to Specify the Makefile
@cindex @code{--file}
-@cindex @code{--f}
+@cindex @code{--makefile}
+@cindex @code{-f}
The way to specify the name of the makefile is with the @samp{-f} or
-@samp{--file} option. For example, @samp{-f altmake} says to use the
-file @file{altmake} as the makefile.
+@samp{--file} option (@samp{--makefile} also works). For example,
+@samp{-f altmake} says to use the file @file{altmake} as the makefile.
If you use the @samp{-f} flag several times and follow each @samp{-f}
with an argument, all the specified files are used jointly as
@table @samp
@item -n
@itemx --just-print
+@itemx --dry-run
+@itemx --recon
@cindex @code{--just-print}
+@cindex @code{--dry-run}
+@cindex @code{--recon}
@cindex @code{-n}
``No-op''. The activity is to print what commands would be used to make
the targets up to date, but not actually execute them.
@itemx --touch
@cindex @code{--touch}
@cindex touching files
-@cindex targets, touching
+@cindex target, touching
@cindex @code{-t}
``Touch''. The activity is to mark the targets as up to date without
actually changing them. In other words, @code{make} pretends to compile
@item -W
@itemx --what-if
+@itemx --assume-new
+@itemx --new-file
@cindex @code{--what-if}
@cindex @code{-W}
+@cindex @code{--assume-new}
+@cindex @code{--new-file}
@cindex what if
@cindex files, assuming new
``What if''. Each @samp{-W} flag is followed by a file name. The given
@section Avoiding Recompilation of Some Files
@cindex @code{-o}
@cindex @code{--old-file}
+@cindex @code{--assume-old}
@cindex files, assuming old
@cindex files, avoiding recompilation of
@cindex recompilation, avoiding
@node Overriding, Testing, Avoiding Compilation, Running
@section Overriding Variables
@cindex overriding variables with arguments
-@cindex variables, overriding with arguments
+@cindex variable, overriding with arguments
@cindex command line variables
-@cindex variables, command line
+@cindex variable, command line
An argument that contains @samp{=} specifies the value of a variable:
@samp{@var{v}=@var{x}} sets the value of the variable @var{v} to @var{x}.
@cindex @code{-d}
@itemx --debug
@cindex @code{--debug}
+@c Extra blank line here makes the table look better.
+
Print debugging information in addition to normal processing. The
debugging information says which files are being considered for
remaking, which file-times are being compared and with what results,
@cindex @code{-h}
@itemx --help
@cindex @code{--help}
+@c Extra blank line here makes the table look better.
+
Remind you of the options that @code{make} understands and then exit.
@item -i
@cindex @code{--dry-run}
@itemx --recon
@cindex @code{--recon}
+@c Extra blank line here makes the table look better.
+
Print the commands that would be executed, but do not execute them.
@xref{Instead of Execution, ,Instead of Executing the Commands}.
@cindex @code{--silent}
@itemx --quiet
@cindex @code{--quiet}
+@c Extra blank line here makes the table look better.
+
Silent operation; do not print the commands as they are executed.
@xref{Echoing, ,Command Echoing}.
@cindex @code{--no-keep-going}
@itemx --stop
@cindex @code{--stop}
+@c Extra blank line here makes the table look better.
+
Cancel the effect of the @samp{-k} option. This is never necessary
except in a recursive @code{make} where @samp{-k} might be inherited
from the top-level @code{make} via @code{MAKEFLAGS} (@pxref{Recursion, ,Recursive Use of @code{make}})
@cindex @code{-t}
@itemx --touch
@cindex @code{--touch}
+@c Extra blank line here makes the table look better.
+
Touch files (mark them up to date without really changing them)
instead of running their commands. This is used to pretend that the
commands were done, in order to fool future invocations of
@cindex @code{-W}
@itemx --what-if @var{file}
@cindex @code{--what-if}
-@itemx --new @var{file}
-@cindex @code{--new}
+@itemx --new-file @var{file}
+@cindex @code{--new-file}
@itemx --assume-new @var{file}
@cindex @code{--assume-new}
Pretend that the target @var{file} has just been modified. When used
@cindex C++, rule to compile
@pindex g++
@file{@var{n}.o} is made automatically from @file{@var{n}.cc} or
-@file{@var{n}.C} with a command of the form @samp{$(C++) -c $(CPPFLAGS)
-$(C++FLAGS)}. We encourage you to use the suffix @samp{.cc} for C++
+@file{@var{n}.C} with a command of the form @samp{$(CXX) -c $(CPPFLAGS)
+$(CXXFLAGS)}. We encourage you to use the suffix @samp{.cc} for C++
source files instead of @samp{.C}.@refill
@item Compiling Pascal programs
@samp{$(AS) $(ASFLAGS)}.@refill
@file{@var{n}.s} is made automatically from @file{@var{n}.S} by
-running the C preprocessor, @code{cpp}. The precise command used is
+running the C preprocessor, @code{cpp}. The precise command is
@w{@samp{$(CPP) $(CPPFLAGS)}}.
@item Linking a single object file
Program for compiling C programs; default @samp{cc}.
@pindex cc
-@item C++
-@vindex C++
+@item CXX
+@vindex CXX
Program for compiling C++ programs; default @samp{g++}.
@pindex g++
@vindex CFLAGS
Extra flags to give to the C compiler.
-@item C++FLAGS
-@vindex C++FLAGS
+@item CXXFLAGS
+@vindex CXXFLAGS
Extra flags to give to the C++ compiler.
@item COFLAGS
@section Chains of Implicit Rules
@cindex chains of rules
-@cindex rules, implicit, chains of
+@cindex rule, implicit, chains of
Sometimes a file can be made by a sequence of implicit rules. For example,
a file @file{@var{n}.o} could be made from @file{@var{n}.y} by running
first Yacc and then @code{cc}. Such a sequence is called a @dfn{chain}.
@cindex intermediate files, preserving
@cindex preserving intermediate files
@cindex preserving with .PRECIOUS
-@cindex @code{.PRECIOUS} files
+@cindex @code{.PRECIOUS} intermediate files
A chain can involve more than two implicit rules. For example, it is
possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS,
in the target; otherwise, it looks exactly like an ordinary rule. The
target is a pattern for matching file names; the @samp{%} matches any
nonempty substring, while other characters match only themselves.
-@cindex target pattern
+@cindex target pattern, implicit
@cindex @code{%}, in pattern rules
For example, @samp{%.c} as a pattern matches any file name that ends in
the pattern rule to apply, its target pattern must match the file name
under consideration, and its dependency patterns must name files that
exist or can be made. These files become dependencies of the target.
-@cindex dependency pattern
+@cindex dependency pattern, implicit
Thus, a rule of the form
presently in question. However, when this file's commands are run, the
other targets are marked as having been updated themselves.
@cindex multiple targets, in pattern rule
-@cindex targets, multiple in pattern rule
+@cindex target, multiple in pattern rule
The order in which pattern rules appear in the makefile is important
because the rules are considered in that order. Of equally applicable
@node Automatic, Pattern Match, Pattern Examples, Pattern Rules
@subsection Automatic Variables
@cindex automatic variables
-@cindex variables, automatic
-@cindex variables, and implicit rules
+@cindex variable, automatic
+@cindex variable, and implicit rule
Suppose you are writing a pattern rule to compile a @samp{.c} file into a
@samp{.o} file: how do you write the @samp{cc} command so that it operates
@node Suffix Rules, Search Algorithm, Last Resort, Implicit Rules
@section Old-Fashioned Suffix Rules
@cindex old-fashioned suffix rules
+@cindex suffix rule
@dfn{Suffix rules} are the old-fashioned way of defining implicit rules for
@code{make}. Suffix rules are obsolete because pattern rules are more
@node Search Algorithm, , Suffix Rules, Implicit Rules
@section Implicit Rule Search Algorithm
-@cindex implicit rule search algorithm
+@cindex implicit rule, search algorithm
@cindex search algorithm, implicit rule
Here is the procedure @code{make} uses for searching for an implicit rule
@menu
* Archive Members:: Archive members as targets.
* Archive Update:: The implicit rule for archive member targets.
-* !!! :: the .X.a kludge
+* Archive Suffix Rules:: You can write a special kind of suffix rule
+ for updating archives.
@end menu
@node Archive Members, Archive Update, , Archives
archive @file{foo.a} as a @emph{member} named @file{bar.o}.
When this rule is chained with others, the result is very powerful.
-Thus, @samp{make "foo.a(bar.o)"} (the quotes are need to protect the
+Thus, @samp{make "foo.a(bar.o)"} (the quotes are needed to protect the
@samp{(} and @samp{)} from being interpreted specially by the shell) in
the presence of a file @file{bar.c} is enough to cause the following
commands to be run, even without a makefile:
* Archive Symbols:: How to update archive symbol directories.
@end menu
+@node Archive Suffix Rules
+@subsection
+@c !!! new section here for .X.a
+
@node Archive Symbols, , , Archive Update
@subsection Updating Archive Symbol Directories
@cindex __.SYMDEF
@node Features, Missing, Archives, Top
@chapter Features of GNU @code{make}
@cindex features of GNU @code{make}
+@cindex portability
+@cindex compatibility
Here is a summary of the features of GNU @code{make}, for comparison
-with and credit to other versions of @code{make}. We consider the features
-of @code{make} in 4.2 BSD systems as a baseline.
+with and credit to other versions of @code{make}. We consider the
+features of @code{make} in 4.2 BSD systems as a baseline. If you are
+concerned with writing portable makefiles, you should use only the
+features of @code{make} @emph{not} listed here or in @ref{Missing}.
Many features come from the version of @code{make} in System V.
@item
Included makefiles. @xref{Include, ,Including Other Makefiles}.
+Allowing multiple files to be included with a single directive is a GNU
+extension.
@item
Variables are read from and communicated via the environment.
@cindex features, missing
The @code{make} programs in various other systems support a few features
-that are not implemented in GNU @code{make}. Draft 11.1 of the POSIX.2
+that are not implemented in GNU @code{make}. Draft 11.2 of the POSIX.2
standard which specifies @code{make} does not require any of these
features.@refill
This appendix summarizes the directives, text manipulation functions,
and special variables which GNU @code{make} understands.
-@xref{Special Targets}, and @ref{Catalogue of Rules, ,Catalogue of
-Implicit Rules}, for other summaries.
+@xref{Special Targets}, @ref{Catalogue of Rules, ,Catalogue of Implicit Rules},
+and @ref{Options Summary, ,Summary of Options}.
+for other summaries.
Here is a summary of the directives GNU @code{make} recognizes:
The default list of suffixes before @code{make} reads any makefiles.
@end table
-@c !!! this is a pretty lame example --roland
@node Complex Makefile, Concept Index, Quick Reference, Top
-@appendix A Complex Makefile Example
+@appendix Complex Makefile Example
Here is the makefile for the GNU @code{tar} program. This is a
moderately complex makefile.
@group
tar: $(OBJS)
- $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS)
+ $(CC) $(LDFLAGS) -o $@@ $(OBJS) $(LIBS)
@end group
@group
rmt: rmt.c
- $(CC) $(CFLAGS) $(LDFLAGS) -o $@ rmt.c
+ $(CC) $(CFLAGS) $(LDFLAGS) -o $@@ rmt.c
@end group
@group
@group
testpad: testpad.o
- $(CC) -o $@ testpad.o
+ $(CC) -o $@@ testpad.o
@end group
@group
projects / platform / upstream / make.git / commitdiff