summaryrefslogtreecommitdiff
path: root/make.texinfo
diff options
context:
space:
mode:
authorRoland McGrath <roland@redhat.com>1992-07-24 02:03:20 +0000
committerRoland McGrath <roland@redhat.com>1992-07-24 02:03:20 +0000
commit1d2e7e6142bc75ada950cb3ad2e926e71f1fb8b2 (patch)
tree50cc09a662d75291f956e98ac5e655ea23a25a30 /make.texinfo
parent099b302768676929b33e4869d9aaa19c15f4fa4a (diff)
downloadgunmake-1d2e7e6142bc75ada950cb3ad2e926e71f1fb8b2.tar.gz
Formerly make.texinfo.~37~
Diffstat (limited to 'make.texinfo')
-rw-r--r--make.texinfo295
1 files changed, 197 insertions, 98 deletions
diff --git a/make.texinfo b/make.texinfo
index b5184c0..98f78ce 100644
--- a/make.texinfo
+++ b/make.texinfo
@@ -321,7 +321,7 @@ from others whenever the others change.
* Bugs:: Problems and Bugs
@end menu
-@node Preparing, Reading, Overview , Overview
+@node Preparing, Reading, , Overview
@ifinfo
@heading Preparing and Running Make
@end ifinfo
@@ -359,11 +359,13 @@ specialized or technical information. The exception is the second
chapter, @ref{Introduction, ,An Introduction to Makefiles}, all of which
is introductory.
-If you are familiar with other @code{make} programs, @ref{Features}
-lists the enhancements GNU @code{make} has, and @ref{Missing} explains
-the few things GNU @code{make} lacks that others have.
+@c Must have commas after references so the Info readers will work.
+If you are familiar with other @code{make} programs, see
+@ref{Features}, which lists the enhancements GNU @code{make} has, and
+@ref{Missing}, which explains the few things GNU @code{make} lacks
+that others have.
-For a quick summary, @pxref{Options Summary} and @ref{Special Targets}.
+For a quick summary, see @ref{Options Summary}, and @ref{Special Targets}.
@node Bugs, , Reading, Overview
@section Problems and Bugs
@@ -457,9 +459,14 @@ together to produce the new executable editor.
@node Parts of Makefiles, Simple Makefile, , Introduction
@comment node-name, next, previous, up
@section The Parts of a Makefile
+@cindex parts of a makefile
A simple makefile consists of ``rules'' with the following shape:
+@cindex rule, part of makefile
+@cindex target, part of makefile
+@cindex dependencies, part of makefile
+@cindex command, part of makefile
@example
@group
@var{target} @dots{} : @var{dependencies} @dots{}
@@ -570,7 +577,7 @@ on the header file @file{defs.h}.
A shell command follows each line that contains a target and
dependencies. These shell commands say how to update the target file.
-A @key{TAB} must come at the beginnning of every command line to
+A @key{TAB} must come at the beginning of every command line to
distinguish commands lines from other lines in the makefile. (Bear in
mind that @code{make} does not know anything about how the commands
work. It is up to you to supply commands that will update the target
@@ -800,6 +807,7 @@ for. Makefiles commonly tell how to do a few other things besides
compiling a program: for example, how to delete all the object files
and executables so that the directory is ``clean''.
+@cindex clean in makefile
Here is how we
could write a @code{make} rule for cleaning our example editor:
@@ -861,22 +869,25 @@ definitions}, @dfn{directives}, and @dfn{comments}. Rules, variables, and
directives are described at length in later chapters.@refill
@itemize @bullet
+@cindex rule (definition of)
@item
-A rule says when and how to remake one or more files, called the rule's
-@dfn{targets}. It lists the other files that the targets @dfn{depend on},
+A @dfn{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 variable definition
@item
-A variable definition is a line that specifies a text string value for
-a @dfn{variable} that can be substituted into the text later. The
+A @dfn{variable definition} is a line that specifies a text string value for
+a variable that can be substituted into the text later. The
simple makefile example (@pxref{Simple Makefile, , A Simple Makefile})
shows a variable definition for @code{objects} as a list of all object
files. @xref{Using Variables, ,How to Use Variables}, for full
details.
+@cindex directive
@item
-A directive is a command for @code{make} to do something special while
+A @dfn{directive} is a command for @code{make} to do something special while
reading the makefile. These include:
@itemize @bullet
@@ -892,9 +903,10 @@ Defining a variable from a verbatim string containing multiple lines
(@pxref{Defining, ,Defining Variables Verbatim}).
@end itemize
+@cindex comment
@item
@cindex comments
-@samp{#} in a line of a makefile starts a comment. It and the rest of
+@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
another backslash will continue the comment across multiple lines.
Comments may appear on any of the lines in the makefile, except within a
@@ -1090,9 +1102,9 @@ target, @code{make} will not let you just do this. But there is another way.
In the containing makefile (the one that wants to include the other),
you can use the @code{.DEFAULT} special target to say that to remake
any target that cannot be made from the information in the containing
-makefile, @code{make} should look in another makefile. @xref{Last
-Resort, , Defining Last-Resort Default Rules}, for more information on
-@code{.DEFAULT}.
+makefile, @code{make} should look in another makefile.
+@xref{Last Resort, , Defining Last-Resort Default Rules},
+for more information on @code{.DEFAULT}.
For example, if you have a makefile called @file{Makefile} that says how
to make the target @samp{foo} (and other targets), you can write a
@@ -1117,6 +1129,7 @@ will apply the rule. And likewise for any other target that
@node Rules, Commands, Makefiles, Top
@chapter Writing Rules
+@cindex writing rules
@cindex rule
@cindex target
@cindex dependency
@@ -1196,6 +1209,8 @@ added to the dependencies.
@node Rule Syntax, Wildcards, Rule Example, Rules
@section Rule Syntax
+@cindex rule syntax
+@cindex syntax of rules
In general, a rule looks like this:
@example
@@ -1216,10 +1231,11 @@ or like this:
The @var{targets} are file names, separated by spaces. Wild card
characters may be used (@pxref{Wildcards, ,Using Wildcard Characters
in File Names}) and a name of the form @file{@var{a}(@var{m})}
-represents member @var{m} in archive file @var{a} (@pxref{Archive
-Members, ,Archive Members as Targets}). Usually there is only one
-target per rule, but occasionally there is a reason to have more;
-@pxref{Multiple Targets, , Multiple Targets in a Rule}.@refill
+represents member @var{m} in archive file @var{a}
+(@pxref{Archive Members, ,Archive Members as Targets}).
+Usually there is only one
+target per rule, but occasionally there is a reason to have more
+(@pxref{Multiple Targets, , Multiple Targets in a Rule}).@refill
The @var{command} lines start with a tab character. The first command may
appear on the line after the dependencies, with a tab character, or may
@@ -1227,8 +1243,9 @@ appear on the same line, with a semicolon. Either way, the effect is the
same. @xref{Commands, ,Writing the Commands in Rules}.
Because dollar signs are used to start variable references, if you really
-want a dollar sign in the rule you must write two of them (@samp{$$}).
-@xref{Using Variables, ,How to Use Variables}. You may split a long line by inserting a backslash
+want a dollar sign in a rule you must write two of them, @samp{$$}
+(@pxref{Using Variables, ,How to Use Variables}).
+You may split a long line by inserting a backslash
followed by a newline, but this is not required, as @code{make} places no
limit on the length of a line in a makefile.
@@ -1306,7 +1323,11 @@ print: *.c
@end example
@noindent
-This rule uses @file{print} as an empty target file; @pxref{Empty Targets, ,Empty Target Files to Record Events}.
+This rule uses @file{print} as an empty target file; see
+@ref{Empty Targets, ,Empty Target Files to Record Events}.
+(The automatic
+variable @samp{$?} is used to print only those files that have
+changed; see @ref{Automatic, ,Automatic Variables}.)
Wildcard expansion does not happen when you define a variable. Thus, if
you write this:
@@ -1447,7 +1468,8 @@ current directory, @code{make} searches the directories listed in
@code{VPATH} for a file with that name. If a file is found in one of
them, that file becomes the dependency. Rules may then specify the
names of source files in the dependencies as if they all existed in the
-current directory. @xref{Commands/Search}.
+current directory.
+@xref{Commands/Search, ,Writing Shell Commands with Directory Search}.
In the @code{VPATH} variable, directory names are separated by colons.
The order in which directories are listed is the order followed by
@@ -1553,7 +1575,8 @@ Therefore, you must write the commands with care so that they will look for
the dependency in the directory where @code{make} finds it.
This is done with the @dfn{automatic variables} such as @samp{$^}
-(@pxref{Automatic, ,Automatic Variables}). For instance, the value of @samp{$^} is a
+(@pxref{Automatic, ,Automatic Variables}).
+For instance, the value of @samp{$^} is a
list of all the dependencies of the rule, including the names of
the directories in which they were found, and the value of
@samp{$@@} is the target. Thus:@refill
@@ -1607,11 +1630,13 @@ names found by directory search with no extra effort.
@node Libraries/Search, , Implicit/Search, Directory Search
@subsection Directory Search for Link Libraries
+@cindex link libraries, directory search
+@cindex directory search, link libraries
Directory search applies in a special way to libraries used with the
linker. This special feature comes into play when you write a dependency
whose name is of the form @samp{-l@var{name}}. (You can tell something
-funny is going on here because the dependency is normally the name of a
+strange is going on here because the dependency is normally the name of a
file, and the @emph{file name} of the library looks like
@file{lib@var{name}.a}, not like @samp{-l@var{name}}.)@refill
@@ -1690,9 +1715,11 @@ Thus, you first write the line that states that @code{clean} is a
phony target, then you write the rule, like this:
@example
+@group
.PHONY: clean
clean:
rm *.o temp
+@end group
@end example
A phony target should not be a dependency of a real target file; strange
@@ -1751,9 +1778,11 @@ depending on this one will always have their commands run.
An example will illustrate this:
@example
+@group
clean: FORCE
rm $(objects)
FORCE:
+@end group
@end example
Here the target @samp{FORCE} satisfies the special conditions, so the
@@ -1799,6 +1828,8 @@ changed (@pxref{Automatic, ,Automatic Variables}).
@node Special Targets, Multiple Targets, Empty Targets, Rules
@section Special Built-in Target Names
@cindex special targets
+@cindex built-in special targets
+@cindex targets, built-in special
Certain names have special meanings if they appear as targets.
@@ -1812,8 +1843,8 @@ time is. @xref{Phony Targets, ,Phony Targets}.
@item .SUFFIXES
The dependencies of the special target @code{.SUFFIXES} are the list
-of suffixes to be used in checking for suffix rules. @xref{Suffix
-Rules, , Old-Fashioned Suffix Rules}.
+of suffixes to be used in checking for suffix rules.
+@xref{Suffix Rules, , Old-Fashioned Suffix Rules}.
@item .DEFAULT
The commands specified for @code{.DEFAULT} are used for any target for
@@ -1849,11 +1880,10 @@ for @code{.SILENT} are not meaningful.
use the more selective ways to silence specific commands.
@xref{Echoing, ,Command Echoing}.
-@c !!! overful hbox here
@item .EXPORT_ALL_VARIABLES
-Simply by being mentioned as a target, @code{.EXPORT_ALL_VARIABLES}
+By being mentioned as a target, @code{.EXPORT_ALL_VARIABLES}
tells @code{make} to export all variables to child processes by default.
-@xref{Variables/Recursion, ,Exporting Variables}.
+@xref{Variables/Recursion, ,Communicating Variables to a Sub-@code{make}}.
@end table
Any defined implicit rule suffix also counts as a special target if it
@@ -1867,6 +1897,8 @@ both pieces to the suffix list. In practice, suffixes normally begin with
@node Multiple Targets, Static Pattern, Special Targets, Rules
@section Multiple Targets in a Rule
+@cindex multiple targets
+@cindex targets, multiple
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
@@ -1991,12 +2023,19 @@ Here is an example, which compiles each of @file{foo.o} and @file{bar.o}
from the corresponding @file{.c} file:
@example
+@group
objects = foo.o bar.o
$(objects): %.o: %.c
$(CC) -c $(CFLAGS) $< -o $@@
+@end group
@end example
+@noindent
+(Here @samp{$<} is the automatic variable that holds the name of the
+dependency and @samp{$@@} is the automatic variable that holds the name
+of the target; see @ref{Automatic, , Automatic Variables}.)
+
Each target specified must match the target pattern; a warning is issued
for each target that does not. If you have a list of files, only some of
which will match the pattern, you can use the @code{filter} function to
@@ -2106,8 +2145,8 @@ means that the command @samp{make extradeps=foo.h} will consider
will not.
If none of the explicit rules for a target has commands, then @code{make}
-searches for an applicable implicit rule to find some commands.
-@xref{Implicit Rules, ,Using Implicit Rules}.
+searches for an applicable implicit rule to find some commands
+9@pxref{Implicit Rules, ,Using Implicit Rules}).
@node Double-Colon, , Multiple Rules, Rules
@section Double-Colon Rules
@@ -2121,7 +2160,7 @@ When a target appears in multiple rules, all the rules must be the same
type: all ordinary, or all double-colon. If they are double-colon, each of
them is independent of the others. Each double-colon rule's commands are
executed if the target is older than any dependencies of that rule. This
-can result in executing none, any or all of the double-colon rules.
+can result in executing none, any, or all of the double-colon rules.
Double-colon rules with the same target are in fact completely separate
from one another. Each double-colon rule is processed individually, just
@@ -2172,10 +2211,11 @@ Text on a line before a @samp{#} is not part of the comment.
@node Echoing, Execution, , Commands
@section Command Echoing
-
-@cindex echoing (of commands)
+@cindex echoing of commands
@cindex silent operation
@cindex @@ (in commands)
+@cindex command echoing
+
Normally @code{make} prints each command line before it is executed.
We call this @dfn{echoing} because it gives the appearance that you
are typing the commands yourself.
@@ -2205,7 +2245,8 @@ started with @samp{@@}. A rule in the makefile for the special target
@node Execution, Parallel, Echoing, Commands
@section Command Execution
-@cindex execution
+@cindex command execution
+@cindex execution of commands
@cindex shell
When it is time to execute commands to update a target, they are executed
@@ -2351,7 +2392,7 @@ clean:
@end example
@noindent
-This causes @code{rm} to continue even if it us unable to remove a file.
+This causes @code{rm} to continue even if it is unable to remove a file.
@cindex @code{-i}
@findex .IGNORE
@@ -2509,6 +2550,7 @@ commands, is propagated to the subsystem.@refill
@node Variables/Recursion, Options/Recursion, MAKE Variable, Recursion
@subsection Communicating Variables to a Sub-@code{make}
+@cindex sub-@code{make}
@cindex environment and recursion
@cindex exporting variables
@cindex variables, environment
@@ -2712,6 +2754,7 @@ probably annoying effects.@refill
@node -w Option, , Options/Recursion, Recursion
@subsection The @samp{-w} Option
+@cindex directories, printing them
If you use several levels of recursive @code{make} invocations, the
@samp{-w} option can make the output a lot easier to understand by showing
@@ -2784,7 +2827,8 @@ foo.c : foo.y
This is a realistic example, but this particular one is not needed in
practice because @code{make} has an implicit rule to figure out these
-commands based on the file names involved. @xref{Implicit Rules, ,Using Implicit Rules}.
+commands based on the file names involved (@pxref{Implicit Rules,
+,Using Implicit Rules}).
@node Empty Commands, , Sequences, Commands
@section Defining Empty Commands
@@ -2806,8 +2850,8 @@ but this would be confusing because such a line looks empty.
You may be wondering why you would want to define a command string that
does nothing. The only reason this is useful is to prevent a target
from getting implicit commands (from implicit rules or the
-@code{.DEFAULT} special target; @pxref{Implicit Rules} and @pxref{Last
-Resort, ,Defining Last-Resort Default Rules}).@refill
+@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
@@ -2906,8 +2950,9 @@ the case of the automatic variables (@pxref{Automatic, ,Automatic Variables}).
@node Flavors, Advanced, Reference, Using Variables
@section The Two Flavors of Variables
-@cindex flavors (of variables)
+@cindex flavors of variables
@cindex recursive variable expansion
+@cindex variable flavors
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
@@ -2966,10 +3011,12 @@ because you cannot easily control when they are called, or even how many
times.
To avoid all the problems and inconveniences of recursively expanded
-variables, there is another flavor: @dfn{simply expanded} variables.
+variables, there is another flavor: simply expanded variables.
-Simply expanded variables are defined by lines using @samp{:=}
-(@pxref{Setting, ,Setting Variables}). The value of a simply expanded variable is scanned
+@cindex simply expanded variables
+@dfn{Simply expanded variables} are defined by lines using @samp{:=}
+(@pxref{Setting, ,Setting Variables}).
+The value of a simply expanded variable is scanned
once and for all, expanding any references to other variables and
functions, when the variable is defined. The actual value of the simply
expanded variable is the result of expanding the text that you write.
@@ -3170,11 +3217,13 @@ function invocations (@pxref{Functions, ,Functions for Transforming Text}), just
For example, using the @code{subst} function (@pxref{Text Functions, ,Functions for String Substitution and Analysis}):
@example
+@group
x = variable1
variable2 := Hello
y = $(subst 1,2,$(x))
z = y
a := $($($(z)))
+@end group
@end example
@noindent
@@ -3191,18 +3240,25 @@ reference. It can contain several variable references, as well as some
invariant text. For example,
@example
+@group
a_dirs := dira dirb
1_dirs := dir1 dir2
+@end group
+@group
a_files := filea fileb
1_files := file1 file2
+@end group
+@group
ifeq "$(use_a)" "yes"
a1 := a
else
a1 := 1
endif
+@end group
+@group
ifeq "$(use_dirs)" "yes"
df := dirs
else
@@ -3210,6 +3266,7 @@ df := files
endif
dirs := $($(a1)_$(df))
+@end group
@end example
@noindent
@@ -3220,10 +3277,12 @@ and @code{use_dirs}.@refill
Computed variable names can also be used in substitution references:
@example
+@group
a_objects := a.o b.o c.o
1_objects := 1.o 2.o 3.o
sources := $($(a1)_object:.o=.c)
+@end group
@end example
@noindent
@@ -3236,15 +3295,21 @@ This is because the test for a recognized function name is done before
the expansion of nested references. For example,
@example
+@group
ifdef do_sort
func := sort
else
func := strip
endif
+@end group
+@group
bar := a d b g q c
+@end group
+@group
foo := $($(func) $(bar))
+@end group
@end example
@noindent
@@ -3255,7 +3320,8 @@ This restriction could be removed in the future if that change is shown
to be a good idea.
Note that @dfn{nested variable references} are quite different from
-@dfn{recursively expanded variables} (@pxref{Flavors, ,The Two Flavors of Variables}), though both are
+@dfn{recursively expanded variables}
+(@pxref{Flavors, ,The Two Flavors of Variables}), though both are
used together in complex ways when doing makefile programming.@refill
@node Values, Setting, Advanced, Using Variables
@@ -3377,6 +3443,9 @@ See the next section.
@section Defining Variables Verbatim
@findex define
@findex endef
+@cindex verbatim variable definition
+@cindex defining variables verbatim
+@cindex variables, 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
@@ -3681,7 +3750,7 @@ beginning or the end of the conditional.@refill
@code{make} evaluates conditionals when it reads a makefile.
Consequently, you cannot use automatic variables in the tests of
conditionals because they are not defined until commands are run
-(@pxref{Automatic}).
+(@pxref{Automatic, , Automatic Variables}).
To prevent intolerable confusion, it is not permitted to start a
conditional in one makefile and end it in another. However, you may
@@ -3788,11 +3857,13 @@ by variable substitution. First define variables @code{comma} and
substitute those variables where such characters are wanted, like this:
@example
+@group
comma:= ,
space:= $(empty) $(empty)
foo:= a b c
bar:= $(subst $(space),$(comma),$(foo))
# @r{bar is now `a,b,c'.}
+@end group
@end example
@noindent
@@ -3943,7 +4014,9 @@ it for this purpose even if you don't care about the sort order.
Here is a realistic example of the use of @code{subst} and
@code{patsubst}. Suppose that a makefile uses the @code{VPATH} variable
to specify a list of directories that @code{make} should search for
-dependency files (@pxref{General Search}).. This example shows how to
+dependency files
+(@pxref{General Search, , @code{VPATH} Search Path for All Dependencies}).
+This example shows how to
tell the C compiler to search for header files in the same list of
directories.@refill
@@ -4133,7 +4206,7 @@ $(word 2, foo bar baz)
@noindent
returns @samp{bar}.
-@c Following item phrased to prevent overful hbox. --RJC 17 Jul 92
+@c Following item phrased to prevent overfull hbox. --RJC 17 Jul 92
@item $(words @var{text})
@findex words
Returns the number of words in @var{text}.
@@ -4310,7 +4383,8 @@ makefile (@pxref{Override Directive, ,The @code{override} Directive}).
@item automatic
if @var{variable} is an automatic variable defined for the
-execution of the commands for each rule. @xref{Automatic}.
+execution of the commands for each rule
+(@pxref{Automatic, , Automatic Variables}).
@end table
This information is primarily useful (other than for your curiosity) to
@@ -4327,11 +4401,13 @@ override any command line definitions. So, @file{bar} could
include:@refill
@example
+@group
ifdef bletch
ifeq "$(origin bletch)" "environment"
bletch = barf, gag, etc.
endif
endif
+@end group
@end example
@noindent
@@ -4436,8 +4512,9 @@ If you use the @samp{-f} flag several times and follow each @samp{-f} with an ar
makefiles.
If you do not use the @samp{-f} flag, the default is to try
-@file{GNUmakefile}, @file{makefile}, or @file{Makefile}, in that order, and
-use the first of these three which exists. @xref{Makefiles, ,Writing Makefiles}.@refill
+@file{GNUmakefile}, @file{makefile}, or @file{Makefile}, in that
+order, and use the first of these three which exists
+(@pxref{Makefiles, ,Writing Makefiles}).@refill
@node Goals, Instead of Execution, Makefile Arguments, Running
@section Arguments to Specify the Goals
@@ -4532,6 +4609,11 @@ and how to update each target. But updating the targets is not always
what you want. Certain options specify other activities for @code{make}.
@table @samp
+@item -n
+@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.
+
@item -t
@cindex touching files
@cindex @code{-t}
@@ -4539,11 +4621,6 @@ what you want. Certain options specify other activities for @code{make}.
actually changing them. In other words, @code{make} pretends to compile
the targets but does not really change their contents.
-@item -n
-@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.
-
@item -q
@cindex @code{-q}
@cindex question mode
@@ -4583,7 +4660,7 @@ lines that begin with @samp{+} characters or contain the strings
the @samp{+} character or the strings @samp{$(MAKE)} or @samp{$@{MAKE@}}
is run regardless of these options. Other lines in the same rule are
not run unless they too begin with @samp{+} or contain @samp{$(MAKE)} or
-@samp{$@{MAKE@}}. @xref{MAKE Variable}.@refill
+@samp{$@{MAKE@}} (@xref{MAKE Variable}).@refill
The @samp{-W} flag provides two features:
@@ -4600,8 +4677,8 @@ files.@refill
@end itemize
Note that the options @samp{-p} and @samp{-v} allow you to obtain other
-information about @code{make} or about the makefiles in use.
-@xref{Options Summary, ,Summary of Options}.@refill
+information about @code{make} or about the makefiles in use
+(@pxref{Options Summary, ,Summary of Options}).@refill
@node Avoiding Compilation, Overriding, Instead of Execution, Running
@section Avoiding Recompilation of Some Files
@@ -4702,8 +4779,8 @@ variable you create.
There is one way that the makefile can change a variable that you have
overridden. This is to use the @code{override} directive, which is a line
-that looks like this: @samp{override @var{variable} = @var{value}}.
-@xref{Override Directive, ,The @code{override} Directive}.
+that looks like this: @samp{override @var{variable} = @var{value}}
+(@pxref{Override Directive, ,The @code{override} Directive}).
@node Testing, Options Summary, Overriding, Running
@section Testing the Compilation of a Program
@@ -4729,8 +4806,8 @@ even though it already knows that linking them will be impossible. In
addition to continuing after failed shell commands, @samp{make -k} will
continue as much as possible after discovering that it does not know how
to make a target or dependency file. This will always cause an error
-message, but without @samp{-k}, it is a fatal error. @xref{Options
-Summary, ,Summary of Options}.@refill
+message, but without @samp{-k}, it is a fatal error (@pxref{Options
+Summary, ,Summary of Options}).@refill
The usual behavior of @code{make} assumes that your purpose is to get the
goals up to date; once @code{make} learns that this is impossible, it might
@@ -4770,7 +4847,7 @@ considered and which are applied---everything interesting about how
@code{make} decides what to do.
@item -e
-@item --environment-ovverides
+@item --environment-overrides
Give variables taken from the environment precedence
over variables from makefiles. @xref{Environment, ,Variables from the Environment}.
@@ -4780,6 +4857,11 @@ over variables from makefiles. @xref{Environment, ,Variables from the Environme
Read the file named @var{file} as a makefile.
@xref{Makefiles, ,Writing Makefiles}.
+@c !!! Does --help exit immediately or run make?
+@item -h
+@itemx --help
+Remind you of the options that @code{make} understands.
+
@item -i
@itemx --ignore-errors
Ignore all errors in commands executed to remake files.
@@ -4876,6 +4958,7 @@ 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}.
+@c !!! Does --version exit immediately or run make? (compare --help)
@item -v
@itemx --version
Print the version of the @code{make} program plus a copyright, a list
@@ -5025,8 +5108,8 @@ implicit rules (@pxref{Catalogue of Rules, , Catalogue of Implicit
Rules}).
If you do not want an implicit rule to be used for a target that has no
-commands, you can give that target empty commands by writing a semicolon.
-@xref{Empty Commands, ,Defining Empty Commands}.
+commands, you can give that target empty commands by writing a semicolon
+(@pxref{Empty Commands, ,Defining Empty Commands}).
@node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit Rules
@section Catalogue of Implicit Rules
@@ -5055,21 +5138,21 @@ fail to be on the list are disabled.@refill
@table @asis
@item Compiling C programs
-@file{@var{n}.o} will be made automatically from @file{@var{n}.c} with
+@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
-@file{@var{n}.o} will be made automatically from @file{@var{n}.cc} or
+@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
-@file{@var{n}.o} will be made automatically from @file{@var{n}.p}
+@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
-@file{@var{n}.o} will be made automatically from @file{@var{n}.r},
+@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
@@ -5083,7 +5166,7 @@ Fortran compiler. The precise command used is as follows:@refill
@end table
@item Preprocessing Fortran and Ratfor programs
-@file{@var{n}.f} will be made automatically from @file{@var{n}.r} or
+@file{@var{n}.f} is made automatically from @file{@var{n}.r} or
@file{@var{n}.F}. This rule runs just the preprocessor to convert a
Ratfor or preprocessable Fortran program into a strict Fortran
program. The precise command used is as follows:@refill
@@ -5095,24 +5178,23 @@ program. The precise command used is as follows:@refill
@samp{$(FC) -F $(FFLAGS) $(RFLAGS)}.
@end table
-@c !!! overfull hbox here
@item Compiling Modula-2 programs
-@file{@var{n}.sym} will be made from @file{@var{n}.def} with a command
+@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}
-will be made from @file{@var{n}.mod} with a command of the form
+is made from @file{@var{n}.mod}; the form is:
@w{@samp{$(M2C) $(M2FLAGS) $(MODFLAGS)}}.@refill
@item Assembling and preprocessing assembler programs
-@file{@var{n}.o} will be made automatically from @file{@var{n}.s} by
+@file{@var{n}.o} is made automatically from @file{@var{n}.s} by
running the assembler @code{as}. The precise command used is
@samp{$(AS) $(ASFLAGS)}.@refill
-@file{@var{n}.s} will be made automatically from @file{@var{n}.S} by
+@file{@var{n}.s} is made automatically from @file{@var{n}.S} by
running the C preprocessor @code{cpp}. The precise command used is
@samp{$(CPP) $(CPPFLAGS)}.@refill
@item Linking a single object file
-@file{@var{n}} will be made automatically from @file{@var{n}.o} by
+@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 @samp{$(CC) $(LDFLAGS) @var{n}.o $(LOADLIBES)}.@refill
@@ -5152,15 +5234,15 @@ faster to do the compiling and linking in one step, so that's how it's
done.@refill
@item Yacc for C programs
-@file{@var{n}.c} will be made automatically from @file{@var{n}.y} by
+@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
-@file{@var{n}.c} will be made automatically from @file{@var{n}.l} by
+@file{@var{n}.c} is made automatically from @file{@var{n}.l} by
by running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}.
@item Lex for Ratfor programs
-@file{@var{n}.r} will be made automatically from @file{@var{n}.l} by
+@file{@var{n}.r} is made automatically from @file{@var{n}.l} by
by running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}.
The convention of using the same suffix @samp{.l} for all Lex files
@@ -5180,26 +5262,27 @@ the list of implicit rule suffixes with:@refill
@end example
@item Making Lint Libraries from C, Yacc, or Lex programs
-@file{@var{n}.ln} will be made from @file{@var{n}.c} with a command of
+@file{@var{n}.ln} is made from @file{@var{n}.c} with a command of
the form @samp{$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i}. The same command
-will be used on the C code produced from @file{@var{n}.y} or
+is used on the C code produced from @file{@var{n}.y} or
@file{@var{n}.l}.@refill
@item @TeX{} and Web
-@file{@var{n}.dvi} will be made from @file{@var{n}.tex} with the
-command @samp{$(TEX)}. @file{@var{n}.tex} will be made from
+@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}
-with @samp{$(CWEAVE)}. @file{@var{n}.p} will be made from
-@file{@var{n}.web} with @samp{$(TANGLE)} and @file{@var{n}.c} will be
+with @samp{$(CWEAVE)}. @file{@var{n}.p} is made from
+@file{@var{n}.web} with @samp{$(TANGLE)} and @file{@var{n}.c} is
made from @file{@var{n}.cweb} with @samp{$(CTANGLE)}.@refill
@item Texinfo and Info
-@file{@var{n}.dvi} will be made from @file{@var{n}.texinfo} with the
-command @samp{$(TEXI2DVI)}. @file{@var{n}.info} will be made from
+@file{@var{n}.dvi} is made from @file{@var{n}.texinfo}.
+@samp{$(TEXI2DVI)} is used for the command.
+@file{@var{n}.info} is made from
@file{@var{n}.texinfo} with the command @samp{$(MAKEINFO)}.@refill
@item RCS
-Any file @file{@var{n}} will be extracted if necessary from an RCS file
+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 @samp{$(CO) $(COFLAGS)}. @file{@var{n}} will not be
extracted from RCS if it already exists, even if the RCS file is
@@ -5208,14 +5291,14 @@ newer. The rules for RCS are terminal (@pxref{Match-Anything Rules,
another source; they must actually exist.@refill
@item SCCS
-Any file @file{@var{n}} will be extracted if necessary from an SCCS file
+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 @samp{$(GET) $(GFLAGS)}. The rules for SCCS are
terminal (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}),
so SCCS files cannot be generated from another source; they must
actually exist.@refill
-For the benefit of SCCS, a file @file{@var{n}} will be copied from
+For the benefit of SCCS, a file @file{@var{n}} is copied from
@file{@var{n}.sh} and made executable (by everyone). This is for
shell scripts that are checked into SCCS. Since RCS preserves the
execution permission of a file, you do not need to use this feature
@@ -5443,7 +5526,7 @@ first Yacc and then @code{cc}. Such a sequence is called a @dfn{chain}.
If the file @file{@var{n}.c} exists, or is mentioned in the makefile, no
special searching is required: @code{make} finds that the object file can
be made by C compilation from @file{@var{n}.c}; later on, when considering
-how to make @file{@var{n}.c}, the rule for running Yacc will be
+how to make @file{@var{n}.c}, the rule for running Yacc is
used. Ultimately both @file{@var{n}.c} and @file{@var{n}.o} are
updated.@refill
@@ -5464,7 +5547,8 @@ deletion is reported to you by printing a @samp{rm -f} command that
shows what @code{make} is doing. (You can list the target pattern of an
implicit rule (such as @samp{%.o}) as a dependency file of the special
target @code{.PRECIOUS} to preserve intermediate files made by implicit
-rules whose target patterns match that file's name.)@refill
+rules whose target patterns match that file's name;
+see @ref{Interrupts}.)@refill
@cindex intermediate files, preserving
@cindex preserving intermediate files
@cindex preserving with .PRECIOUS
@@ -5662,7 +5746,7 @@ The target member name, when the target is an archive member.
empty when the target is not an archive member.
@item $<
-The name of the first dependency. if the target got its commands from
+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}).
@@ -5879,7 +5963,7 @@ specific target pattern and thereby prevent time from being wasted looking
for @file{foo.p.o} or @file{foo.p.c}.
Dummy pattern rules such as the one for @samp{%.p} are made for every
-suffix listed as valid for use in suffix rules. @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
+suffix listed as valid for use in suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}).
@node Canceling Rules, , Match-Anything Rules, Pattern Rules
@subsection Canceling Implicit Rules
@@ -5900,6 +5984,8 @@ would cancel the rule that runs the assembler:
@node Last Resort, Suffix Rules, Pattern Rules, Implicit Rules
@section Defining Last-Resort Default Rules
+@cindex last-resort default rules
+@cindex default rules, last-resort
You can define a last-resort implicit rule by writing a terminal
match-anything pattern rule with no dependencies (@pxref{Match-Anything
@@ -5940,12 +6026,12 @@ Then @code{make} acts as if you had never defined @code{.DEFAULT} at all.
If you do not want a target to get the commands from a match-anything
pattern rule or @code{.DEFAULT}, but you also do not want any commands
-to be run for the target, you can give it empty commands. @xref{Empty
-Commands, ,Defining Empty Commands}.@refill
+to be run for the target, you can give it empty commands (@pxref{Empty
+Commands, ,Defining Empty Commands}).@refill
@node Suffix Rules, Search Algorithm, Last Resort, Implicit Rules
@section Old-Fashioned Suffix Rules
-@cindex suffix rules
+@cindex old-fashioned suffix rules
@dfn{Suffix rules} are the old-fashioned way of defining implicit rules for
@code{make}. Suffix rules are obsolete because pattern rules are more
@@ -6043,6 +6129,8 @@ this variable.
@node Search Algorithm, , Suffix Rules, Implicit Rules
@section 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
for a target @var{t}. This procedure is followed for each double-colon
@@ -6240,6 +6328,10 @@ named @file{foo.o}. In connection with such usage, the automatic variables
@node Archive Symbols, , , Archive Update
@subsection Updating Archive Symbol Directories
@cindex __.SYMDEF
+@cindex updating archive symbol directories
+@cindex archive symbol directory updating
+@cindex symbol directories, updating archive
+@cindex directories, updating archive symbol
An archive file that is used as a library usually contains a special member
named @file{__.SYMDEF} that contains a directory of the external symbol
@@ -6272,6 +6364,7 @@ updates the @file{__.SYMDEF} member automatically.
@node Features, Missing, Archives, Top
@chapter Features of GNU @code{make}
+@cindex features of GNU @code{make}
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
@@ -6382,6 +6475,9 @@ The remaining features are inventions new in GNU @code{make}:
@item
Use the @samp{-v} option to print version and copyright information.
+@item
+Use the @samp{-h} option to summarize the options to @code{make}.
+
@item
Simply-expand variables. @xref{Flavors, ,The Two Flavors of Variables}.
@@ -6464,6 +6560,9 @@ Various new built-in implicit rules. @xref{Catalogue of Rules, ,Catalogue of Im
@node Missing, Quick Reference, Features, Top
@chapter Incompatibilities and Missing Features
+@cindex incompatibilities
+@cindex missing features
+@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