@smallbook
@c %**end of header
-@set EDITION 0.37
+@set EDITION 0.38
@set VERSION 3.63 Beta
-@set UPDATED 13 November 1992
+@set UPDATED 17 November 1992
@set UPDATE-MONTH November 1992
@c finalout
@c Combine the variable and function indices:
@synindex vr fn
+@c Combine the program and function indices:
+@synindex pg fn
@ifinfo
This file documents the GNU Make utility, which determines
Here is a straightforward makefile that describes the way an
executable file called @code{edit} depends on eight object files
which, in turn, depend on eight C source and three header files.
-@cindex @code{edit}
In this example, all the C files include @file{defs.h}, but only those
defining editing commands include @file{command.h}, and only low
level files that change the editor buffer include @file{buffer.h}.
-@cindex @file{defs.h}
-@cindex @file{command.h}
-@cindex @file{buffer.h}
@example
@group
make clean
@end example
-@cindex @file{main.o}
-@cindex @file{kbd.o}
-@cindex @file{main.c}
In the example makefile, the targets include the executable file
@samp{edit}, and the object files @samp{main.o} and @samp{kbd.o}. The
dependencies are files such as @samp{main.c} and @samp{defs.h}.
Targets}, for information about this kind of target. @xref{Errors, ,
Errors in Commands}, to see how to cause @code{make} ignore errors
from @code{rm}.
-@cindex @samp{clean} target
+@cindex @code{clean} target
@pindex rm @r{(shell command)}
@node How Make Works, Variables Simplify, Simple Makefile, Introduction
link @file{edit}. If we change the file @file{command.h} and run
@code{make}, @code{make} will recompile the object files @file{kbd.o},
@file{command.o} and @file{files.o} and then link the file @file{edit}.
-@cindex @file{insert.c}
-@cindex @file{insert.o}
-@cindex @file{files.o}
@node Variables Simplify, make Deduces, How Make Works, Introduction
@section Variables Make Makefiles Simpler
compiling a program: for example, how to delete all the object files
and executables so that the directory is @samp{clean}.
-@cindex @samp{clean} target
+@cindex @code{clean} target
Here is how we
could write a @code{make} rule for cleaning our example editor:
@end itemize
@cindex comments, in makefile
-@cindex @samp{#} (comments), in makefile
+@cindex @code{#} (comments), in makefile
@item
@samp{#} in a line of a makefile starts a @dfn{comment}. It and the rest of
the line are ignored, except that a trailing backslash not escaped by
@pindex GNUmakefile
@pindex makefile
-@cindex @file{README}
+@cindex @code{README}
Normally you should call your makefile either @file{makefile} or
@file{Makefile}. (We recommend @file{Makefile} because it appears
prominently near the beginning of a directory listing, right near other
than that of somehow appending the dependencies to the end of the main
makefile as has been traditionally done with other versions of
@code{make}.
-@cindex generating dependencies automatically
-@cindex dependencies, generating automatically
+@cindex dependencies, automatic generation
@cindex @code{-I}
If the specified name does not start with a slash, and the file is not
@node MAKEFILES Variable, Remaking Makefiles, Include, Makefiles
@section The Variable @code{MAKEFILES}
@cindex makefiles (@code{MAKEFILES} variable)
-@cindex including makefiles (@code{MAKEFILES} variable)
+@cindex including (@code{MAKEFILES} variable)
@vindex MAKEFILES
If the environment variable @code{MAKEFILES} is defined, @code{make}
.DEFAULT:
@@$(MAKE) -f Makefile $@@
@end example
-@cindex @code{foo}
-@cindex @code{bar}
-@cindex @code{frobnicate}
If you say @samp{make foo}, @code{make} will find @file{GNUmakefile},
read it, and see that to make @file{foo}, it needs to run the command
cc -c -g foo.c
@end example
-@cindex @file{foo.o}
-@cindex @file{foo.c}
-@cindex @file{defs.h}
Its target is @file{foo.o} and its dependencies are @file{foo.c} and
@file{defs.h}. It has one command, which is @samp{cc -c -g foo.c}.
The command line starts with a tab to identify it as a command.
same. @xref{Commands, ,Writing the Commands in Rules}.
@cindex dollar signs in rules
-@cindex @samp{$} in rules
-@cindex rules, and @samp{$}
+@cindex @code{$} in rules
+@cindex rules, 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}).
Wildcards can be used in the commands of a rule, where they are expanded
by the shell. For example, here is a rule to delete all the object files:
-@cindex @file{clean}
@example
@group
touch print
@end example
-@cindex @file{print}
+@cindex @code{print} target
@pindex lpr @r{(shell command)}
@pindex touch @r{(shell command)}
@noindent
Wildcard expansion does not happen when you define a variable. Thus, if
you write this:
-@cindex @code{objects}
@example
objects = *.o
@end example
foo : $(objects)
cc -o foo $(CFLAGS) $(objects)
@end example
-@cindex @file{foo}
-@cindex @code{objects}
@noindent
The value of @code{objects} is the actual string @samp{*.o}. Wildcard
@vindex VPATH
@findex vpath
@cindex vpath
-@cindex search path for dependencies (VPATH)
-@cindex directory search (VPATH)
+@cindex search path for dependencies (@code{VPATH})
+@cindex directory search (@code{VPATH})
For large systems, it is often desirable to put sources in a separate
directory from the binaries. The @dfn{directory search} features of
@node Commands/Search, Implicit/Search, Selective Search, Directory Search
@subsection Writing Shell Commands with Directory Search
@cindex shell commands, and directory search
-@cindex directory search (VPATH), and shell commands
+@cindex directory search, and shell commands
When a dependency is found in another directory through directory search,
this cannot change the commands of the rule; they will execute as written.
@node Implicit/Search, Libraries/Search, Commands/Search, Directory Search
@subsection Directory Search and Implicit Rules
-@cindex directory search (VPATH) and implicit rules
-@cindex search in directories (VPATH) with implicit rules
-@cindex implicit rules with directory search (VPATH)
+@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}
The search through the directories specified in @code{VPATH} or with
@code{vpath} happens also during consideration of implicit rules
@node Libraries/Search, , Implicit/Search, Directory Search
@subsection Directory Search for Link Libraries
-@cindex link libraries, directory search (VPATH)
-@cindex libraries for linking, directory search (VPATH)
-@cindex directory search (VPATH), link libraries
-@cindex search in directories (VPATH), link libraries
+@cindex link libraries, and directory search
+@cindex libraries for linking, directory search
+@cindex directory search, and link libraries
+@cindex @code{VPATH}, and link libraries
+@cindex search path, and link libraries
@cindex @code{-l} (library search)
Directory search applies in a special way to libraries used with the
commands will be executed every time the target comes up for remaking.
Here is an example:
-@cindex @file{clean}
@example
@group
clean:
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 @file{all}
+@cindex @code{all}
@example
all : prog1 prog2 prog3
prog3 : prog3.o sort.o utils.o
cc -o prog3 prog3.o sort.o utils.o
@end example
-@cindex @file{prog1}
-@cindex @file{prog2}
-@cindex @file{prog3}
-@cindex @file{prog1.o}
-@cindex @file{prog2.o}
-@cindex @file{prog3.o}
-@cindex @file{sort.o}
-@cindex @file{utils.o}
@noindent
Now you can say just @samp{make} to remake all three programs, or specify
cleandiff :
rm *.diff
@end example
-@cindex @file{cleanall}
-@cindex @file{cleanobj}
-@cindex @file{cleandiff}
@node Force Targets, Empty Targets, Phony Targets, Rules
@section Rules without Commands or Dependencies
@cindex force targets
@cindex targets, force
-@cindex @file{FORCE}
-@cindex rules, without commands or dependencies
+@cindex @code{FORCE}
+@cindex rules, 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
lpr -p $?
touch print
@end example
-@cindex @file{print}
+@cindex @code{print} target
@pindex lpr @r{(shell command)}
@pindex touch @r{(shell command)}
@example
kbd.o command.o files.o: command.h
@end example
-@cindex @file{kbd.o}
-@cindex @file{command.o}
-@cindex @file{files.o}
-@cindex @file{kbd.h}
@noindent
gives an additional dependency to each of the three object files
generate text.g -$(subst output,,$@@) > $@@
@end group
@end example
-@cindex @file{bigoutput}
-@cindex @file{littleoutput}
-@cindex @file{text.g}
-@cindex @code{generate}
@findex subst
@noindent
variable named @code{objects} containing a list of all the compiler output
files in the system being made. An easy way to say that all of them must
be recompiled if @file{config.h} changes is to write the following:
-@cindex @code{objects}
-@cindex @file{config.h}
-@cindex @file{foo.o}
-@cindex @file{bar.o}
-@cindex @file{defs.h}
-@cindex @file{test.h}
@example
objects = foo.o bar.o
$(objects) : $(extradeps)
@end group
@end example
-@cindex @code{extradeps}
@noindent
means that the command @samp{make extradeps=foo.h} will consider
@node Static Usage, Static versus Implicit, , Static Pattern
@subsection Syntax of Static Pattern Rules
@cindex static pattern rule, syntax of
-@cindex pattern rule, static (not implicit), syntax of
+@cindex pattern rules, static, syntax of
Here is the syntax of a static pattern rule:
pattern must match exactly. For example, the target @file{foo.o} matches
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 @file{foo.o}
-@cindex @file{foo.c}
-@cindex @file{foo.out}
The dependency names for each target are made by substituting the stem
for the @samp{%} in each dependency pattern. For example, if one
to write a dependency pattern that does not contain @samp{%}; then this
dependency is the same for all targets.
-@cindex backslash (@samp{\}), to quote @samp{%}
-@cindex @samp{\} (backslash), to quote @samp{%}
-@cindex quoting @samp{%} with @samp{\} (backslash)
-@cindex @samp{%}, quoting with @samp{\} (backslash)
+@cindex backslash (@code{\}), to quote @code{%}
+@cindex @code{\} (backslash), to quote @code{%}
+@cindex quoting @code{%} with @code{\}
+@cindex @code{%}, quoting with @code{\} (backslash)
@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
$(CC) -c $(CFLAGS) $< -o $@@
@end group
@end example
-@cindex @code{objects}
@noindent
Here @samp{$<} is the automatic variable that holds the name of the
emacs -f batch-byte-compile $<
@end example
@pindex emacs
-@cindex @code{files}
-@cindex @file{foo.elc}
-@cindex @file{bar.o}
-@cindex @file{lose.o}
@noindent
Here the result of @samp{$(filter %.o,$(files))} is @file{bar.o lose.o},
@node Double-Colon, , Multiple Rules, Rules
@section Double-Colon Rules
@cindex double-colon rules
-@cindex rules, double-colon (@samp{::})
-@cindex multiple, independent rules for one target
-@cindex @samp{::} rules (double-colon)
+@cindex rules, double-colon (@code{::})
+@cindex multiple rules for one target (@code{::})
+@cindex @code{::} rules (double-colon)
@dfn{Double-colon} rules are rules written with @samp{::} instead of
@samp{:} after the target names. They are handled differently from
@cindex comments, in commands
@cindex commands, comments in
-@cindex @samp{#} (comments), in commands
+@cindex @code{#} (comments), in commands
The shell that is in use determines whether comments can be written on
command lines, and what syntax they use. When the shell is
@file{/bin/sh}, a @samp{#} starts a comment that extends to the end of
@section Command Echoing
@cindex echoing of commands
@cindex silent operation
-@cindex @samp{@@} (in commands)
+@cindex @code{@@} (in commands)
@cindex command echoing
@cindex printing of commands
foo : bar/lose
cd bar; gobble lose > ../foo
@end example
-@cindex @file{foo}
-@cindex @file{bar}
-@cindex @file{lose}
-@cindex @code{gobble}
-@cindex commands, backslash (@samp{\}) in
+@cindex commands, backslash (@code{\}) in
@cindex commands, quoting newlines in
-@cindex backslash (@samp{\}), in commands
-@cindex @samp{\} (backslash), in commands
+@cindex backslash (@code{\}), in commands
+@cindex @code{\} (backslash), in commands
@cindex quoting newlines 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.
directory exists. If the directory already exists, @code{mkdir} will
report an error, but you probably want @code{make} to continue regardless.
-@cindex @samp{-} (in commands)
+@cindex @code{-} (in commands)
To ignore errors in a command line, write a @samp{-} at the beginning of
the line's text (after the initial tab). The @samp{-} is discarded before
the command is passed to the shell for execution.
-rm -f *.o
@end group
@end example
-@cindex @file{clean}
@pindex rm @r{(shell command)}
@noindent
subsystem:
cd subdir; $(MAKE)
@end example
-@cindex @file{subsystem}
-@cindex @file{subdir}
@noindent
or, equivalently, this (@pxref{Options Summary, ,Summary of Options}):
cd subdir; $(MAKE)
@end group
@end example
-@cindex @file{subsystem}
-@cindex @file{subdir}
The value of this variable is the file name with which @code{make} was
invoked. If this file name was @file{/bin/make}, then the command executed
really want it to do is run @samp{@w{cd subdir;} @w{make -t}}; but that would
require executing the command, and @samp{-t} says not to execute
commands.@refill
-@cindex @code{-t} (vs. recursion)
+@cindex @code{-t}, and recursion
@cindex recursion, and @code{-t}
The special feature makes this do what you want: whenever a command
@code{.EXPORT_ALL_VARIABLES} instead of using the @code{export} directive.
This will be ignored by old @code{make}s, while the @code{export}
directive will cause a syntax error.@refill
-@cindex compatibility (@code{.EXPORT_ALL_VARIABLES})
+@cindex compatibility in exporting
Likewise, you can use @code{unexport} by itself to tell @code{make}
@emph{not} to export variables by default. Since this is the default
@node Options/Recursion, -w Option, Variables/Recursion, Recursion
@subsection Communicating Options to a Sub-@code{make}
-@cindex options and recursion
+@cindex options, and recursion
@cindex recursion, and options
@vindex MAKEFLAGS
mv y.tab.c $@@
endef
@end example
-@cindex @code{run-yacc}
@pindex yacc
-@cindex @file{y.tab.c}
@noindent
Here @code{run-yacc} is the name of the variable being defined;
foo.c : foo.y
$(run-yacc)
@end example
-@cindex @file{foo.c}
-@cindex @file{foo.y}
@noindent
@samp{foo.y} will be substituted for the variable @samp{$^} when it occurs in
* Environment:: Variable values can come from the environment.
@end menu
-@c !!! I have added index entries up thru here as of 11-16-92. -rm
-
@node Reference, Flavors, , Using Variables
@section Basics of Variable References
+@cindex variables, how to reference
+@cindex reference to variables
+@cindex @code{$} (variables)
+@cindex dollar sign (@code{$}), and variables
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
@end example
@noindent
-could be used to compile a C program @file{prog.c}. Since spaces around
+could be used to compile a C program @file{prog.c}. Since spaces before
the variable value are ignored in variable assignments, the value of
@code{foo} is precisely @samp{c}. (Don't actually write your makefiles
this way!)
@section The Two Flavors of Variables
@cindex flavors of variables
@cindex recursive variable expansion
-@cindex variable flavors
+@cindex variables, flavors
+@cindex recursively expanded variables
+@cindex variables, recursively expanded
There are two ways that a variable in GNU @code{make} can have a value;
we call them the two @dfn{flavors} of variables. The two flavors are
distinguished in how they are defined and in what they do when expanded.
+@cindex =
The first flavor of variable is a @dfn{recursively expanded} variable.
Variables of this sort are defined by lines using @samp{=}
(@pxref{Setting, ,Setting Variables}) or by the @code{define} directive
@noindent
because it will cause an infinite loop in the variable expansion.
(Actually @code{make} detects the infinite loop and reports an error.)
+@cindex loops in variable expansion
+@cindex variables, loops in expansion
-Another disadvantage is that any functions (@pxref{Functions, ,Functions for Transforming Text})
+Another disadvantage is that any functions
+(@pxref{Functions, ,Functions for Transforming Text})
referenced in the definition will be executed every time the variable is
expanded. This makes @code{make} run slower; worse, it causes the
@code{wildcard} and @code{shell} functions to give unpredictable results
variables, there is another flavor: simply expanded variables.
@cindex simply expanded variables
+@cindex variables, simply expanded
+@cindex :=
@dfn{Simply expanded variables} are defined by lines using @samp{:=}
(@pxref{Setting, ,Setting Variables}).
The value of a simply expanded variable is scanned
(@xref{Variables/Recursion, , Communicating Variables to a
Sub-@code{make}}, for information about @code{MAKELEVEL}.)
+@vindex MAKELEVEL
+@vindex MAKE
@example
@group
ifeq (0,$@{MAKELEVEL@})
more predictable because they work like variables in most programming
languages. They allow you to redefine a variable using its own value (or
its value processed in some way by one of the expansion functions) and to
-use the expansion functions much more efficiently (@pxref{Functions, ,Functions for Transforming Text}).
+use the expansion functions much more efficiently
+(@pxref{Functions, ,Functions for Transforming Text}).
+@cindex spaces, in variable values
+@cindex variables, spaces in values
You can also use them to introduce controlled leading or trailing spaces
into variable values. Such spaces are discarded from your input before
substitution of variable references and function calls; this means you can
@subsection Substitution References
@cindex modified variable reference
@cindex substitution variable reference
+@cindex variables, modified reference
+@cindex variables, substitution reference
+@cindex variables, substituting suffix in
+@cindex suffix, substituting in variables
A @dfn{substitution reference} substitutes the value of a variable with
alterations that you specify. It has the form
@samp{$(@var{var}:@var{a}=@var{b})} (or
substitution references as well as @code{patsubst} for compatibility with
other implementations of @code{make}.
+@findex patsubst
Another type of substitution reference lets you use the full power of
the @code{patsubst} function. It has the same form
@samp{$(@var{var}:@var{a}=@var{b})} described above, except that now
@subsection Computed Variable Names
@cindex nested variable reference
@cindex computed variable name
-@cindex variable reference, nested
+@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
Computed variable names are a complicated concept needed only for
sophisticated makefile programming. For most purposes you need not
@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
Variables can get values in several different ways:
@item
Several @dfn{automatic} variables are given new values for each rule.
-Each of these has a single conventional use. @xref{Automatic, ,Automatic Variables}.
+Each of these has a single conventional use.
+@xref{Automatic, ,Automatic Variables}.
@item
Several variables have constant initial values.
@section The @code{override} Directive
@findex override
@cindex overriding with @code{override}
+@cindex variables, 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
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
characters to be included in the value, which is convenient for defining
-canned sequences of commands (@pxref{Sequences, ,Defining Canned Command Sequences}).
+canned sequences of commands
+(@pxref{Sequences, ,Defining Canned Command Sequences}).
The @code{define} directive is followed on the same line by the name of the
variable and nothing more. The value to give the variable appears on the
@node Environment, , Defining, Using Variables
@section Variables from the Environment
+@cindex variables, 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
and value. But an explicit assignment in the makefile, or with a command
argument, overrides the environment. (If the @samp{-e} flag is specified,
then values from the environment override assignments in the makefile.
-@xref{Options Summary, ,Summary of Options}. But this is not recommended practice.)
+@xref{Options Summary, ,Summary of Options}.
+But this is not recommended practice.)
Thus, by setting the variable @code{CFLAGS} in your environment, you can
cause all C compilations in most makefiles to use the compiler switches you
@node Conditional Example, Conditional Syntax, , Conditionals
@section Example of a Conditional
-The following example of a conditional tells @code{make} to use one set of libraries if the
-@code{CC} variable is @samp{gcc}, and a different set of libraries
-otherwise. It works by controlling which of two command lines will be used
-as the command for a rule. The result is that @samp{CC=gcc} as an argument
-to @code{make} changes not only which compiler is used but also which
-libraries are linked.
+The following example of a conditional tells @code{make} to use one set
+of libraries if the @code{CC} variable is @samp{gcc}, and a different
+set of libraries otherwise. It works by controlling which of two
+command lines will be used as the command for a rule. The result is
+that @samp{CC=gcc} as an argument to @code{make} changes not only which
+compiler is used but also which libraries are linked.
@example
libs_for_gcc = -lgnu
You can write a conditional that tests @code{make} command flags such as
@samp{-t} by using the variable @code{MAKEFLAGS} together with the
-@code{findstring} function. This is useful when @code{touch} is not
-enough to make a file appear up to date.
+@code{findstring} function
+(@pxref{Text Functions, , Functions for String Substitution and Analysis}).
+This is useful when @code{touch} is not enough to make a file appear up
+to date.
The @code{findstring} function determines whether one string appears as a
substring of another. If you want to test for the @samp{-t} flag,
@node Syntax of Functions, Text Functions, , Functions
@section Function Call Syntax
-@cindex $ (function call)
-@cindex arguments
+@cindex @code{$} (function call)
+@cindex arguments of functions
+@cindex functions, syntax of
A function call resembles a variable reference. It looks like this:
@node Text Functions, Filename Functions, Syntax of Functions, Functions
@section Functions for String Substitution and Analysis
+@cindex functions, for text
Here are some functions that operate on strings:
@var{replacement} also contains a @samp{%}, the @samp{%} is replaced
by the text that matched the @samp{%} in @var{pattern}.@refill
-@cindex quoting @samp{%} in @code{patsubst}
-@cindex @samp{%}, quoting in @code{patsubst}
+@cindex backslash (@code{\}), to quote @samp{%}
+@cindex @code{\} (backslash), to quote @samp{%}
+@cindex quoting @code{%} in @code{patsubst}
+@cindex @code{%}, quoting 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.
@end example
@item $(strip @var{string})
+@cindex stripping whitespace
+@cindex whitespace, stripping
+@cindex spaces, stripping
@findex strip
Removes leading and trailing whitespace from @var{string} and replaces
each internal sequence of one or more whitespace characters with a
@item $(findstring @var{find},@var{in})
@findex findstring
+@cindex searching for strings
+@cindex finding strings
+@cindex strings, searching for
Searches @var{in} for an occurrence of @var{find}. If it occurs, the
value is @var{find}; otherwise, the value is empty. You can use this
function in a conditional to test for the presence of a specific
@need 750
@findex filter
+@cindex filtering words
+@cindex words, filtering
@item $(filter @var{pattern}@dots{},@var{text})
Removes all whitespace-separated words in @var{text} that do
@emph{not} match any of the @var{pattern} words, returning only
@item $(filter-out @var{pattern}@dots{},@var{text})
@findex filter-out
+@cindex filtering out words
+@cindex words, filtering out
Removes all whitespace-separated words in @var{text} that @emph{do}
match the @var{pattern} words, returning only the words that @emph{do
not} match. This is the exact opposite of the @code{filter}
@need 1500
@findex sort
+@cindex sorting words
@item $(sort @var{list})
Sorts the words of @var{list} in lexical order, removing duplicate
words. The output is a list of words separated by single spaces.
@cindex removing duplicate words
@cindex duplicate words, removing
+@cindex words, removing duplicates
Incidentally, since @code{sort} removes duplicate words, you can use
it for this purpose even if you don't care about the sort order.
@end table
@node Filename Functions, Foreach Function, Text Functions, Functions
@section Functions for File Names
+@cindex functions, for file names
+@cindex file name functions
Several of the built-in expansion functions relate specifically to
taking apart file names or lists of file names.
@table @code
@item $(dir @var{names}@dots{})
@findex dir
+@cindex directory part
+@cindex file name, directory part
Extracts the directory-part of each file name in @var{names}. The
directory-part of the file name is everything up through (and
including) the last slash in it. If the file name contains no slash,
@item $(notdir @var{names}@dots{})
@findex notdir
+@cindex file name, nondirectory part
+@cindex nondirectory part
Extracts all but the directory-part of each file name in @var{names}.
If the file name contains no slash, it is left unchanged. Otherwise,
everything through the last slash is removed from it.
@item $(suffix @var{names}@dots{})
@findex suffix
+@cindex suffix, function to find
+@cindex file name suffix
Extracts the suffix of each file name in @var{names}. If the file name
contains a period, the suffix is everything starting with the last
period. Otherwise, the suffix is the empty string. This frequently
@item $(basename @var{names}@dots{})
@findex basename
+@cindex basename
+@cindex file name, basename of
Extracts all but the suffix of each file name in @var{names}. If the
file name contains a period, the basename is everything starting up to
(and not including) the last period. Otherwise, the basename is the
@c plural convention with dots (be consistent)
@item $(addsuffix @var{suffix},@var{names}@dots{})
@findex addsuffix
+@cindex suffix, adding
+@cindex file name suffix, adding
The argument @var{names} is regarded as a series of names, separated
by whitespace; @var{suffix} is used as a unit. The value of
@var{suffix} is appended to the end of each individual name and the
@item $(addprefix @var{prefix},@var{names}@dots{})
@findex addprefix
+@cindex prefix, adding
+@cindex file name prefix, adding
The argument @var{names} is regarded as a series of names, separated
by whitespace; @var{prefix} is used as a unit. The value of
@var{prefix} is prepended to the front of each individual name and the
@item $(join @var{list1},@var{list2})
@findex join
+@cindex joining lists of words
+@cindex words, joining lists
Concatenates the two arguments word by word: the two first words (one
from each argument) concatenated form the first word of the result, the
two second words form the second word of the result, and so on. So the
@item $(word @var{n},@var{text})
@findex word
+@cindex words, selecting
+@cindex selecting words
Returns the @var{n}th word of @var{text}. The legitimate values of
@var{n} start from 1. If @var{n} is bigger than the number of words
in @var{text}, the value is empty. For example,
@c Following item phrased to prevent overfull hbox. --RJC 17 Jul 92
@item $(words @var{text})
@findex words
+@cindex words, finding number
Returns the number of words in @var{text}.
Thus, the last word of @var{text} is
@w{@code{$(word $(words @var{text}),@var{text})}}.@refill
@item $(firstword @var{names}@dots{})
@findex firstword
+@cindex words, extracting first
The argument @var{names} is regarded as a series of names, separated
by whitespace. The value is the first name in the series. The rest
of the names are ignored.
@item $(wildcard @var{pattern})
@findex wildcard
+@cindex wildcards, 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 Foreach Function, Origin Function, Filename Functions, Functions
@section The @code{foreach} Function
@findex foreach
+@cindex words, iterating over
The @code{foreach} function is very different from other functions. It
causes one piece of text to be used repeatedly, each time with a different
@node Origin Function, Shell Function, Foreach Function, Functions
@section The @code{origin} Function
@findex origin
+@cindex variables, origin of
+@cindex origin of variable
The @code{origin} function is unlike most other functions in that it does
not operate on the values of variables; it tells you something @emph{about}
@item default
if @var{variable} has a default definition, as is usual with @code{CC}
-and so on. @xref{Implicit Variables, ,Variables Used by Implicit Rules}. Note that if you have
-redefined a default variable, the @code{origin} function will return
-the origin of the later definition.
+and so on. @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
+Note that if you have redefined a default variable, the @code{origin}
+function will return the origin of the later definition.
@item environment
@findex shell
@cindex command expansion
@cindex backquotes
+@cindex shell commands, 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}
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
@node Goals, Instead of Execution, Makefile Arguments, Running
@section Arguments to Specify the Goals
-@cindex goal
+@cindex goal, how to specify
The @dfn{goals} are the targets that @code{make} should strive ultimately
to update. Other targets are updated as well if they appear as
@table @file
@item all
+@cindex @code{all} @r{(standard target)}
Make all the top-level targets the makefile knows about.
@item clean
+@cindex @code{clean} @r{(standard target)}
Delete all files that are normally created by running @code{make}.
@item mostlyclean
+@cindex @code{mostlyclean} @r{(standard target)}
Like @samp{clean}, but may refrain from deleting a few files that people
normally don't want to recompile. For example, the @samp{mostlyclean}
target for GCC does not delete @file{libgcc.a}, because recompiling it
is rarely necessary and takes a lot of time.
@item distclean
+@cindex @code{distclean} @r{(standard target)}
@itemx realclean
+@cindex @code{realclean} @r{(standard target)}
@itemx clobber
+@cindex @code{clobber} @r{(standard target)}
Any of these three might be defined to delete everything that would
not be part of a standard distribution. For example, this would
delete configuration files or links that you would normally create as
these files.
@item install
+@cindex @code{install} @r{(standard target)}
Copy the executable file into a directory that users typically search
for commands; copy any auxiliary files that the executable uses into
the directories where it will look for them.
@item print
+@cindex @code{print} @r{(standard target)}
Print listings of the source files that have changed.
@item tar
+@cindex @code{tar} @r{(standard target)}
Create a tar file of the source files.
@item shar
+@cindex @code{shar} @r{(standard target)}
Create a shell archive (shar file) of the source files.
@item dist
+@cindex @code{dist} @r{(standard target)}
Create a distribution file of the source files. This might
be a tar file, or a shar file, or a compressed version of one of the
above, or even more than one of the above.
@item TAGS
+@cindex @code{TAGS} @r{(standard target)}
Update a tags table for this program.
@item check
+@cindex @code{check} @r{(standard target)}
@itemx test
+@cindex @code{test} @r{(standard target)}
Perform self tests on the program this makefile builds.
@end table
@node Instead of Execution, Avoiding Compilation, Goals, Running
@section Instead of Executing the Commands
+@cindex execution, instead of
+@cindex commands, instead of executing
The makefile tells @code{make} how to tell whether a target is up to date,
and how to update each target. But updating the targets is not always
@itemx --touch
@cindex @code{--touch}
@cindex touching files
+@cindex targets, 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
@cindex @code{--what-if}
@cindex @code{-W}
@cindex what if
+@cindex files, assuming new
``What if''. Each @samp{-W} flag is followed by a file name. The given
files' modification times are recorded by @code{make} as being the present
time, although the actual modification times remain the same.
@node Avoiding Compilation, Overriding, Instead of Execution, Running
@section Avoiding Recompilation of Some Files
@cindex @code{-o}
+@cindex @code{--old-file}
+@cindex files, assuming old
+@cindex files, avoiding recompilation of
+@cindex recompilation, avoiding
Sometimes you may have changed a source file but you do not want to
recompile all the files that depend on it. For example, suppose you add a
@node Overriding, Testing, Avoiding Compilation, Running
@section Overriding Variables
@cindex overriding variables with arguments
+@cindex variables, overriding with arguments
+@cindex command line variables
+@cindex variables, 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}.
@node Testing, Options Summary, Overriding, Running
@section Testing the Compilation of a Program
@cindex testing compilation
+@cindex compilation, testing
Normally, when an error happens in executing a shell command, @code{make}
gives up immediately, returning a nonzero status. No further commands are
@section Summary of Options
@cindex options
@cindex flags
+@cindex switches
Here is a table of all the options @code{make} understands:
@table @samp
@item -b
+@cindex @code{-b}
@itemx -m
+@cindex @code{-m}
These options are ignored for compatibility with other versions of @code{make}.
@item -C @var{dir}
+@cindex @code{-C}
@itemx --directory @var{dir}
+@cindex @code{--directory}
Change to directory @var{dir} before reading the makefiles. If multiple
@samp{-C} options are specified, each is interpreted relative to the
previous one: @samp{-C / -C etc} is equivalent to @samp{-C /etc}.
(@pxref{Recursion, ,Recursive Use of @code{make}}).
@item -d
+@cindex @code{-d}
@itemx --debug
+@cindex @code{--debug}
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,
@code{make} decides what to do.
@item -e
+@cindex @code{-e}
@item --environment-overrides
+@cindex @code{--environment-overrides}
Give variables taken from the environment precedence
-over variables from makefiles. @xref{Environment, ,Variables from the Environment}.
+over variables from makefiles.
+@xref{Environment, ,Variables from the Environment}.
@item -f @var{file}
+@cindex @code{-f}
@item --file @var{file}
+@cindex @code{--file}
@item --makefile @var{file}
+@cindex @code{--makefile}
Read the file named @var{file} as a makefile.
@xref{Makefiles, ,Writing Makefiles}.
@item -h
+@cindex @code{-h}
@itemx --help
-Remind you of the options that @code{make} understands and then exits.
+@cindex @code{--help}
+Remind you of the options that @code{make} understands and then exit.
@item -i
+@cindex @code{-i}
@itemx --ignore-errors
+@cindex @code{--ignore-errors}
Ignore all errors in commands executed to remake files.
@xref{Errors, ,Errors in Commands}.
@item -I @var{dir}
+@cindex @code{-I}
@item --include-dir @var{dir}
+@cindex @code{--include-dir}
Specifies a directory @var{dir} to search for included makefiles.
@xref{Include, ,Including Other Makefiles}. If several @samp{-I}
options are used to specify several directories, the directories are
searched in the order specified.
@item -j [@var{jobs}]
+@cindex @code{-j}
@itemx --jobs [@var{jobs}]
+@cindex @code{--jobs}
Specifies the number of jobs (commands) to run simultaneously. With no
argument, @code{make} runs as many jobs simultaneously as possible. If
there is more than one @samp{-j} option, the last one is effective.
for more information on how commands are run.
@item -k
+@cindex @code{-k}
@itemx --keep-going
+@cindex @code{--keep-going}
Continue as much as possible after an error. While the target that
failed, and those that depend on it, cannot be remade, the other
dependencies of these targets can be processed all the same.
@xref{Testing, ,Testing the Compilation of a Program}.
@item -l [@var{load}]
+@cindex @code{-l}
@itemx --load-average [@var{load}]
+@cindex @code{--load-average}
@itemx --max-load [@var{load}]
+@cindex @code{--max-load}
Specifies that no new jobs (commands) should be started if there are
others jobs running and the load average is at least @var{load} (a
floating-point number). With no argument, removes a previous load
limit. @xref{Parallel, ,Parallel Execution}.
@item -n
+@cindex @code{-n}
@itemx --just-print
+@cindex @code{--just-print}
@itemx --dry-run
+@cindex @code{--dry-run}
@itemx --recon
+@cindex @code{--recon}
Print the commands that would be executed, but do not execute them.
@xref{Instead of Execution, ,Instead of Executing the Commands}.
@item -o @var{file}
+@cindex @code{-o}
@itemx --old-file @var{file}
+@cindex @code{--old-file}
@itemx --assume-old @var{file}
+@cindex @code{--assume-old}
Do not remake the file @var{file} even if it is older than its
dependencies, and do not remake anything on account of changes in
@var{file}. Essentially the file is treated as very old and its rules
Some Files}.@refill
@item -p
+@cindex @code{-p}
@itemx --print-data-base
+@cindex @code{--print-data-base}
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
trying to remake any files, use @w{@samp{make -p -f /dev/null}}.
@item -q
+@cindex @code{-q}
@itemx --question
+@cindex @code{--question}
``Question mode''. Do not run any commands, or print anything; just
return an exit status that is zero if the specified targets are already
up to date, nonzero otherwise. @xref{Instead of Execution, ,Instead of
Executing the Commands}.@refill
@item -r
+@cindex @code{-r}
@itemx --no-builtin-rules
+@cindex @code{--no-builtin-rules}
Eliminate use of the built-in implicit rules (@pxref{Implicit Rules,
,Using Implicit Rules}). You can still define your own by writing
pattern rules (@pxref{Pattern Rules, ,Defining and Redefining Pattern
@code{.SUFFIXES}, and then define your own suffix rules.
@item -s
+@cindex @code{-s}
@itemx --silent
+@cindex @code{--silent}
@itemx --quiet
+@cindex @code{--quiet}
Silent operation; do not print the commands as they are executed.
@xref{Echoing, ,Command Echoing}.
@item -S
+@cindex @code{-S}
@itemx --no-keep-going
+@cindex @code{--no-keep-going}
@itemx --stop
+@cindex @code{--stop}
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}})
or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill
@item -t
+@cindex @code{-t}
@itemx --touch
+@cindex @code{--touch}
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
@code{make}. @xref{Instead of Execution, ,Instead of Executing the Commands}.
@item -v
+@cindex @code{-v}
@itemx --version
+@cindex @code{--version}
Print the version of the @code{make} program plus a copyright, a list
of authors, and a notice that there is no warranty. After this
information is printed, continue processing normally. To get this
@w{@samp{make --version -f /dev/null}}.
@item -w
+@cindex @code{-w}
@itemx --print-directory
+@cindex @code{--print-directory}
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 @code{make} commands.
see @ref{-w Option, ,The @samp{--print-directory} Option}.)
@item -W @var{file}
+@cindex @code{-W}
@itemx --what-if @var{file}
+@cindex @code{--what-if}
@itemx --new @var{file}
+@cindex @code{--new}
@itemx --assume-new @var{file}
+@cindex @code{--assume-new}
Pretend that the target @var{file} has just been modified. When used
with the @samp{-n} flag, this shows you what would happen if you were
to modify that file. Without @samp{-n}, it is almost the same as
@node Implicit Rules, Archives, Running, Top
@chapter Using Implicit Rules
@cindex implicit rule
+@cindex rule, implicit
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
@node Using Implicit, Catalogue of Rules, , Implicit Rules
@section Using Implicit Rules
+@cindex implicit rule, how to use
+@cindex rule, implicit, how to use
To allow @code{make} to find a customary method for updating a target file,
all you have to do is refrain from specifying commands yourself. Either
Of course, when you write the makefile, you know which implicit rule you
want @code{make} to use, and you know it will choose that one because you
know which possible dependency files are supposed to exist.
-@xref{Catalogue of Rules, ,Catalogue of Implicit Rules}, for a catalogue of all the predefined implicit
-rules.
+@xref{Catalogue of Rules, ,Catalogue of Implicit Rules},
+for a catalogue of all the predefined implicit rules.
Above, we said an implicit rule applies if the required dependencies ``exist
or can be made''. A file ``can be made'' if it is mentioned explicitly in
@node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit Rules
@section Catalogue of Implicit Rules
+@cindex implicit rule, predefined
+@cindex rule, implicit, predefined
Here is a catalogue of predefined implicit rules which are always
available unless the makefile explicitly overrides or cancels them.
@table @asis
@item Compiling C programs
+@cindex C, rule to compile
+@pindex cc
+@pindex gcc
@file{@var{n}.o} is made automatically from @file{@var{n}.c} with
a command of the form @samp{$(CC) -c $(CPPFLAGS) $(CFLAGS)}.@refill
@item Compiling C++ programs
+@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++
source files instead of @samp{.C}.@refill
@item Compiling Pascal programs
+@cindex Pascal, rule to compile
+@pindex pc
@file{@var{n}.o} is made automatically from @file{@var{n}.p}
with the command @samp{$(PC) -c $(PFLAGS)}.@refill
@item Compiling Fortran and Ratfor programs
+@cindex Fortran, rule to compile
+@cindex Ratfor, rule to compile
+@pindex f77
@file{@var{n}.o} is made automatically from @file{@var{n}.r},
@file{@var{n}.F} or @file{@var{n}.f} by running the
Fortran compiler. The precise command used is as follows:@refill
@end table
@item Compiling Modula-2 programs
+@cindex Modula-2, rule to compile
+@pindex m2c
@file{@var{n}.sym} is made from @file{@var{n}.def} with a command
of the form @samp{$(M2C) $(M2FLAGS) $(DEFFLAGS)}. @file{@var{n}.o}
is made from @file{@var{n}.mod}; the form is:
@need 1200
@item Assembling and preprocessing assembler programs
+@cindex assembly, rule to compile
+@pindex as
@file{@var{n}.o} is made automatically from @file{@var{n}.s} by
running the assembler, @code{as}. The precise command is
@samp{$(AS) $(ASFLAGS)}.@refill
@w{@samp{$(CPP) $(CPPFLAGS)}}.
@item Linking a single object file
+@cindex linking, predefined rule for
@file{@var{n}} is made automatically from @file{@var{n}.o} by
running the linker @code{ld} via the C compiler. The precise command
used is @w{@samp{$(CC) $(LDFLAGS) @var{n}.o $(LOADLIBES)}}.@refill
done.@refill
@item Yacc for C programs
+@pindex yacc
+@cindex Yacc, rule to run
@file{@var{n}.c} is made automatically from @file{@var{n}.y} by
running Yacc with the command @samp{$(YACC) $(YFLAGS)}.
@item Lex for C programs
+@pindex lex
+@cindex Lex, rule to run
@file{@var{n}.c} is made automatically from @file{@var{n}.l} by
by running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}.
@end example
@item Making Lint Libraries from C, Yacc, or Lex programs
+@pindex lint
+@cindex @code{lint}, rule to run
@file{@var{n}.ln} is made from @file{@var{n}.c} with a command of
the form @w{@samp{$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i}}.
The same command is used on the C code produced from
@file{@var{n}.y} or @file{@var{n}.l}.@refill
@item @TeX{} and Web
+@cindex @TeX{}, rule to run
+@cindex Web, rule to run
+@pindex tex
+@pindex cweave
+@pindex weave
+@pindex tangle
+@pindex ctangle
@file{@var{n}.dvi} is made from @file{@var{n}.tex} with the
command @samp{$(TEX)}. @file{@var{n}.tex} is made from
@file{@var{n}.web} with @samp{$(WEAVE)}, or from @file{@var{n}.cweb}
made from @file{@var{n}.cweb} with @samp{$(CTANGLE)}.@refill
@item Texinfo and Info
+@cindex Texinfo, rule to format
+@cindex Info, rule to format
+@pindex texi2dvi
+@pindex makeinfo
@file{@var{n}.dvi} is made from @file{@var{n}.texinfo} or
@file{@var{n}.texi} with the @samp{$(TEXI2DVI)} command.
@file{@var{n}.info} is made from @file{@var{n}.texinfo} or
@file{@var{n}.texi} with the @samp{$(MAKEINFO)} command .@refill
@item RCS
+@cindex RCS, rule to extract from
+@pindex co
Any file @file{@var{n}} is extracted if necessary from an RCS file
named either @file{@var{n},v} or @file{RCS/@var{n},v}. The precise
command used is @w{@samp{$(CO) $(COFLAGS)}}. @file{@var{n}} will not be
actually exist.@refill
@item SCCS
+@cindex SCCS, rule to extract from
+@pindex get
Any file @file{@var{n}} is extracted if necessary from an SCCS file
named either @file{s.@var{n}} or @file{SCCS/s.@var{n}}. The precise
command used is @w{@samp{$(GET) $(GFLAGS)}}. The rules for SCCS are
file uses @code{LINK.@var{x}}; and the rule to preprocess a
@file{.@var{x}} file uses @code{PREPROCESS.@var{x}}.
+@vindex OUTPUT_OPTION
Every rule that produces an object file uses the variable
@code{OUTPUT_OPTION}. @code{make} defines this variable either to
contain @samp{-o $@@}, or to be empty, depending on a compile-time
@item AR
@vindex AR
Archive-maintaining program; default @samp{ar}.
+@pindex ar
@item AS
@vindex AS
Program for doing assembly; default @samp{as}.
+@pindex as
@item CC
@vindex CC
Program for compiling C programs; default @samp{cc}.
+@pindex cc
@item C++
@vindex C++
Program for compiling C++ programs; default @samp{g++}.
+@pindex g++
@item CO
@vindex CO
Program for extracting a file from RCS; default @samp{co}.
+@pindex co
@item CPP
@vindex CPP
@vindex FC
Program for compiling or preprocessing Fortran and Ratfor programs;
default @samp{f77}.
+@pindex f77
@item GET
@vindex GET
Program for extracting a file from SCCS; default @samp{get}.
+@pindex get
@item LEX
@vindex LEX
Program to use to turn Lex grammars into C programs or Ratfor programs;
default @samp{lex}.
+@pindex lex
@item PC
@vindex PC
Program for compiling Pascal programs; default @samp{pc}.
+@pindex pc
@item YACC
@vindex YACC
Program to use to turn Yacc grammars into C programs; default @samp{yacc}.
+@pindex yacc
@item YACCR
@vindex YACCR
@vindex MAKEINFO
Program to convert a Texinfo source file into an Info file; default
@samp{makeinfo}.
+@pindex makeinfo
@item TEX
@vindex TEX
Program to make @TeX{} @sc{dvi} files from @TeX{} source;
default @samp{tex}.
+@pindex tex
@item TEXI2DVI
@vindex TEXI2DVI
Program to make @TeX{} @sc{dvi} files from Texinfo source;
default @samp{texi2dvi}.
+@pindex texi2dvi
@item WEAVE
@vindex WEAVE
Program to translate Web into @TeX{}; default @samp{weave}.
+@pindex weave
@item CWEAVE
@vindex CWEAVE
Program to translate C Web into @TeX{}; default @samp{cweave}.
+@pindex cweave
@item TANGLE
@vindex TANGLE
Program to translate Web into Pascal; default @samp{tangle}.
+@pindex tangle
@item CTANGLE
@vindex CTANGLE
Program to translate C Web into C; default @samp{ctangle}.
+@pindex ctangle
@item RM
@vindex RM
Command to remove a file; default @samp{rm -f}.
+@pindex rm
@end table
Here is a table of variables whose values are additional arguments for the
@section Chains of Implicit Rules
@cindex chains of rules
+@cindex rules, 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}.
updated.@refill
@cindex intermediate file
+@cindex files, intermediate
However, even if @file{@var{n}.c} does not exist and is not mentioned,
@code{make} knows how to envision it as the missing link between
@file{@var{n}.o} and @file{@var{n}.y}! In this case, @file{@var{n}.c} is
@node Pattern Intro, Pattern Examples, , Pattern Rules
@subsection Introduction to Pattern Rules
@cindex pattern rule
+@cindex rule, pattern
A pattern rule contains the character @samp{%} (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 @samp{%} matches any
nonempty substring, while other characters match only themselves.
+@cindex target pattern
+@cindex @code{%}, in pattern rules
For example, @samp{%.c} as a pattern matches any file name that ends in
@samp{.c}. @samp{s.%.c} as a pattern matches any file name that starts
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
Thus, a rule of the form
@code{make} worries only about giving commands and dependencies to the file
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
The order in which pattern rules appear in the makefile is important
because the rules are considered in that order. Of equally applicable
over those that are built in. Note, however, that a rule whose
dependencies actually exist or are mentioned always takes priority over a
rule with dependencies that must be made by chaining other implicit rules.
+@cindex pattern rules, order of
+@cindex order of pattern rules
@node Pattern Examples, Automatic, Pattern Intro, Pattern Rules
@subsection Pattern Rule Examples
@node Automatic, Pattern Match, Pattern Examples, Pattern Rules
@subsection Automatic Variables
@cindex automatic variables
+@cindex variables, automatic
+@cindex variables, and implicit rules
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
Here is a table of automatic variables:
@table @code
-@cindex @code{$@@}
+@vindex $@@
+@vindex @@ @r{(automatic variable)}
@item $@@
The file name of the target of the rule. If the target is an archive
member, then @samp{$@@} is the name of the archive file.
-@cindex @code{$%}
+@vindex $%
+@vindex % @r{(automatic variable)}
@item $%
The target member name, when the target is an archive member.
@xref{Archives}. For example, if the target is @file{foo.a(bar.o)} then
@samp{$%} is @file{bar.o} and @samp{$@@} is @file{foo.a}. @samp{$%} is
empty when the target is not an archive member.
-@cindex @code{$<}
+@vindex $<
+@vindex < @r{(automatic variable)}
@item $<
The name of the first dependency. If the target got its commands from
an implicit rule, this will be the first dependency added by the
implicit rule (@pxref{Implicit Rules}).
-@cindex @code{$?}
+@vindex $?
+@vindex ? @r{(automatic variable)}
@item $?
The names of all the dependencies that are newer than the target, with
spaces between them. For dependencies which are archive members, only
the member named is used (@pxref{Archives}).
+@cindex dependencies, list of changed
+@cindex list of changed dependencies
-@cindex @code{$^}
+@vindex $^
+@vindex ^ @r{(automatic variable)}
@item $^
The names of all the dependencies, with spaces between them. For
dependencies which are archive members, only the member named is used
(@pxref{Archives}).
+@cindex dependencies, list of all
+@cindex list of all dependencies
-@cindex @code{$*}
+@vindex $*
+@vindex * @r{(automatic variable)}
@item $*
The stem with which an implicit rule matches (@pxref{Pattern Match, ,How
Patterns Match}). If the target is @file{dir/a.foo.b} and the target
pattern is @file{a.%.b} then the stem is @file{dir/foo}. The stem is
useful for constructing names of related files.@refill
+@cindex stem, variable for
In a static pattern rule, the stem is part of the file name that matched
the @samp{%} in the target pattern.
@end group
@end example
-
Of the variables listed above, four have values that are single file
names, and two have values that are lists of file names. These six
have variants that get just the file's directory name or just the file
@table @samp
@vindex $(@@D)
-@vindex @@D
+@vindex @@D @r{(automatic variable)}
@item $(@@D)
The directory part of the file name of the target. If the value of
@samp{$@@} is @file{dir/foo.o} then @samp{$(@@D)} is @file{dir/}.
@samp{$(@@D)} is equivalent to @w{@samp{$(dir $@@)}}.@refill
@vindex $(@@F)
-@vindex @@F
+@vindex @@F @r{(automatic variable)}
@item $(@@F)
The file-within-directory part of the file name of the target. If the
value of @samp{$@@} is @file{dir/foo.o} then @samp{$(@@F)} is
@file{foo.o}. @samp{$(@@F)} is equivalent to @samp{$(notdir $@@)}.
@vindex $(*D)
-@vindex *D
+@vindex *D @r{(automatic variable)}
@item $(*D)
@vindex $(*F)
-@vindex *F
+@vindex *F @r{(automatic variable)}
@itemx $(*F)
The directory part and the file-within-directory
part of the stem; @file{dir/} and @file{foo} in this example.
@vindex $(%D)
-@vindex %D
+@vindex %D @r{(automatic variable)}
@item $(%D)
@vindex $(%F)
-@vindex %F
+@vindex %F @r{(automatic variable)}
@itemx $(%F)
The directory part and the file-within-directory part of the target
archive member name. This makes sense only for archive member targets
,Archive Members as Targets}.)
@vindex $(<D)
-@vindex <D
+@vindex <D @r{(automatic variable)}
@item $(<D)
@vindex $(<F)
-@vindex <F
+@vindex <F @r{(automatic variable)}
@itemx $(<F)
The directory part and the file-within-directory
part of the first dependency.
@vindex $(^D)
-@vindex ^D
+@vindex ^D @r{(automatic variable)}
@item $(^D)
@vindex $(^F)
-@vindex ^F
+@vindex ^F @r{(automatic variable)}
@itemx $(^F)
Lists of the directory parts and the file-within-directory
parts of all dependencies.
@vindex $(?D)
-@vindex ?D
+@vindex ?D @r{(automatic variable)}
@item $(?D)
@vindex $(?F)
-@vindex ?F
+@vindex ?F @r{(automatic variable)}
@itemx $(?F)
Lists of the directory parts and the file-within-directory parts of
all dependencies that are newer than the target.
(@pxref{Archives}).
@item $*
-The stem with which an implicit rule matches (@pxref{Pattern Match, ,How Patterns Match}).
+The stem with which an implicit rule matches
+(@pxref{Pattern Match, ,How Patterns Match}).
-@vindex $(@@D)
-@vindex @@D
@item $(@@D)
-@vindex $(@@F)
-@vindex @@F
@itemx $(@@F)
The directory part and the file-within-directory part of @code{$@@}.
-@vindex $(*D)
-@vindex *D
@item $(*D)
-@vindex $(*F)
-@vindex *F
@itemx $(*F)
The directory part and the file-within-directory part of @code{$*}.
-@vindex $(%D)
-@vindex %D
@item $(%D)
-@vindex $(%F)
-@vindex %F
@itemx $(%F)
The directory part and the file-within-directory part of @code{$%}.
-@vindex $(<D)
-@vindex <D
@item $(<D)
-@vindex $(<F)
-@vindex <F
@itemx $(<F)
The directory part and the file-within-directory part of @code{$<}.
-@vindex $(^D)
-@vindex ^D
@item $(^D)
-@vindex $(^F)
-@vindex ^F
@itemx $(^F)
The directory part and the file-within-directory part of @code{$^}.
-@vindex $(?D)
-@vindex ?D
@item $(?D)
-@vindex $(?F)
-@vindex ?F
@itemx $(?F)
The directory part and the file-within-directory part of @code{$?}.
@end table
projects / thirdparty / make.git / commitdiff
