Initial revisionRelease1

This version was distributed by RMS in `binutils.tar'.

1 files changed, 3705 insertions, 0 deletions

diff --git a/make.texinfo b/make.texinfo
new file mode 100644
index 0000000..1c4d5b2
--- /dev/null
+++ b/make.texinfo
@@ -0,0 +1,3705 @@
+\input texinfo
+@setfilename make.info
+@synindex vr fn
+
+@ifinfo
+This file documents the GNU Make utility.
+
+Copyright (C) 1988 Richard M. Stallman.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end ifinfo
+@c
+@setchapternewpage odd
+@settitle Make
+
+@titlepage
+@sp 6
+@center @titlefont{GNU Make}
+@sp 1
+@center A Program for Directing Recompilation
+@sp 2
+@center February 1988
+@sp 5
+@center Richard M. Stallman
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1988 Richard M. Stallman.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end titlepage
+@page
+
+@node Top, Simple,, (DIR)
+@chapter Overview of @code{make}
+
+The purpose of the @code{make} utility is to determine automatically which
+pieces of a large program need to be recompiled, and issue the commands to
+recompile them.  This manual describes the GNU implementation of
+@code{make}.
+
+Our examples show C programs, since they are most common, but you can use
+@code{make} with any programming language whose compiler can be run with a
+shell command.  In fact, @code{make} is not limited to programs.  You can
+use it to describe any task where some files must be updated automatically
+from others whenever the others change.
+
+To prepare to use @code{make}, you must write a file called the
+@dfn{makefile} that describes the relationships among files in your
+program, and the states the commands for updating each file.  In a program,
+typically the executable file is updated from object files, which are in
+turn made by compiling source files.
+
+Once a suitable makefile exists, each time you change some source files, this
+simple shell command:
+
+@example
+make
+@end example
+
+@noindent
+suffices to perform all necessary recompilations.  The @code{make} program
+uses the makefile data base and the last-modification times of the files to
+decide which of the files need to be updated.  For each of those files, it
+issues the commands recorded in the data base.
+
+@iftex
+Command arguments to @code{make} can be used to control which files should
+be recompiled, or how.  @xref{Running}.
+@end iftex
+
+GNU @code{make} was implemented by Richard Stallman and Roland McGrath.
+
+@menu
+* Simple::	A simple example explained.
+* Makefiles::	The data base contains rules and variable definitions.
+* Rules::	A rule says how and when to remake one file.
+* Commands::    A rule contains shell commands that say how to remake.
+* Variables::	A variable holds a text string for substitution into rules.
+* Conditionals::Makefiles that do one thing or another depending on
+		 variable values.
+* Functions::   Functions can do text-processing within @code{make}.
+
+* Running::     How to run @code{make}; how you can adjust the way
+                 @code{make} uses the makefile.
+
+* Implicit::	Implicit rules take over if the makefile doesn't say
+		 how a file is to be remade.
+* Archives::    How to use @code{make} to update archive files.
+* Missing::     Features of other @code{make}s not supported by GNU @code{make}.
+* Concept Index::Index of cross-references to where concepts are discussed.
+* Name Index::  Index of cross-references for names of @code{make}'s
+                 variables, functions, special targets and directives.
+@end menu
+
+@node Simple,,Top, Top
+@section Simple Example of @code{make}
+
+Suppose we have a text editor consisting of eight C source files and three
+header files.  We need a makefile to tell @code{make} how to compile and
+link the editor.  Assume that all the C files include @file{defs.h}, but
+only those defining editing commands include @file{commands.h} and only low
+level files that change the editor buffer include @file{buffer.h}.
+
+To recompile the editor, each changed C source file must be recompiled.  If
+a header file has changed, in order to be safe each C source file that
+includes the header file must be recompiled.  Each compilation produces an
+object file corresponding to the source file.  Finally, if any source file
+has been recompiled, all the object files, whether newly made or saved from
+previous compilations, must be linked together to produce the new
+executable editor.
+
+Here is a straightforward makefile that describes these criteria and says
+how to compile and link when the time comes:
+
+@example
+edit : main.o kbd.o commands.o display.o \
+              insert.o search.o files.o utils.o
+        cc -o edit main.o kbd.o commands.o display.o \
+              insert.o search.o files.o utils.o
+
+main.o : main.c defs.h
+        cc -c main.c
+kbd.o : kbd.c defs.h command.h
+        cc -c kbd.c
+commands.o : command.c defs.h command.h
+        cc -c commands.c
+display.o : display.c defs.h buffer.h
+        cc -c display.c
+insert.o : insert.c defs.h buffer.h
+        cc -c insert.c
+search.o : search.c defs.h buffer.h
+        cc -c search.c
+files.o : files.c defs.h buffer.h command.h
+        cc -c files.c
+utils.o : utils.c defs.h
+        cc -c utils.c
+@end example
+
+We split each long line into two lines using a backslash-newline; this is
+like using one long line, but is easier to read.
+
+Each file that is generated by a program---that is to say, each file except
+for source files---is the @dfn{target} of a @dfn{rule} (@pxref{Rules}).
+(In this example, these are the object files such as @file{main.o},
+@file{kbd.o}, etc., and the executable file @file{edit}.)  The target
+appears at the beginning of a line, followed by a colon.
+
+After the colon come the target's @dfn{dependencies}: all the files that
+are used as input when the target file is updated.  A target file needs to
+be recompiled or relinked if any of its dependencies changes.  In addition,
+any dependencies that are themselves automatically generated should be
+updated first.  In this example, @file{edit} depends on each of the
+eight object files; the object file @file{main.o} depends on the source
+file @file{main.c} and on the header file @file{defs.h}.
+
+By default, @code{make} starts with the first rule (not counting rules
+whose target names start with @samp{.}).  This is called the @dfn{default
+goal}.  Therefore, we put the rule for the executable program @file{edit}
+first.  The other rules are processed because their targets appear as
+dependencies in the goal.
+
+After each line containing a target and dependencies come one or more lines
+of shell commands that say how to update the target file.  These lines
+start with a tab to tell @code{make} that they are command lines.
+But @code{make} does not know anything about how the commands work.  It is up
+to you to supply commands that will update the target file properly.  All
+@code{make} does is execute the commands you have specified when the target
+file needs to be updated.
+
+@subsection How @code{make} Processes This Makefile
+
+After reading the makefile, @code{make} begins its real work by processing
+the first rule, the one for relinking @file{edit}; but before it can fully
+process this rule, it must process the rules for the files @file{edit}
+depends on: all the object files.  Each of these files is processed
+according to its own rule.  These rules say to update the @samp{.o} file by
+compiling its source file.  The recompilation must be done if the source
+file, or any of the header files named as dependencies, is more recent than
+the object file, or if the object file does not exist.
+
+Before recompiling an object file, @code{make} considers updating its
+dependencies, the source file and header files.  This makefile does not
+specify anything to be done for them---the @samp{.c} and @samp{.h} files
+are not the targets of any rules---so nothing needs to be done.  But
+automatically generated C programs, such as made by Yacc, would be updated
+by their own rules at this time.
+
+After recompiling whichever object files need it, @code{make} can now
+decide whether to relink @file{edit}.  This must be done if the file
+@file{edit} does not exist, or if any of the object files are newer than
+it.  If an object file was just recompiled, it is now newer than
+@file{edit}, so @file{edit} will be relinked.
+
+@subsection Variables Make Makefiles Simpler
+
+In our example, we had to list all the object files twice in the rule for
+@file{edit} (repeated here):
+
+@example
+edit : main.o kbd.o commands.o display.o \
+              insert.o search.o files.o utils.o
+        cc -o edit main.o kbd.o commands.o display.o \
+              insert.o search.o files.o utils.o
+@end example
+
+@vindex objects
+Such duplication is error-prone; if a new object file is added to the
+system, we might add it to one list and forget the other.  We can eliminate
+the risk and simplify the makefile by using a @dfn{variable}.  Variables
+allow a text string to be defined once and substituted in multiple places
+later (@pxref{Variables}).
+
+It's standard practice for every makefile to have a variable named
+@code{objects}, @code{OBJECTS} or @code{OBJ} which is a list of all object
+file names.  We would define such a variable @code{objects} with a line
+like this in the makefile:
+
+@example
+objects = main.o kbd.o commands.o display.o \
+              insert.o search.o files.o utils.o
+@end example
+
+@noindent
+Then, each place we want to put a list of the object file names, we can
+substitute the variable's value by writing @samp{$(objects)}
+(@pxref{Variables}).  Here is how the rule for @code{edit} looks as a
+result:
+
+@example
+edit : $(objects)
+        cc -o edit $(objects)
+@end example
+
+@subsection Letting @code{make} Deduce the Commands
+
+It is not necessary to spell out the commands for compiling the individual
+C source files, because @code{make} can figure them out: it has an
+@dfn{implicit rule} for updating a @samp{.o} file from a correspondingly
+named @samp{.c} file using a @samp{cc -c} command.  For example, it will
+use the command @samp{cc -c main.c -o main.o} to compile @file{main.c} into
+@file{main.o}.  We can therefore omit the commands from the rules for the
+object files.  @xref{Implicit}.@refill
+
+When a @samp{.c} file is used automatically in this way, it is also
+automatically added to the list of dependencies.  We can therefore omit the
+@samp{.c} files from the dependencies, provided we omit the commands.
+
+Here is the entire example, with both of these changes, and a variable
+@code{objects} as suggested above:
+
+@example
+objects =  main.o kbd.o commands.o display.o \
+ insert.o search.o files.o utils.o
+
+edit : $(objects)
+        cc -o edit $(objects)
+
+main.o : defs.h
+kbd.o : defs.h command.h
+commands.o : defs.h command.h
+display.o : defs.h buffer.h
+insert.o : defs.h buffer.h
+search.o : defs.h buffer.h
+files.o : defs.h buffer.h command.h
+utils.o : defs.h
+@end example
+
+@noindent
+This is how we would write the makefile in actual practice.
+
+@subsection Another Style of Makefile
+
+Since the rules for the object files specify only dependencies, no
+commands, one can alternatively combine them by dependency instead of by
+target.  Here is what it looks like:
+
+@example
+objects =  main.o kbd.o commands.o display.o \
+ insert.o search.o files.o utils.o
+
+edit : $(objects)
+        cc -o edit $(objects)
+
+$(objects): defs.h
+kbd.o commands.o files.o : command.h
+display.o insert.o search.o files.o : buffer.h
+@end example
+
+@noindent
+Here @file{defs.h} is given as a dependency of all the object files;
+@file{commands.h} and @file{buffer.h} are dependencies of the specific
+object files listed for them.
+
+Whether this is better is a matter of taste: it is more compact, but some
+people dislike it because they find it clearer to put all the information
+about each target in one place.
+
+@node Makefiles, Rules, Simple, Top
+@chapter Writing Makefiles
+
+@cindex makefile
+The information that tells @code{make} how to recompile a system comes from
+reading a data base called the @dfn{makefile}.
+
+@menu
+* Contents: Makefile Contents.   Overview of what you put in a makefile.
+* Names: Makefile Names.         Where @code{make} finds the makefile.
+* Include::                      How one makefile can use another makefile.
+@end menu
+
+@node Makefile Contents, Makefile Names, Makefiles, Makefiles
+@section What Makefiles Contain
+
+Makefiles contain four kinds of things: @dfn{rules}, @dfn{variable
+definitions}, @dfn{directives} and @dfn{comments}.  Rules, variables and
+directives are described at length in later chapters.@refill
+
+@itemize @bullet
+@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},
+and may also give commands to use to create or update the targets.
+@xref{Rules}.
+
+@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
+simple makefile example (@pxref{Simple}) shows a variable definition
+for @code{objects} as a list of all object files.  @xref{Variables},
+for full details.
+
+@item
+A directive is a command for @code{make} to do something special while
+reading the makefile.  These include:
+
+@itemize @bullet
+@item
+Reading another makefile (@pxref{Include}).
+
+@item
+Deciding (based on the values of variables) whether to use or ignore a
+part of the makefile (@pxref{Conditionals}).
+
+@item
+Defining a variable from a verbatim string containing multiple lines
+(@pxref{Defining}).
+@end itemize
+
+@item
+@cindex comments
+@samp{#} in a line of a makefile starts a comment.  It and the rest of
+the line are ignored.  Comments may appear on any of the lines in the
+makefile, except within a @code{define} directive, and perhaps within
+commands (where the shell decides what is a comment).  A line
+containing just a comment (with perhaps spaces before it) is
+effectively blank, and is ignored.
+@end itemize
+
+@node Makefile Names, Include, Makefile Contents, Makefiles
+@section What Name to Give Your Makefile
+
+By default, when @code{make} looks for the makefile, it tries the names
+@file{./makefile} or @file{./Makefile} in that order.  So normally you call
+your makefile by one of these two names, and @code{make} finds it
+automatically.  We recommend @file{Makefile} because it appears prominently
+near the beginning of a directory listing.
+
+If @code{make} finds neither of these two names, it does not use any
+makefile.  Then you must specify a goal with a command argument, and
+@code{make} will attempt to figure out how to remake it using only its
+built-in implicit rules.@refill
+
+If you want to use a nonstandard name for your makefile, you can specify
+the makefile name with the @samp{-f} option.  The arguments @samp{-f
+@var{name}} tell @code{make} to read the file @var{name} as the makefile.
+If you use more than one @samp{-f} option, you can specify several
+makefiles.  All the makefiles are effectively concatenated in the order
+specified.  The default makefile names @file{./makefile} and
+@file{./Makefile} are not used if you specify @samp{-f}.@refill
+
+@vindex MAKEFILES
+If the environment variable @code{MAKEFILES} is defined, @code{make}
+considers its value as a list of names (separated by whitespace) of
+additional makefiles to be read before the others.  This works much like
+the @code{include} directive: various directories are searched for those
+files and the default goal is never taken from them.  @xref{Include}.  In
+addition, it is not an error if the files listed in @code{MAKEFILES} are
+not found.
+
+The main use of @code{MAKEFILES} is in communication between recursive
+invocations of @code{make} (@pxref{Recursion}).  It usually isn't
+desirable to set the environment variable before a top-level invocation
+of @code{make}, because it is usually better not to mess with a makefile
+from outside.
+
+Some users are tempted to set @code{MAKEFILES} in the environment
+automatically on login, and program makefiles to expect this to be done.
+This is a very bad idea, because such makefiles will fail to work if run by
+anyone else.  It is much better to write explicit @code{include} directives
+in the makefiles.
+
+@node Include,, Makefile Names, Makefiles
+@section Including Other Makefiles
+
+@findex include
+The @code{include} directive tells @code{make} to suspend reading the
+current makefile and read another makefile before continuing.  The
+directive is a line in the makefile that looks like this:
+
+@example
+include @var{filename}
+@end example
+
+Extra spaces are allowed and ignored at the beginning of the line, but a
+tab is not allowed.  (If the line begins with a tab, it will be considered
+a command line.)  Whitespace is required between @code{include} and
+@var{filename}; extra whitespace is ignored there and at the end of the
+directive.  A comment starting with @samp{#} is allowed at the end of the
+line.
+
+Reading of the containing makefile is temporarily suspended while the file
+@var{filename} is read as a makefile.  When that is finished, @code{make}
+goes on with reading the makefile in which the directive appears.
+
+The default goal target is never taken from an included makefile
+(@pxref{Goals}).
+
+One occasion for using @code{include} directives is when several programs,
+handled by individual makefiles in various directories, need to use a
+common set of variable definitions (@pxref{Setting}) or pattern rules
+(@pxref{Pattern Rules}).
+
+If the specified name does not start with a slash, and the file is not
+found in the current directory, several other directories are searched.
+First, any directories you have specified with the @samp{-I} option are
+searched (@pxref{Options}).  Then the following directories (if they
+exist) are searched, in this order: @file{/usr/gnu/include},
+@file{/usr/local/include}, @file{/usr/include}.@refill
+
+@node Rules, Commands, Makefiles, Top
+@chapter Writing Rules
+
+@cindex rule
+@cindex target
+@cindex dependency
+A @dfn{rule} appears in the makefile and says when and how to remake
+certain files, called the rule's @dfn{targets} (usually only one per rule).
+It lists the other files that are the @dfn{dependencies} of the target, and
+@dfn{commands} to use to create or update the target.
+
+The order of rules is not significant, except for determining the
+@dfn{default goal}: the target for @code{make} to consider, if you do not
+otherwise specify one.  The default goal comes from the first rule (not
+counting included makefiles) whose target does not start with a period.
+Therefore, the first rule is normally one for compiling the entire program
+or all the programs described by the makefile.  @xref{Goals}.
+
+@menu
+* Rule Example::        An explained example of a rule.
+* Rule Syntax::	        General syntax of rules, with explanation.
+
+* Wildcards::	        Using wildcard characters like `*' in file names.
+* Directory Search::    Searching other directories for source files.
+
+* Phony Targets::       Using a target that isn't a real file's name.
+* Special Targets::     Targets with special built-in meanings.
+* Empty Targets::       Real files that are empty--only the date matters.
+* Multiple Targets::    When it is useful to have several targets in a rule.
+* Multiple Rules::      Using several rules with the same target.
+* Double-Colon::        Special kind of rule allowing
+                          several independent rules for one target.
+* Commands::            Special features and details of how commands
+                         in a rule are executed.
+@end menu
+
+@ifinfo
+@node Rule Example, Rule Syntax, Rules, Rules
+@isubsection Rule Example
+
+Here is an example of a rule:
+
+@example
+foo.o : foo.c defs.h       # module for twiddling the frobs
+        cc -c -g foo.c
+@end example
+
+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.
+
+This rule says two things:
+
+@itemize @bullet
+@item
+How to decide whether @file{foo.o} is out of date: it is out of date
+if it does not exist, or if either @file{foo.c} or @file{defs.h} is
+more recent than it.
+
+@item
+How to update the file @file{foo.o}: by running @code{cc} as stated.
+The command does not explicitly mention @file{defs.h}, but we presume
+that @file{foo.c} includes it, and that that is why @file{defs.h} was
+added to the dependencies.
+@end itemize
+@end ifinfo
+
+@node Rule Syntax, Wildcards, Rule Example, Rules
+@section Rule Syntax
+
+In general, a rule looks like this:
+
+@example
+@var{targets} : @var{dependencies}
+        @var{command}
+        @var{command}
+        ...
+@end example
+
+@noindent
+or like this:
+
+@example
+@var{targets} : @var{dependencies} ; @var{command}
+        @var{command}
+        @var{command}
+        ...
+@end example
+
+The @var{targets} are file names, separated by spaces.  Wild card
+characters may be used (@pxref{Wildcards}) and a name of the form
+@file{@var{a}(@var{m})} represents member @var{m} in archive file @var{a}
+(@pxref{Archive Members}).  Usually there is only one target per rule, but
+occasionally there is a reason to have more (@pxref{Multiple Targets}).
+
+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
+appear on the same line, with a semicolon.  Either way, the effect is the
+same.  @xref{Commands}.
+
+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{Variables}.  A long line may be split by inserting a backslash
+followed by a newline, but this is not required, as there is no limit on
+the length of a line.
+
+A rule tells @code{make} two things: when the targets are out of date,
+and how to update them when necessary.
+
+The criterion for being out of date is specified in terms of the
+@var{dependencies}, which consist of file names separated by spaces.
+(Wildcards and archive members are allowed here too.)  A target is out of
+date if it does not exist or if it is older than any of the dependencies
+(by comparison of last-modification times).  The idea is that the contents
+of the target file are computed based on information in the dependencies,
+so if any of the dependencies changes the contents of the existing target
+file are no longer necessarily valid.
+
+How to remake is specified by @var{commands}.  These are lines to be
+executed by the shell (normally @samp{sh}), but with some extra features
+(@pxref{Commands}).
+
+@node Wildcards, Directory Search, Rule Syntax, Rules
+@section Using Wildcards Characters in File Names
+@cindex wildcard
+@cindex file name
+
+A single file name can specify many files using @dfn{wildcard characters}.
+The wildcard characters in @code{make} are @samp{*}, @samp{?} and
+@samp{[@dots{}]}, the same as in the Bourne shell.  For example, @file{*.c}
+specifies a list of all the files (in the working directory) whose names
+end in @samp{.c}.@refill
+
+Wildcard expansion happens automatically in targets, in dependencies, and
+in commands.  In other contexts, wildcard expansion happens only if you
+request it explicitly with the @code{wildcard} function.
+
+The special significance of a wildcard character can be turned off by
+preceding it with a backslash.  Thus, @file{foo\*bar} would refer to a
+specific file whose name consists of @samp{foo}, an asterisk, and
+@samp{bar}.@refill
+
+@menu
+* Examples: Wildcard Examples.    Some simple examples.
+* Pitfall: Wildcard Pitfall.      @code{*.o} won't do what you want!
+* Function: Wildcard Function.
+       How to do wildcard expansion when defining a variable
+       using the function @code{wildcard}.
+@end menu
+
+@node Wildcard Examples, Wildcard Function, Wildcards, Wildcards
+@subsection Wildcard Examples
+
+Wildcards can be used in the commands of a rule.  For example, here is a
+rule to delete all the object files:
+
+@example
+clean:
+        rm -f *.o
+@end example
+
+Wildcards are also useful in the dependencies of a rule.  With the
+following rule in the makefile, @samp{make print} will print all the
+@samp{.c} files that have changed since the last time you printed them:
+
+@example
+print: *.c
+        lpr -p $?
+        touch print
+@end example
+
+@noindent
+This rule uses @file{print} as an empty target file; @pxref{Empty Targets}.
+
+Wildcard expansion does not happen when you define a variable.  Thus, if
+you write this:
+
+@example
+objects=*.o
+@end example
+
+@noindent
+then the value of the variable @code{objects} is the actual string
+@samp{*.o}.  However, if you use the value of @code{objects} in a target,
+dependency or command, wildcard expansion will take place at that time.
+
+@node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards
+@subsection Pitfalls of Using Wildcards
+
+Now here is an example of a naive way of using wildcard expansion, that
+does not do what you would intend.  Suppose you would like to say that the
+executable file @file{foo} is made from all the object files in the
+directory, and you write this:
+
+@example
+objects=*.o
+
+foo : $(objects)
+        cc -o foo $(CFLAGS) $(objects)
+@end example
+
+@noindent
+The value of @code{objects} is the actual string @samp{*.o}.  Wildcard
+expansion happens in the rule for @file{foo}, so that each @emph{existing}
+@samp{.o} file becomes a dependency of @file{foo} and will be recompiled if
+necessary.
+
+But what if you delete all the @samp{.o} files?  Then @samp{*.o} will
+expand into @emph{nothing}.  The target @file{foo} will have no
+dependencies and would be remade by linking no object files.  This is not
+what you want!
+
+Actually you can use wildcard expansion for this purpose, but you need more
+sophisticated techniques, including the @code{wildcard} function and string
+substitution.
+@ifinfo
+@xref{Wildcard Function}.
+@end ifinfo
+@iftex
+These are described in the following section.
+@end iftex
+
+@node Wildcard Function,, Wildcard Pitfall, Wildcards
+@subsection The Function @code{wildcard}
+@findex wildcard
+
+Wildcard expansion happens automatically in rules.  But wildcard expansion
+does not normally take place when a variable is set, or inside the
+arguments of a function.  If you want to do wildcard expansion in such
+places, you need to use the @code{wildcard} function, like this:
+
+@example
+$(wildcard @var{pattern})
+@end example
+
+This string, used anywhere in a makefile, is replaced by a space-separated
+list of names of existing files that match the pattern @var{pattern}.
+
+One use of the @code{wildcard} function is to get a list of all the C source
+files in a directory, like this:
+
+@example
+$(wildcard *.c)
+@end example
+
+We can change the list of C source files into a list of object files by
+substituting @samp{.o} for @samp{.c} in the result, like this:
+
+@example
+$(subst .c,.o,$(wildcard *.c))
+@end example
+
+Here we have used another function, @code{subst} (@pxref{Text Functions}).
+
+Thus, a makefile to compile all C source files in the directory and then
+link them together could be written as follows:
+
+@example
+objects=$(subst .c,.o,$(wildcard *.c))
+
+foo : $(objects)
+        cc -o foo $(LDFLAGS) $(objects)
+@end example
+
+@noindent
+(This takes advantage of the implicit rule for compiling C programs, so
+there is no need to write explicit rules for compiling the files.)
+
+@node Directory Search, Phony Targets, Wildcards, Rules
+@section Searching Directories for Dependencies
+@vindex VPATH
+@cindex directory search
+
+For large systems, it is often desirable to put sources in a separate
+directory from the binaries.  The @code{VPATH} feature makes this easier.
+
+The value of the variable @code{VPATH} is a list of directories which
+@code{make} should search (in the order specified) for dependency files.
+The directory names are separated by colons.  For example:
+
+@example
+VPATH = src:../headers
+@end example
+
+@noindent
+specifies a path containing two directories, @file{src} and @file{../headers}.
+
+When a file listed as a dependency does not exist in the current directory,
+the directories listed in @code{VPATH} are searched 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 as if they all existed in
+the current directory.
+
+Using the value of @code{VPATH} set in the previous example, a rule like this:
+
+@example
+foo.o : foo.c
+@end example
+
+@noindent
+is interpreted as if it were written like this:
+
+@example
+foo.o : src/foo.c
+@end example
+
+@noindent
+assuming the file @file{foo.c} does not exist in the current directory but
+is found in the directory @file{src}.
+
+But what about the rule's commands?  The @code{VPATH} directory search
+cannot change the commands; they will execute as written.  You need to
+write the commands so that they will use the file names that @code{make}
+finds.  This is done with the @dfn{automatic variables} such as @samp{$^}
+(@pxref{Automatic}).  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:
+
+@example
+foo.o : foo.c
+        cc -c $(CFLAGS) $^ -o $@@
+@end example
+
+@noindent
+The variable @code{CFLAGS} exists so you can specify flags for C
+compilation by changing its value; we use it here for consistency so it
+will affect all C compilations uniformly.  (@pxref{Implicit Variables}).
+
+Often the dependencies include header files as well, which you don't want
+to mention in the commands.  The function @code{firstword} can be used to
+extract just the first dependency from the entire list, as shown here
+(@pxref{Filename Functions}):
+
+@example
+foo.o : foo.c defs.h hack.h
+        cc -c $(CFLAGS) $(firstword $^) -o $@@
+@end example
+
+@noindent
+Here the value of @samp{$^} is something like @samp{src/foo.c
+../headers/defs.h hack.h}, from which @samp{$(firstword $^)} extracts just
+@samp{src/foo.c}.@refill
+
+@subsection Directory Search and Implicit Rules
+
+The search through the directories in @code{VPATH} happens also during
+consideration of implicit rules (@pxref{Implicit}).
+
+For example, when a file @file{foo.o} has no explicit rule, @code{make}
+considers implicit rules, such as to compile @file{foo.c} if that file
+exists.  If such a file is lacking in the current directory, the
+directories in @code{VPATH} are searched for it.  If @file{foo.c} exists
+(or is mentioned in the makefile) in any of the directories, the implicit
+rule for C compilation is applicable.
+
+The commands of all the built-in implicit rules normally use automatic
+variables as a matter of necessity; consequently they will use the file
+names found by directory search with no extra effort.
+
+@node Phony Targets, Empty Targets, Directory Search, Rules
+@section Phony Targets
+
+A phony target is one that is not really the name of a file.
+It is only a name for some commands to be executed when explicitly
+requested.
+
+If you write a rule whose commands will not create the target file, the
+commands will be executed every time the target comes up for remaking.
+Here is an example:
+
+@example
+clean:
+        rm *.o temp
+@end example
+
+@noindent
+Because the @code{rm} command does not create a file named @file{clean},
+probably no such file will ever exist.  Therefore, the @code{rm} command
+will be executed every time you say @samp{make clean}.
+
+@findex .PHONY
+The phony target will cease to work if anything ever does create a file
+named @file{clean} in this directory.  Since there are no dependencies, the
+@file{clean} would be considered up-to-date and its commands would not be
+executed.  To avoid this problem, you can explicitly declare the target to
+be phony, using the special target @code{.PHONY} (@pxref{Special Targets})
+as follows:
+
+@example
+.PHONY : clean
+@end example
+
+@noindent
+Once this is done, @code{make} will run the commands regardless of whether
+there is a file named @file{clean}.
+
+A phony target should not be a dependency of a real target file; strange
+things can result from that.  As long as you don't do that, the phony
+target commands will be executed only when the phony target is a goal
+(@pxref{Goals}).
+
+Phony targets can have dependencies.  When one directory contains multiple
+programs, it is most convenient to describe all of the programs in one
+makefile @file{./Makefile}.  Since the target remade by default will be the
+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:
+
+@example
+all : prog1 prog2 prog3
+.PHONY : all
+
+prog1 : prog1.o utils.o
+        cc -o prog1 prog1.o utils.o
+
+prog2 : prog2.o
+        cc -o prog2 prog2.o
+
+prog3 : prog3.o sort.o utils.o
+        cc -o prog3 prog3.o sort.o utils.o
+@end example
+
+@noindent
+Now you can say @code{make} to remake all three programs, or specify
+as arguments the ones to remake (as in @samp{make prog1 prog3}).
+
+When one phony target is a dependency of another, it serves as a subroutine
+of the other.  For example, here @samp{make cleanall} will delete the
+object files, the difference files, and the file @file{program}:
+
+@example
+cleanall : cleanobj cleandiff
+        rm program
+
+cleanobj :
+        rm *.o
+
+cleandiff :
+        rm *.diff
+@end example
+
+@node Empty Targets, Special Targets, Phony Targets, Rules
+@section Empty Target Files to Record Events
+@cindex empty target
+
+The @dfn{empty target} is a variant of the phony target; it is used to hold
+commands for an action that you request explicitly from time to time.
+Unlike a phony target, this target file can really exist; but the file's
+contents do not matter, and usually are empty.
+
+The purpose of the empty target file is to record, with its
+last-modification-time, when the rule's commands were last executed.  It
+does so because one of the commands is a @code{touch} command to update the
+target file.
+
+The empty target file must have some dependencies.  When you ask to remake
+the empty target, the commands are executed if any dependency is more
+recent than the target; in other words, if a dependency has changed since
+the last time you remade the target.  Here is an example:
+
+@example
+print: foo.c bar.c
+        lpr -p $?
+        touch print
+@end example
+
+@noindent
+With this rule, @samp{make print} will execute the @code{lpr} command if
+either source file has changed since the last @samp{make print}.  The
+automatic variable @samp{$?} is used to print only those files that have
+changed (@pxref{Automatic}).
+
+@node Special Targets, Multiple Targets, Empty Targets, Rules
+@section Special Built-in Target Names
+@cindex special targets
+
+Certain names have special meanings if they appear as targets.
+
+@table @code
+@item .PHONY
+The dependencies of the special target @code{.PHONY} are considered to
+be phony targets.  When it is time to consider such a target,
+@code{make} will run its commands unconditionally, regardless of
+whether a file with that name exists or what its date is.  @xref{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 (@pxref{Suffix
+Rules}).
+
+@item .DEFAULT
+The commands specified for @code{.DEFAULT} are used for any target for
+which no other commands are known (either explicitly or through an
+implicit rule).  If @code{.DEFAULT} commands are specified, every
+nonexistent file mentioned as a dependency will have these commands
+executed on its behalf.  @xref{Search Algorithm}.
+
+@item .PRECIOUS
+The targets which @code{.PRECIOUS} depends on are given this special
+treatment: if @code{make} is killed or interrupted during the
+execution of their commands, the target is not deleted.
+@xref{Interrupts}.
+
+@item .IGNORE
+Simply by being mentioned as a target, @code{.IGNORE} says to ignore
+errors in execution of commands.  The dependencies and commands for
+@code{.IGNORE} are not meaningful.
+
+@samp{.IGNORE} exists for historical compatibility.  Since
+@code{.IGNORE} affects every command in the makefile, it is not very
+useful; we recommend you use the more selective ways to ignore errors
+in specific commands (@pxref{Errors}).
+
+@item .SILENT
+Simply by being mentioned as a target, @code{.SILENT} says not to
+print commands before executing them.  The dependencies and commands
+for @code{.SILENT} are not meaningful.
+
+@samp{.SILENT} exists for historical compatibility.  We recommend you
+use the more selective ways to silence specific commands
+(@pxref{Echoing}).
+@end table
+
+An entire class of special targets have names made of the concatenation of
+two implicit rule suffixes (two members of the list of dependencies of
+@code{.SUFFIXES}).  Such special targets are suffix rules, an obsolete way
+of defining implicit rules (but a way still widely used).  In principle,
+any target name could be special in this way if you break it in two and add
+both pieces to the suffix list.  In practice, suffixes normally begin with
+@samp{.}, so these special target names also begin with @samp{.}.
+@xref{Suffix Rules}.
+
+@node Multiple Targets, Multiple Rules, Special Targets, Rules
+@section Multiple Targets in a Rule
+
+A rule with multiple targets is equivalent to writing many rules, each with
+one target, and all identical aside from that.  This is useful in two cases.
+
+@itemize @bullet
+@item
+You want just dependencies, no commands.  For example:
+
+@example
+kbd.o commands.o files.o: command.h
+@end example
+
+@noindent
+gives an additional dependency to each of the three object files
+mentioned.
+
+@item
+Identical commands work for all the targets.  The automatic variable
+@samp{$@@} can be used to substitute the target to be remade into the
+commands (@pxref{Automatic}).  For example:
+
+@example
+bigoutput littleoutput : text.g
+        generate text.g -$(subst output,,$@@) > $@@
+@end example
+
+@noindent
+is equivalent to
+
+@example
+bigoutput : text.g
+        generate text.g -big > bigoutput
+littleoutput : text.g
+        generate text.g -little > littleoutput
+@end example
+
+@noindent
+Here we assume the hypothetical program @code{generate} makes two
+types of output, one if given @samp{-big} and one if given
+@samp{-little}.@refill
+@end itemize
+
+@node Multiple Rules, Double-Colon, Multiple Targets, Rules
+@section Multiple Rules for One Target
+
+One file can be the target of several rules if at most one rule has commands.
+The other rules can only have dependencies.  All the dependencies mentioned
+in all the rules are merged into one list of dependencies for the target.
+If the target is older than any dependency from any rule, the commands are
+executed.
+
+An extra rule with just dependencies can be used to give a few extra
+dependencies to many files at once.  For example, one usually has a
+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
+
+@example
+objects = foo.o bar.o
+foo.o : defs.h
+bar.o : defs.h test.h
+$(objects) : config.h
+@end example
+
+This could be inserted or taken out without changing the rules that really
+say how to make the object files, making it a convenient form to use if
+you wish to add the additional dependency intermittently.
+
+Another wrinkle is that the additional dependencies could be specified with
+a variable that you could set with a command argument to @code{make}
+(@pxref{Overriding}).  For example,
+
+@example
+extradeps=
+$(objects) : $(extradeps)
+@end example
+
+@noindent
+means that the command @samp{make extradeps=foo.h} will consider
+@file{foo.h} as a dependency of each object file, but plain @samp{make}
+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}.
+
+@node Double-Colon,, Multiple Rules, Rules
+@section Double-Colon Rules
+@cindex double-colon rule
+
+@dfn{Double-colon} rules are rules written with @samp{::} instead of
+@samp{:} after the target names.  They are handled differently from
+ordinary rules when the same target appears in more than one rule.
+
+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.
+
+The double-colon rules for a target are executed in the order they appear
+in the makefile.  However, the cases where double-colon rules really make
+sense are those where the order of executing the commands would not matter.
+
+Each double-colon rule should specify commands; if it does not, an
+implicit rule will be used if one applies.  @xref{Implicit}.
+
+@node Commands, Variables, Rules, Top
+@chapter Writing the Commands in Rules
+@cindex command (in rules)
+
+The commands of a rule consist of shell command lines to be executed one by
+one.  Each command line must start with a tab, except that the first
+command line may be attached to the target-and-dependencies line with a
+semicolon in between.  Blank lines and lines of just comments may appear
+among the command lines; they are ignored.
+
+Users use many different shell programs, but commands in makefiles are
+always interpreted by @file{/bin/sh} unless the makefile specifies otherwise.
+
+Whether comments can be written on command lines, and what syntax they use,
+is under the control of the shell that is in use.  If it is @file{/bin/sh},
+a @samp{#} at the start of a word starts a comment.
+
+@menu
+* Echoing::       Normally commands are echoed before execution,
+                    but you can control this in several ways.
+* Execution::     How commands are executed.
+* Errors::	  What happens after an error in command execution.
+		   How to ignore errors in certain commands.
+* Interrupts::	  If a command is interrupted or killed,
+		   the target may be deleted.
+* Recursion::	  Invoking @code{make} from commands in makefiles.
+* Sequences::     Defining canned sequences of commands.
+@end menu
+
+@node Echoing, Execution, Commands, Commands
+@section Command Echoing
+
+@cindex echoing (of commands)
+@cindex silent operation
+@cindex @@ (in commands)
+@cindex -n
+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.
+
+When a line starts with @samp{@@}, it is normally not echoed.  The
+@samp{@@} is discarded before the command is passed to the shell.  Typically
+you would use this for a command whose only effect is to print something,
+such as an @code{echo} command.
+
+When @code{make} is given the flag @samp{-n}, echoing is all that happens,
+no execution.  @xref{Options}.  In this case and only this case, even the
+commands starting with @samp{@@} are printed.  This flag is useful for
+finding out which commands @code{make} thinks are necessary without
+actually doing them.
+
+@cindex -s
+@findex .SILENT
+The @samp{-s} flag to @code{make} prevents all echoing, as if all commands
+started with @samp{@@}.  A rule in the makefile for the special target
+@code{.SILENT} has the same effect (@pxref{Special Targets}).
+@code{.SILENT} is essentially obsolete since @samp{@@} is more
+general.@refill
+
+@node Execution, Errors, Echoing, Commands
+@section Command Execution
+@cindex execution
+@cindex shell
+
+When it is time to execute commands to update a target, they are executed
+one at a time by making a new subshell for each line.  (In practice,
+@code{make} may take shortcuts that do not affect the results.)
+
+This implies that shell commands such as @code{cd} that set variables local
+to each process will not affect the following command lines.  If you want
+to use @code{cd} to affect the next command, put the two on a single line
+with a semicolon between them.  Then @code{make} will consider them a
+single command and pass them, together, to a shell which will execute them
+in sequence.  For example:
+
+@example
+foo : bar/lose
+        cd bar; gobble lose > ../foo
+@end example
+
+If you would like to split a single shell command into multiple lines of
+text, you must use a backslash at the end of all but the last subline.
+Such a sequence of lines is combined into a single line, by deleting the
+backslash-newline sequences, before passing it to the shell.  Thus, the
+following is equivalent to the preceding example:
+
+@group
+@example
+foo : bar/lose
+        cd bar;  \
+        gobble lose > ../foo
+@end example
+@end group
+
+@vindex SHELL
+@vindex SHFLAGS
+The program used as the shell is taken from the variable @code{SHELL}.  By
+default, the program @file{/bin/sh} is used.
+
+Unlike most variables, the variable @code{SHELL} will not be set from the
+environment, except in a recursive @code{make}.  This is because the
+environment variable @code{SHELL} is used to specify your personal choice
+of shell program for interactive use.  It would be very bad for personal
+choices like this to affect the functioning of makefiles.
+@xref{Environment}.
+
+The value of the variable @code{SHFLAGS} is used as additional command
+arguments to give to the shell each time it is run.  By default, the
+value is empty.  This variable also is not set from the environment
+except in recursive use of @code{make}.
+
+@node Errors, Interrupts, Execution, Commands
+@section Errors in Commands
+
+@cindex error (in commands)
+After each shell command returns, @code{make} looks at its exit status.
+If the command completed successfully, the next command line is executed in
+a new shell, or after the last command line the rule is finished.
+
+If there is an error (the exit status is nonzero), @code{make} gives up on
+the current rule, and perhaps on all rules.
+
+Sometimes it does not matter whether a command fails.  For example, you
+may use the @code{mkdir} command to insure that a directory exists.  If
+the directory already exists, @code{mkdir} will report an error, but you
+probably want @code{make} to continue regardless.
+
+@cindex - (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.
+
+@cindex -i
+@findex .IGNORE
+When @code{make} is run with the @samp{-i} flag, errors are ignored in
+all commands of all rules.  A rule in the makefile for the special target
+@code{.IGNORE} has the same effect.  These ways of ignoring errors are
+obsolete because @samp{-} is more general.
+
+When errors are to be ignored, because of either a @samp{-} or the
+@samp{-i} flag, @code{make} treats an error return just like success.
+
+@cindex -k
+When an error happens that @code{make} has not been told to ignore,
+it implies that the current target cannot be correctly remade, and neither
+can any other that depends on it either directly or indirectly.  No further
+commands will be executed for these targets, since their preconditions
+have not been achieved.
+
+Normally @code{make} gives up immediately in this circumstance, returning a
+nonzero status.  However, if the @samp{-k} flag is specified, @code{make}
+continues to consider the other dependencies of the pending targets,
+remaking them if necessary, before it gives up and returns nonzero status.
+For example, after an error in compiling one object file, @samp{make -k}
+will continue compiling other object files even though it already knows
+that linking them will be impossible.  @xref{Options}.
+
+The usual behavior assumes that your purpose is to get the specified
+targets up to date; once @code{make} learns that this is impossible, it
+might as well report the failure immediately.  @samp{-k} says that the real
+purpose is to test as much as possible of the changes made in the program,
+perhaps to find several independent problems so that you can correct them
+all before the next attempt to compile.  This is why Emacs's @code{compile}
+command passes the @samp{-k} flag by default.
+
+@node Interrupts, Recursion, Errors, Commands
+@section Interrupting or Killing @code{make}
+@cindex interrupt
+@cindex signal
+@cindex deletion of target files
+
+If @code{make} gets a fatal signal while a command is executing, it may
+delete the target file that the command was supposed to update.  This is
+done if the target file's date has changed since @code{make} first checked it.
+
+The purpose of deleting the target is to make sure that it is remade from
+scratch when @code{make} is next run.  Otherwise, a partially written file
+could appear to be valid, since it is more recent than the dependencies.
+
+@findex .PRECIOUS
+You can prevent the deletion of a target file in this way by making the
+special target @code{.PRECIOUS} depend on it.  Before remaking a target,
+@code{make} checks to see whether it appears on the dependencies of
+@code{.PRECIOUS}, and thereby decides whether the target should be
+deleted if a signal happens.  Some reasons why you might do this are
+that the target is updated in some atomic fashion or exists only to
+record a date/time (its contents do not matter) or will cause trouble
+if it ever fails to exist.
+
+@node Recursion, Sequences, Interrupts, Commands
+@section Recursive Use of @code{make}
+@cindex recursion
+@vindex MAKE
+
+Recursive use of @code{make} means using @code{make} as a command in a
+makefile.  This technique is useful when you want separate makefiles for
+various subsystems that compose a larger system.  For example, suppose you
+have a subdirectory @file{subdir} which has its own makefile, and you would
+like the containing directory's makefile to run @code{make} on the
+subdirectory.
+
+You can do it by writing this:
+
+@example
+subsystem:
+        cd subdir; $(MAKE)
+@end example
+
+@noindent
+or, equivalently, this (@pxref{Options}):
+
+@example
+subsystem:
+        $(MAKE) -c subdir
+@end example
+
+That's all you have to write in the makefile to cause the sub-@code{make}
+to be run if you do @code{make subsystem}, but there are other things you
+should know about how this does its job and how the sub-@code{make} relates
+to the top-level @code{make}.
+
+The commands above use the variable @code{MAKE}, whose value is the file
+name with which @code{make} was invoked.  If this file name was
+@file{/bin/make}, then the command executed is @samp{cd subdir; /bin/make}.
+If you use a special version of @code{make} to run the top-level makefile,
+the same special version will be executed for recursive invocations.  Also,
+any arguments that define variable values are added to @code{MAKE}, so the
+sub-@code{make} gets them too.  Thus, if you do @samp{make CFLAGS=-O}, so
+that all C-compilations will be optimized, the sub-@code{make} is run with
+@samp{cd subdir; /bin/make CFLAGS=-O}.
+
+The flag options you give to the top-level @code{make} are passed down
+to the sub-@code{make} automatically, through the variable @code{MAKEFLAGS}
+as described below.
+
+All the other variable values of the top-level @code{make} are passed to
+the sub-@code{make} through the environment.  These variables are defined
+in the sub-@code{make} as defaults, but do not override what is specified
+in the sub-@code{make}'s makefile.  The way this works is that @code{make}
+adds each variable and its value to the environment for running each
+command.  (Variables whose names start with non-alphanumeric characters are
+left out.)  The sub-@code{make}, in turn, uses the environment to
+initialize its table of variable values.  @xref{Environment}.
+
+@vindex MAKELEVEL
+As a special feature, the variable @code{MAKELEVEL} is changed when it is
+passed down from level to level.  This variable's value is a string which
+is the depth of the level as a decimal number.  The value is @samp{0} for
+the top-level @code{make}; @samp{1} for a sub-@code{make}, @samp{2} for a
+sub-sub-@code{make}, and so on.  The incrementation happens when
+@code{make} sets up the environment for a command.@refill
+
+The main use of @code{MAKELEVEL} is to test it in a conditional directive
+(@pxref{Conditionals}); this way you can write a makefile that behaves one
+way if run recursively and another way if run directly by you.
+
+@vindex MAKEFLAGS
+Flags such as @samp{-s} and @samp{-k} are passed automatically to the
+sub-@code{make} through the variable @code{MAKEFLAGS}.  This variable is
+set up automatically by @code{make} to contain the flag letters that
+@code{make} received.  Thus, if you do @samp{make -ks} then
+@code{MAKEFLAGS} gets the value @samp{ks}.
+
+As a consequence, every sub-@code{make} gets a value for @code{MAKEFLAGS}
+in its environment.  In response, it takes the flags from that value and
+processes them as if they had been given as arguments.  @xref{Options}.
+
+The options @samp{-c}, @samp{-d}, @samp{-f}, @samp{-I}, @samp{-o}, and
+@samp{-p} are not put into @code{MAKEFLAGS}; these options are not
+passed down.@refill
+
+If you don't want to pass the other the flags down, you must change the
+value of @code{MAKEFLAGS}, like this:
+
+@example
+subsystem:
+        cd subdir; $(MAKE) MAKEFLAGS=
+@end example
+
+@vindex MFLAGS
+A similar variable @code{MFLAGS} exists also, for historical compatibility.
+It has the same value as @code{MAKEFLAGS} except that a hyphen is added at
+the beginning if it is not empty.  @code{MFLAGS} was traditionally used
+explicitly in the recursive @code{make} command, like this:
+
+@example
+subsystem:
+        cd subdir; $(MAKE) $(MFLAGS)
+@end example
+
+@noindent
+but now @code{MAKEFLAGS} makes this usage redundant.
+
+What about @samp{make -t}?  (@xref{Instead of Execution}.)  Following the
+usual definition of @samp{-t}, this would create a file named
+@file{subsystem}.  What you really want it to do is run @samp{cd subdir;
+make -t}; but that would require executing the command, and @samp{-t} says
+not to execute commands.@refill
+
+The paradox is resolved by a special @code{make} feature: whenever a
+command uses the variable @code{MAKE}, the flags @samp{-t}, @samp{-n} or
+@samp{-q} do not apply to that rule.  The commands of that rule are
+executed normally despite the presence of a flag that causes most
+commands not to be run.  These flags are passed along via
+@code{MAKEFLAGS}, so your request to touch the files, or print the
+commands, is propagated to the subsystem.
+
+@vindex MAKEFILES
+If the environment variable @code{MAKEFILES} is defined, @code{make}
+considers its value as a list of names (separated by whitespace) of
+additional makefiles to be read before the others.  This works much like
+the @code{include} directive: various directories are searched for those
+files and the default goal is never taken from them.  @xref{Include}.  In
+addition, it is not an error if the files listed in @code{MAKEFILES} are
+not found.
+
+The main use of @code{MAKEFILES} is with recursive invocation of @code{make}.
+The outer @code{make} can set @code{MAKEFILES} to influence recursive
+@code{make} levels.
+
+@node Sequences,, Recursion, Commands
+@section Defining Canned Command Sequences
+@cindex sequences of commands
+
+When the same sequence of commands is useful in making various targets, you
+can define it as a canned sequence with the @code{define} directive, and
+refer to the canned sequence from the rules for those targets.  The canned
+sequence is actually a variable, so the name must not conflict with other
+variable names.
+
+Here is an example of defining a canned sequence of commands:
+
+@example
+define run-yacc
+yacc $(firstword $^)
+mv y.tab.c $@@
+endef
+@end example
+
+@noindent
+Here @code{run-yacc} is the name of the variable being defined;
+@code{endef} marks the end of the definition; the lines in between are the
+commands.  The @code{define} directive does not expand variable references
+and function calls in the canned sequence; the @samp{$} characters,
+parentheses, variable names, and so on, all become part of the value of the
+variable you are defining.  @xref{Defining}, for a complete explanation of
+@code{define}.
+
+The first command in this example runs Yacc on the first dependency (of
+whichever rule uses the canned sequence).  The output file from Yacc is
+always named @file{y.tab.c}.  The second command moves the output to the
+rule's target file name.
+
+To use the canned sequence, substitute the variable into the commands of a
+rule.  You can substitute it like any other variable (@pxref{Reference}).
+But usually substitution alone is not enough, because the commands in a
+canned sequence typically contain variable references that should be
+expanded each time the canned sequence is used.  To make this work, you
+need to use the @code{expand} function when you substitute the sequence
+(@pxref{Expand Function}).  Here is how it looks:
+
+@example
+foo.c : foo.y
+        $(expand $(run-yacc))
+@end example
+
+@noindent
+The @code{expand} function will substitute @samp{foo.y} for the variable
+@samp{$^} when it occurs in @code{run-yacc}'s value, and @samp{foo.c} for
+@samp{$@@}.@refill
+
+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}.
+
+@node Variables, Conditionals, Commands, Top
+@chapter How to Use Variables
+@cindex variable
+@cindex value
+
+A @dfn{variable} is a name defined within @code{make} to represent a string
+of text, called the variable's @dfn{value}.  These values can be
+substituted by explicit request into targets, dependencies, commands and
+other parts of the makefile.
+
+Variables can represent lists of file names, options to pass to compilers,
+programs to run, directories to look in for source files, directories to
+write output in, or anything else you can imagine.
+
+A variable name may be any sequence characters not containing @samp{:},
+@samp{#}, @samp{=}, tab characters or leading or trailing spaces.  However,
+variable names containing nonalphanumeric characters should be avoided, as
+they may be given special meanings in the future.
+
+It is traditional to use upper case letters in variable names, but we
+recommend using lower case letters for variable names that serve internal
+purposes in the makefile, and reserving upper case for parameters that
+control implicit rules or for parameters that the user should override with
+command options (@pxref{Overriding}).
+
+@menu
+* Reference::	How to use the value of a variable.
+* Values::      All the ways variables get their values.
+* Setting::	How to set a variable in the makefile.
+* Override Directive:: Setting a variable in the makefile
+		 even if the user has set it with a command argument.
+* Defining::    An alternate way to set a variable to a verbatim string.
+* Environment:: Variable values can come from the environment.
+@end menu
+
+@node Reference, Values, Variables, Variables
+@section Reference to Variables
+@cindex reference to variables
+@cindex $
+
+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
+@samp{$@{foo@}} is a valid reference to the variable @code{foo}.  This
+special significance of @samp{$} is why you must write @samp{$$} to have
+the effect of a single dollar sign in a file name or command.
+
+Variable references can be used in any context: targets, dependencies,
+commands, most directives, and new variable values.  Here is a common kind
+of example, where a variable holds the names of all the object files in a
+program:
+
+@example
+objects = program.o foo.o utils.o
+program : $(objects)
+        cc -o program $(objects)
+
+$(objects) : defs.h
+@end example
+
+Variable references work by strict textual substitution.  Thus, the rule
+
+@example
+foo = c
+prog.o : prog.c
+        $(foo)$(foo) prog.c
+@end example
+
+@noindent
+could be used to compile a C program @file{prog.c}.  (Since spaces around
+the variable value are ignored in variable assignments, the value of
+@code{foo} is precisely @samp{c}.)
+
+A dollar sign followed by a character other than a dollar sign,
+open-parenthesis or open-brace treats that single character as the variable
+name.  Thus, you could reference the variable @code{x} with @samp{$x}.
+However, this practice is strongly discouraged, except with the automatic
+variables (@pxref{Automatic}).
+
+@node Values, Setting, Reference, Variables
+@section How Variables Get Their Values
+
+Variables can get values in several different ways:
+
+@itemize @bullet
+@item
+You can specify an overriding value when you run @code{make}.
+@xref{Overriding}.
+
+@item
+You can specify a value in the makefile, either with an assignment
+(@pxref{Setting}) or with a verbatim definition (@pxref{Defining}).
+
+@item
+Values are inherited from the environment.  @xref{Environment}.
+
+@item
+Several @dfn{automatic} variables are given new values for each rule.
+@xref{Automatic}.
+
+@item
+Several variables have constant initial values.  @xref{Implicit
+Variables}.
+@end itemize
+
+@node Setting, Override Directive, Values, Variables
+@section Setting Variables
+@cindex setting variables
+
+To set a variable from the makefile, write a line starting with the
+variable name followed by @samp{=}.  Whatever follows the @samp{=} on the
+line becomes the value.  For example,
+
+@example
+objects = main.o foo.o bar.o utils.o
+@end example
+
+@noindent
+defines a variable named @code{objects}.  Spaces around the variable name
+are ignored, and so are spaces after the @samp{=} or at the end of the
+line.
+
+The line that sets the variable can contain variable references.  Such
+references are replaced by their values before the new variable is set.
+The value given to the new variable does not contain variable references;
+it contains the substuted values.  Thus,
+
+@example
+x = foo
+y = $(x) bar
+@end example
+
+@noindent
+is equivalent to
+
+@example
+x = foo
+y = foo bar
+@end example
+
+This gives you a way to introduce 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 include leading
+or trailing spaces in a variable value by protecting them with variable
+references, like this:
+
+@example
+nullstring=
+space=$(nullstring) $(nullstring)
+@end example
+
+@noindent
+Here the value of the variable @code{space} is precisely one space.
+
+There is no limit on the length of the value of a variable except the
+amount of swapping space on the computer.  When a variable definition is
+long, it is a good idea to break it into several lines by inserting
+backslash-newline at convenient places in the definition.  This will not
+affect the functioning of @code{make}, but it will make the makefile easier
+to read.
+
+Most variable names are considered to have the empty string as a value if
+you have never set them.  Several variables have built-in initial values
+that are not empty, but can be set by you in the usual ways
+(@pxref{Implicit Variables}).  Several special variables are set
+automatically to a new value for each rule; these are called the
+@dfn{automatic} variables (@pxref{Automatic}).
+
+@node Override Directive, Defining, Setting, Variables
+@section The @code{override} Directive
+@findex override
+
+If a variable has been set with a command argument (@pxref{Overriding}),
+then ordinary assignments in the makefile are ignored.  If you want to set
+the variable in the makefile even though it was set with a command
+argument, you can use an @code{override} directive, which is a line that
+looks like this:
+
+@example
+override @var{variable} = @var{value}
+@end example
+
+The @code{override} directive was not invented for escalation in the war
+between makefiles and command arguments.  It was invented so you can alter
+and add to values that the user specifies with command arguments.
+
+For example, suppose you always want the @samp{-g} switch when you run the
+C compiler, but you would like to allow the user to specify the other
+switches with a command argument just as usual.  You could use this
+@code{override} directive:
+
+@example
+override CFLAGS = $(CFLAGS) -g
+@end example
+
+@node Defining, Environment, Override Directive, Variables
+@section Defining Variables Verbatim
+@findex define
+@findex endef
+
+Another way to set the value of a variable is to use the @code{define}
+directive.  This directive has a different syntax and provides different
+features, and its intended use is for defining canned sequences of commands
+(@pxref{Sequences}).  But the variables made with @code{define} are just
+like those made the usual way.  Only the variable's value matters.
+
+The @code{define} directive is followed on the same line the name of the
+variable and nothing more.  The value to give the variable appears on the
+following lines.  These lines are used verbatim; the character @samp{$} is
+not treated specially and whitespace is not changed.  The end of the value
+is marked by a line containing just the word @code{endef}.
+
+@example
+define two-lines
+echo foo
+echo $100
+endef
+@end example
+
+Aside from syntax, there are two differences between @code{define} and
+ordinary variable assignments:
+
+@itemize @bullet
+@item
+The value assigned in an ordinary variable assignment is scanned for
+variable references and function calls, which are expanded.  The
+@code{define} commands are used verbatim, with no replacement.
+
+@item
+The value in an ordinary assignment cannot contain a newline.  The text in
+a @code{define} can be multiple lines; the newlines that separate the lines
+become part of the variable's value.  (The final newline which is always
+present does not become part of the variable value.)
+@end itemize
+
+@node Environment,, Defining, Variables
+@section Variables from the Environment
+
+@cindex environment
+Variables in @code{make} can come from the environment with which
+@code{make} is run.  Every environment variable that @code{make} sees when
+it starts up is transformed into a @code{make} variable with the same name
+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}.)
+
+By setting the variable @code{CFLAGS} in your environment, you can cause
+all C compilations in most makefiles to use the compiler switches you
+prefer.  This is safe for variables with standard or conventional meanings
+because you know that no makefile will use them for other things.  (But
+this is not totally reliable; some makefiles set @code{CFLAGS} explicitly
+and therefore are not affected by the value in the environment.)
+
+When @code{make} is invoked recursively, variables defined in the outer
+invocation are automatically passed to inner invocations through the
+environment (@pxref{Recursion}).  This is the main purpose of turning
+environment variables into @code{make} variables, and it requires no
+attention from you.
+
+Other use of variables from the environment is not recommended.  It is not
+wise for makefiles to depend for their functioning on environment variables
+set up outside their control, since this would cause different users to get
+different results from the same makefile.  This is against the whole
+purpose of most makefiles.
+
+Such problems would be especially likely with the variable @code{SHELL},
+which is normally present in the environment to specify the user's choice
+of interactive shell.  It would be very undesirable for this choice to
+affect @code{make}.  So @code{make} ignores the environment value of
+@code{SHELL} (and @code{SHFLAGS}) if the value of @code{MAKELEVEL} is zero
+(which is normally true except in recursive invocations of
+@code{make}).@refill
+
+@node Conditionals, Functions, Variables, Top
+@chapter Conditional Parts of Makefiles
+
+@cindex conditionals
+A @dfn{conditional} causes part of a makefile to be obeyed or ignored
+depending on the values of variables.  Conditionals can compare the value
+of one variable with another, or the value of a variable with a constant
+string.
+
+@menu
+* Example: Conditional Example.   An annotated example.
+* Syntax: Conditional Syntax.     Precise rules for syntax of conditionals.
+* Flags: Testing Flags.           Conditionals testing flags such as @samp{-t}.
+@end menu
+
+@node Conditional Example, Conditional Syntax, Conditionals, Conditionals
+@section Example of a Conditional
+
+This 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} not only changes which compiler is used but also which
+libraries are linked.
+
+@example
+libs_for_gcc = -lgnu
+normal_libs =
+
+foo: $(objects)
+ifeq ($(CC),gcc)
+        $(CC) -o foo $(objects) $(libs_for_gcc)
+else
+        $(CC) -o foo $(objects) $(normal_libs)
+endif
+@end example
+
+@noindent
+This conditional uses three directives: one @code{ifeq}, one @code{else}
+and one @code{endif}.
+
+The @code{ifeq} directive contains two arguments, separated by a comma and
+surrounded by parentheses.  Variable substitution is performed on both
+arguments and then they are compared.  The lines of the makefile following
+the @code{ifeq} are obeyed if the two arguments match; otherwise they are
+ignored.
+
+The @code{else} directive causes the following lines to be obeyed if the
+previous conditional failed.  In the example above, this means that the
+second alternative linking command is used whenever the first alternative
+is not used.  It is optional to have an @code{else} in a conditional.
+
+The @code{endif} directive ends the conditional.  Every conditional must
+end with an @code{endif}.  Unconditional makefile text follows.
+
+When the variable @code{CC} has the value @samp{gcc}, the above example has
+this effect:
+
+@example
+foo: $(objects)
+        $(CC) -o foo $(objects) $(libs_for_gcc)
+@end example
+
+@noindent
+When the variable @code{CC} has any other value, this effect is this:
+
+@example
+foo: $(objects)
+        $(CC) -o foo $(objects) $(normal_libs)
+@end example
+
+Equivalent results can be obtained in another way by conditionalizing a
+variable assignment and then using the variable unconditionally:
+
+@example
+libs_for_gcc = -lgnu
+normal_libs =
+
+ifeq ($(CC),gcc)
+  libs=$(libs_for_gcc)
+else
+  libs=$(normal_libs)
+endif
+
+foo: $(objects)
+        $(CC) -o foo $(objects) $(libs)
+@end example
+
+@node Conditional Syntax, Testing Flags, Conditional Example, Conditionals
+@section Syntax of Conditionals
+@findex ifdef
+@findex ifeq
+@findex else
+@findex endif
+
+The syntax of a simple conditional with no @code{else} is as follows:
+
+@example
+@var{conditional-directive}
+@var{text-if-true}
+endif
+@end example
+
+@noindent
+The @var{text-if-true} may be any lines of text, to be considered as part
+of the makefile if the condition is true.  If the condition is false, no
+text is used instead.
+
+The syntax of a complex conditional is as follows:
+
+@example
+@var{conditional-directive}
+@var{text-if-true}
+else
+@var{text-if-false}
+endif
+@end example
+
+@noindent
+If the condition is true, @var{text-if-true} is used; otherwise,
+@var{text-if-false} is used instead.  The @var{text-if-false} can be any
+number of lines of text.
+
+Conditionals work at the textual level.  The lines of the
+@var{text-if-true} are read as part of the makefile if the condition is
+true; if the condition is false, those lines are ignored completely.  It
+follows that syntactic units of the makefile, such as rules, may safely be
+split across the beginning or the end of the conditional.@refill
+
+You may use an @code{include} directive within a conditional, but you may
+not start a conditional in one file and end it in another.
+
+The syntax of the @var{conditional-directive} is the same whether the
+conditional is simple or complex.  There are four different directives that
+test different conditions.  Here is a table of them:
+
+@table @code
+@item ifeq (@var{arg1}, @var{arg2})
+Expand all variable references in @var{arg1} and @var{arg2} and
+compare them.  If they are identical, the @var{text-if-true} is
+effective; otherwise, the @var{text-if-false}, if any, is effective.
+
+@item ifneq (@var{arg1}, @var{arg2})
+Expand all variable references in @var{arg1} and @var{arg2} and
+compare them.  If they are different, the @var{text-if-true} is
+effective; otherwise, the @var{text-if-false}, if any, is effective.
+
+@item ifdef @var{variable-name}
+If the variable @var{variable-name} has a non-empty value, the
+@var{text-if-true} is effective; otherwise, the @var{text-if-false},
+if any, is effective.  Variables that have never been defined have an
+empty value.
+
+@item ifndef @var{variable-name}
+If the variable @var{variable-name} has an empty value, the
+@var{text-if-true} is effective; otherwise, the @var{text-if-false},
+if any, is effective.
+@end table
+
+Extra spaces are allowed and ignored at the beginning of the conditional
+directive line, but a tab is not allowed.  (If the line begins with a tab,
+it will be considered a command for a rule.)  Aside from this, extra spaces
+or tabs may be inserted with no effect anywhere except within the directive
+name or within an argument.  A comment starting with @samp{#} may appear at
+the end of the line.
+
+The other two directives that play a part in a conditional are @code{else}
+and @code{endif}.  Each of these directives is written as one word, with no
+arguments.  Extra spaces are allowed and ignored at the beginning of the
+line, and spaces or tabs at the end.  A comment starting with @samp{#} may
+appear at the end of the line.
+
+@node Testing Flags,, Conditional Syntax, Conditionals
+@section Conditionals that Test Flags
+
+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.
+
+The @code{findstring} function determines whether one string appears as a
+substring of another.  If you want to test for the @samp{-t} flag,
+use @samp{t} as the first string and the value of @code{MAKEFLAGS} as
+the other.
+
+For example, here is how to arrange to use @samp{ranlib -t} to finish
+marking an archive file up to date:
+
+@example
+archive.a: @dots{}
+ifneq (,$(findstring t,$(MAKEFLAGS)))
+        @@echo $(MAKE) > /dev/null
+        touch archive.a
+	ranlib -t archive.a
+else
+        ranlib archive.a
+endif
+@end example
+
+@noindent
+The @code{echo} command does nothing when executed; but its presence, with
+a reference to the variable @code{MAKE}, marks the rule as ``recursive'' so
+that its commands will be executed despite use of the @samp{-t} flag.
+
+@node Functions, Running, Conditionals, Top
+@chapter Functions for Transforming Text
+@cindex function
+
+@dfn{Functions} allow you to do text processing in the makefile to
+compute the files to operate on or the commands to use.
+
+@menu
+* Syntax: Function Syntax.  Syntax of function calls in general.
+* Text Functions::          Text manipulation functions.
+* Expand Function::         The function @code{expand} can search a variable's
+                             value for variable references.
+* Filename Functions::      Functions for manipulating file names.
+@end menu
+
+@node Function Syntax, Text Functions, Functions, Functions
+@section Function Call Syntax
+@cindex $
+
+A function call resembles a variable reference.  It looks like this:
+
+@example
+$(@var{function} @var{arguments})
+@end example
+
+@noindent
+or like this:
+
+@example
+$@{@var{function} @var{arguments}@}
+@end example
+
+Here @var{function} is a function name; one of a short list of names that
+are part of @code{make}.  There is no provision for defining new functions.
+
+The @var{arguments} are the arguments of the function.  They are separated
+from the function name by one or more spaces and/or tabs, and if there are
+more than one argument they are separated by commas.  Such whitespace and
+commas are not part of any argument's value.  Parentheses or braces,
+whichever you use to surround the function call, can appear in an argument
+only in matching pairs; the ones that were not used to surround the
+function call can appear freely.  If the arguments contain other function
+calls or variable references, it is wisest to surround them with the same
+delimiters used for the containing function call.
+
+The text written for each argument is processed by substitution of
+variables and function calls in order to produce the argument value, which
+is the text on which the function acts.
+
+Commas and unmatched parentheses or braces cannot appear in the text of an
+argument as written; leading spaces cannot appear in the text of the first
+argument as written.  These characters can be put into the argument value
+by variable substitution.  First define variables @code{comma} and
+@code{space} whose values are isolated comma and space characters, then
+substitute those variables where such characters are wanted, like this:
+
+@example
+comma= ,
+space= $(empty) $(empty)
+foo= a b c
+bar= $(subst $(space),$(comma),$(foo))
+@r{# bar is now `a,b,c'.}
+@end example
+
+@noindent
+Here the @code{subst} function replaces each space with a comma, through
+the value of @code{foo}, and substitutes the result.
+
+@node Text Functions, Expand Function, Function Syntax, Functions
+@section Functions for String Substitution and Analysis
+
+Here are two functions that operate on substrings of a string:
+@code{subst} and @code{findstring}.
+
+@table @code
+@item $(subst @var{from},@var{to},@var{text})
+@findex subst
+Performs a textual replacement on the text @var{text}: each occurrence
+of @var{from} is replaced by @var{to}.  The result is substituted for
+the function call.  For example,
+
+@example
+$(subst ee,EE,feet on the street)
+@end example
+
+substitutes the string @samp{fEEt on the strEEt}.
+
+@item $(findstring @var{find},@var{in})
+@findex findstring
+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
+substring in a given string.  @xref{Testing Flags}, for a practical
+application of @code{findstring}.
+@end table
+
+Here is a realistic example of use of @code{subst}.  Suppose that a
+makefile uses the @code{VPATH} variable to specify a list of directories
+that @code{make} should search for dependency files.  This example shows
+how to tell the C compiler to search for header files in the same list of
+directories.
+
+The value of @code{VPATH} is a list of directories separated by colons,
+such as @samp{src:../headers}.  First, the @code{subst} function is used to
+change the colons to spaces:
+
+@example
+$(subst :, ,$(VPATH))
+@end example
+
+@noindent
+This produces @samp{src ../headers}.  Then another function,
+@code{addprefix}, can turn each directory name into an @samp{-I} flag.
+These can be added to the value of the variable @code{CFLAGS}, which is
+passed automatically to the C compiler, like this:
+
+@example
+CFLAGS= $(CFLAGS) $(addprefix -I,$(subst :, ,$(VPATH)))
+@end example
+
+@noindent
+The effect is to append the text @samp{-Isrc -I../headers} to the
+previously given value of @code{CFLAGS}.
+
+@node Expand Function, Filename Functions, Text Functions, Functions
+@section Rescanning Text for Variable References
+
+@table @code
+@item $(expand @var{text})
+@findex expand
+Expands the text @var{text} twice.  This is to say, after variable
+references and function calls written in @var{text} are expanded,
+producing the argument text, that text is scanned over again for
+variable references and function calls.
+@end table
+
+For an example, suppose the following variable values have been set up:
+
+@example
+foo=cross$$(intermediate)
+intermediate=bar
+@end example
+
+@noindent
+where the double @samp{$} is used in setting @code{foo} in order to prevent
+variable substitution from occurring when @code{foo} is set, thus getting
+an actual dollar sign into the value of @code{foo}.
+
+Now if we expand @code{foo} in the usual way, with @samp{$(foo)}, the
+result is @samp{cross$(intermediate)}.
+
+The effect of @samp{$(expand $(foo))} is to rescan that string
+@samp{cross$(intermediate)}, which appears as the expanded argument string.
+In the process, variable substitution operates on the variable
+@code{intermediate}.  The ultimate result is @samp{crossbar}.
+
+The @code{expand} function is most often useful with canned sequences of
+commands (@xref{Sequences}).
+
+@node Filename Functions,, Expand Function, Functions
+@section Functions for File Names
+
+Several of the built-in expansion functions relate specifically to
+taking apart file names or lists of file names.
+
+Each of these functions performs a specific transformation on a file name.
+The argument of the function is regarded as a series of file names,
+separated by whitespace.  (Leading and trailing whitespace is ignored.)
+Each file name in the series is transformed in the same way and the results
+are concatenated with single spaces between them.
+
+@table @code
+@item $(dir @var{names})
+@findex dir
+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,
+the directory part is the string @samp{./}.  For example,
+
+@example
+$(dir src/foo.c hacks)
+@end example
+
+@noindent
+produces the result @samp{src/ ./}.
+
+@item $(notdir @var{names})
+@findex notdir
+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.  A file name
+that ends with a slash becomes an empty string.  This is unfortunate,
+because it means that the result does not always have the same number
+of whitespace-separated file names as the argument had; but we do not
+see any other valid alternative.
+
+For example,
+
+@example
+$(notdir src/foo.c hacks)
+@end example
+
+@noindent
+produces the result @samp{foo.c hacks}.
+
+@item $(suffix @var{names})
+@findex 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
+means that the result will be empty when @var{names} is not, and if
+@var{names} contains multiple file names, the result may contain fewer
+file names.
+
+For example,
+
+@example
+$(notdir src/foo.c hacks)
+@end example
+
+@noindent
+produces the result @samp{.c}.
+
+@item $(basename @var{names})
+@findex basename
+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
+entire file name.  For example,
+
+@example
+$(basename src/foo.c hacks)
+@end example
+
+@noindent
+produces the result @samp{src/foo hacks}.
+
+@item $(addsuffix @var{suffix},@var{names})
+@findex addsuffix
+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
+resulting larger names are concatenated with single spaces between
+them.  For example,
+
+@example
+$(addsuffix .c,foo bar)
+@end example
+
+@noindent
+produces the result @samp{foo.c bar.c}.
+
+@item $(addprefix @var{prefix},@var{names})
+@findex addprefix
+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 appended to the front of each individual name and the
+resulting larger names are concatenated with single spaces between
+them.  For example,
+
+@example
+$(addprefix src/,foo bar)
+@end example
+
+@noindent
+produces the result @samp{src/foo src/bar}.
+
+@item $(firstword @var{names})
+@findex firstword
+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.  For example,
+
+@example
+$(firstword foo bar)
+@end example
+
+@noindent
+produces the result @samp{foo}.
+
+@item $(wildcard @var{pattern})
+@findex wildcard
+The argument @var{pattern} is a file name pattern, typically
+containing wildcards characters.  The result of @code{wildcard} is a
+space-separated list of the names of existing files that match the
+pattern.
+
+Wildcard are expanded automatically in rules (@pxref{Wildcards}).  But
+it does not normally take place when a variable is set, or inside the
+arguments of other functions.  Those occasions are when the
+@code{wildcard} function is useful.
+@end table
+
+@node Running, Implicit, Functions, Top
+@chapter How to Run @code{make}
+
+A makefile that says how to recompile a program can be used in more than
+one way.  The simplest use is to recompile every file that is out of date.
+This is what @code{make} will do if run with no arguments.
+
+But you might want to update only some of the files; you might want to use
+a different compiler or different compiler options; you might want just to
+find out which files are out of date without changing them.
+
+By specifying arguments when you run @code{make}, you can do any of these
+things or many others.
+
+@menu
+* Makefile Arguments::    Arguments to specify which makefile to use.
+
+* Goals::                 Goal arguments specify which parts of the makefile
+                           should be used.
+
+* Avoid Compilation::     How to avoid recompiling certain files.
+
+* Instead of Execution::  Mode flags specify what kind of thing to do
+                           with the commands in the makefile
+                           other than simply execute them.
+
+* Overriding::            Overriding a variable can specify an alternate
+                           compiler, or alternate flags for the compiler,
+                           or whatever else you program into the makefile.
+
+* Testing::               How to proceed past some errors, to test compilation.
+
+* Options::               Summary of all options @code{make} accepts.
+@end menu
+
+@node Makefile Arguments, Goals, Running, Running
+@section Arguments to Specify the Makefile
+
+The way to specify the name of the makefile is with the @samp{-f} option.
+For example, @samp{-f altmake} says to use the file @file{altmake} as
+the makefile.
+
+If you use the @samp{-f} flag several times (each time with a
+following argument), all the specified files are used jointly as
+makefiles.
+
+If you do not use the @samp{-f} flag, the default is to use
+@file{./makefile}, or, if that does not exist, @file{./Makefile}.
+@xref{Makefiles}.@refill
+
+@node Goals, Avoid Compilation, Makefile Arguments, Running
+@section Goals
+@cindex goal
+
+The @dfn{goals} are the targets that @code{make} should strive ultimately
+to update.  Other targets are updated as well if they appear as
+dependencies of goals, or dependencies of dependencies of goals, etc.
+
+By default, the goal is the first target in the makefile (not counting
+targets that start with a period or that appear in included makefiles).
+Therefore, makefiles are usually written so that the first target is for
+compiling the entire program or programs they describe.
+
+You can specify a different goal or goal with arguments to @code{make}.
+Use the name of the goal as an argument.  If you specify several goals,
+@code{make} processes each of them in turn, in the order you name them.
+
+Any target in the makefile may be specified as a goal (unless it starts
+with @samp{-} or contains an @samp{=}).  Even targets not in the makefile
+may be specified, if @code{make} can find implicit rules that say how to
+make them.
+
+One use of specifying a goal is if you want to compile only a part of
+the program, or only one of several programs.  Specify as a goal each
+file that you wish to remake.  For example, consider a directory containing
+a several programs, with a makefile that starts like this:
+
+@example
+all: size nm ld ar as
+@end example
+
+If you are working on the program @code{size}, you might want to say
+@samp{make size} so that only the files of that program are recompiled.
+
+Another use of specifying a goal is to make files that aren't normally
+made.  For example, there may be a file of debugging output, or a version
+of the program that is compiled specially for testing, which has a rule
+in the makefile but isn't a dependency of the default goal.
+
+Another use of specifying a goal is to run the commands associated with a
+phony target (@pxref{Phony Targets}) or empty target (@pxref{Empty Targets}).
+Many makefiles contain a phony target named @file{clean} which deletes
+everything except source files.  Naturally, this is done only if you
+request it explicitly with @samp{make clean}.  Here is a list of typical
+phony and empty target names:
+
+@table @file
+@item clean
+Delete all files that the makefile could remake.
+
+@item install
+Copy the executable file into a directory that users typically search for
+commands.
+
+@item print
+Print listings of the source files that have changed.
+
+@item tar
+Create a tar file of the source files.
+@end table
+
+@node Avoid Compilation, Instead of Execution, Goals, Running
+@section Avoiding Recompilation of Some Files
+
+Sometimes you may have changed a source file but you don't want to
+recompile all the files that depend on it.  For example, suppose you add a
+macro or a declaration to a header file that many other files depend on.
+Being conservative, @code{make} assumes that any change in the header file
+requires recompilation of all dependent files, but you know that they don't
+need to be recompiled and you would rather not waste the time waiting.
+
+If you anticipate the problem before making the change, you can use the
+@samp{-t} flag.  This flag tells @code{make} not to run the commands in the
+rules, but rather to mark the target up-to-date by changing its
+last-modification date.  You would follow this procedure:
+
+@enumerate
+@item
+Use the command @samp{make} to recompile the source files that really
+need recompilation.
+
+@item
+Make the changes in the header files.
+
+@item
+Use the command @samp{make -t} to mark all the object files as
+up-to-date.  The next time you run @code{make}, the changes in the
+header files will not cause any recompilation.
+@end enumerate
+
+If you have already changed the header file at a time when some files do
+need recompilation, it is too late to do this.  Instead, you can use the
+@samp{-o @var{file}} flag, which marks a specified file as ``old''
+(@pxref{Options}).  This means that the file itself won't be remade,
+and nothing else will be remade on its account.  Follow this procedure:
+
+@enumerate
+@item
+Recompile the source files that need compilation for reasons independent
+of the particular header file, with @samp{make -o @var{headerfile}}.
+If several header files are involved, use a separate @samp{-o} option
+for each header file.
+
+@item
+Touch all the object files with @samp{make -t}.
+@end enumerate
+
+@node Instead of Execution, Overriding, Avoid Compilation, Running
+@section Instead of Executing the Commands
+@cindex -t
+@cindex touch
+@cindex -q
+@cindex -n
+
+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
+what you want.  Certain options specify other activities for @code{make}.
+
+@table @samp
+@item -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
+the targets but does not really change their contents.
+
+@item -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
+``Question''.  The activity is to find out silently whether the targets
+are up to date already; but execute no commands in either case.  In other
+words, neither compilation nor output will occur.
+@end table
+
+With the @samp{-n} flag, @code{make} prints without execution the commands
+that it would normally execute.
+
+With the @samp{-t} flag, @code{make} ignores the commands in the rules
+and uses (in effect) the command @code{touch} for each target that needs to
+be remade.  The @code{touch} command is also printed, unless @samp{-s} or
+@code{.SILENT} is used.  For speed, @code{make} does not actually invoke
+the program @code{touch}.  It does the work directly.
+
+With the @samp{-q} flag, @code{make} prints nothing and executes no
+commands, but the exit status code it returns is zero if and only if the
+targets to be considered are already up to date.
+
+It is an error to use more than one of these three flags in the same
+invocation of @code{make}.
+
+@node Overriding, Testing, Instead of Execution, Running
+@section Overriding Variables
+
+You can override the value of a variable using an arguments to @code{make}
+that contains a @samp{=}.  The argument @samp{@var{v}=@var{x}} sets the
+value of the variable @var{v} to @var{x}.
+
+Values specified this way override all values specified in the makefile
+itself; once you have set a variable with a command argument, any ordinary
+attempt in the makefile to change that variable is simply ignored.
+
+One way to use this facility is to pass extra flags to compilers.
+For example, in a properly written makefile, the variable @code{CFLAGS}
+is included in each command that runs the C compiler, so a file
+@file{foo.c} would be compiled like this:
+
+@example
+cc -c $(CFLAGS) foo.c
+@end example
+
+Thus, whatever value you set for @code{CFLAGS} affects each compilation
+that occurs.  The makefile probably specifies the usual value for
+@code{CFLAGS}, like this:
+
+@example
+CFLAGS=-g
+@end example
+
+Each time you run @code{make}, you can override this value and specify a
+different value.  For example, if you say @samp{make CFLAGS='-g -O'}, each
+C compilation will be done with @samp{cc -c -g -O}.  (This illustrates how
+you can enclose spaces and other special characters in the value of a
+variable when you override it.)
+
+The variable @code{CFLAGS} is only one of many standard variables that
+exist just so that you can change them this way.  @xref{Implicit
+Variables}, for a complete list.
+
+You can also program the makefile to look at additional variables of your
+own, giving the user ability to control other aspects of how the makefile
+works by changing the variables.
+
+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:
+
+@example
+override @var{variable} = @var{value}
+@end example
+
+@noindent
+This line acts like an ordinary variable assignment except that it is
+not ignored even if you have used a commadn option to set the variable.
+@xref{Override Directive}.
+
+@node Testing, Options, Overriding, Running
+@section Testing the Compilation of a Program
+
+Normally, when an error happens in executing a shell command, @code{make}
+gives up immediately, returning a nonzero status.  No further commands are
+executed for any target.  The error implies that the goal cannot be
+correctly remade, so @code{make} reports this as soon as it knows.
+
+When you are compiling a program that you have just changed, this is not
+what you want.  Instead, you would rather that @code{make} try compiling
+every file that can be tried, to show you all the compilation errors.
+
+@cindex -k
+Then you should use the @samp{-k} flag.  If the @samp{-k} flag is
+specified, @code{make} continues to consider the other dependencies of the
+pending targets, remaking them if necessary, before it gives up and returns
+nonzero status.  For example, after an error in compiling one object file,
+@samp{make -k} will continue compiling other object files even though it
+already knows that linking them will be impossible.  @xref{Options}.
+
+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
+as well report the failure immediately.  The @samp{-k} flag says that the
+real purpose is to test as much as possible of the changes made in the
+program, perhaps to find several independent problems so that you can
+correct them all before the next attempt to compile.  This is why Emacs's
+@code{compile} command passes the @samp{-k} flag by default.
+
+@node Options,, Testing, Running
+@section Summary of Options
+@cindex options
+@cindex flags
+
+Here is a table of all the options @code{make} understands:
+
+@table @samp
+@item -b
+This option is ignored for compatibility with other versions of
+@code{make}.
+
+@item -c @var{dir}
+Change to directory @var{dir} before executing the rules.  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}.
+This is typically used with recursive invocations of @code{make}
+(@pxref{Recursion}).
+
+@item -d
+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,
+which files actually need to be remade, which implicit rules are
+considered and which are applied---everything interesting about how
+@code{make} decides what to do.
+
+@item -f @var{file}
+Use file @var{file} as a makefile.  @xref{Makefiles}.
+
+@item -i
+Ignore all errors in commands executed to remake files.
+@xref{Errors}.
+
+@item -I @var{dir}
+Specifies a directory @var{dir} to search for included makefiles.
+@xref{Include}.  If several @samp{-I} options are used to specify
+several directories, the directories are searched in the order
+specified.
+
+@item -k
+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}.
+
+@item -n
+Print the commands that would be executed, but do not execute them.
+@xref{Instead of Execution}.
+
+@item -o @var{file}
+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
+are ignored.  @xref{Avoid Compilation}.
+
+@item -p
+Print the data base (rules and variable values) that results from
+reading the makefiles; then execute as usual or as otherwise
+specified.
+
+@item -q
+``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}.
+
+@item -r
+Eliminate use of the built-in implicit rules (@pxref{Implicit}).
+Also clear out the default list of suffixes for suffix rules
+(@pxref{Suffix Rules}).
+
+@item -s
+Silent operation; do not print the commands as they are executed.
+@xref{Echoing}.
+
+@item -S
+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}.  @xref{Recursion}.
+
+@item -t
+Touch files (mark them up to date without really changing them)
+instead of running their commands.  This is used to pretend (to fool
+future invocations of @code{make}) that the commands were done.
+@xref{Instead of Execution}.
+@end table
+
+@node Implicit, Archives, Running, Top
+@chapter Using Implicit Rules
+@cindex implicit rule
+
+Certain standard ways of remaking target files are used very often.  For
+example, one customary way to make an object file is from a C source file
+using the C compiler, @code{cc}.
+
+@dfn{Implicit rules} tell @code{make} how to use customary techniques so
+that you don't have to specify them in detail when you want to use them.
+For example, there is an implicit rule for C compilation.
+
+Implicit rules work based on file names.  For example, C compilation typically
+takes a @file{.c} file and makes a @file{.o} file.  So @code{make} applies
+the implicit rule when it sees this combination of file-name endings.
+
+A chain of implicit rules can apply in sequence; for example, @code{make}
+will remake a @file{.o} file from a @file{.y} file by way of a @file{.c} file.
+@iftex
+@xref{Chained Rules}.
+@end iftex
+
+The built-in implicit rules use several variables in their commands so
+that, by changing the values of the variables, you can change the way the
+implicit rule works.  For example, the variable @code{CFLAGS} controls the
+flags given to the C compiler by the implicit rule for C compilation.
+@iftex
+@xref{Implicit Variables}.
+@end iftex
+
+You can define your own implicit rules by writing @dfn{pattern rules}.
+@iftex
+@xref{Pattern Rules}.
+@end iftex
+
+@menu
+* Using Implicit::       How to use an existing implicit rule
+                          to get the commands for updating a file.
+
+* Catalogue of Rules::   Catalogue of built-in implicit rules.
+
+* Implicit Variables::   By changing certain variables, you can
+                          change what the predefined implicit rules do.
+
+* Chained Rules::        Using a chain of implicit rules.
+
+* Pattern Rules::        Defining new implicit rules.
+
+* Search Algorithm::     Precise algorithm for applying implicit rules.
+@end menu
+
+@node Using Implicit, Catalogue of Rules, Implicit, Implicit
+@section Using Implicit Rules
+
+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
+write a rule with no command lines, or don't write a rule at all.  Then
+@code{make} will figure out which implicit rule to use based on which
+kind of source file exists.
+
+For example, suppose the makefile looks like this:
+
+@example
+foo : foo.o bar.o
+        cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS)
+@end example
+
+@noindent
+Because you mention @file{foo.o} but do not give a rule for it, @code{make}
+will automatically look for an implicit rule that tells how to update it.
+This happens whether or not the file @file{foo.o} currently exists.
+
+If an implicit rule is found, it supplies both commands and a dependency
+(the source file).  You would want to write a rule for @file{foo.o} with no
+command lines if you need to specify additional dependencies, such as
+header files, that the implicit rule cannot supply.
+
+Each implicit rule has a target pattern and dependency patterns.  There may
+be many implicit rules with the same target pattern.  For example, numerous
+rules make @samp{.o} files: one, from a @samp{.c} file with the C compiler;
+another, from a @samp{.p} file with the Pascal compiler; and so on.  The rule
+that actually applies is the one whose dependency exists or can be made.
+
+So, if you have a file @file{foo.c}, @code{make} will run the C compiler;
+otherwise, if you have a file @file{foo.p}, @code{make} will run the Pascal
+compiler; and so on.
+
+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 other files are supposed to exist.  @xref{Catalogue of Rules},
+for a catalogue of all the predefined implicit rules.
+
+Above, we said an implicit rule applies if the required dependency ``exists
+or can be made''.  A file ``can be made'' if it is mentioned explicitly in
+the makefile as a target or a dependency, or if an implicit rule can be
+recursively found for how to make it.  When the implicit dependency is the
+result of another implicit rule, we say that @dfn{chaining} is occurring.
+@xref{Chained Rules}.
+
+In general, @code{make} searches for an implicit rule for each target, and
+for each double-colon rule, that has no commands.  A file that is mentioned
+only as a dependency is considered a target whose rule specifies nothing,
+so implicit rule search happens for it.  @xref{Search Algorithm}, for the
+details of how the search is done.
+
+@node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit
+@section Catalogue of Implicit Rules
+
+Here is a catalogue of predefined implicit rules which are always available
+unless the makefile explicitly overrides or cancels them.
+(@xref{Cancelling Rules}, for information on cancelling or overriding an
+implicit rule.  The @samp{-r} option cancels all predefined rules.)
+
+@table @asis
+@item Compiling C programs
+@file{@var{n}.o} will be made automatically from @file{@var{n}.c} 
+with the command @samp{$(CC) -c $(CFLAGS)}.@refill
+
+@item Compiling Pascal programs
+@file{@var{n}.o} will be made automatically from @file{@var{n}.p}
+with the command @samp{$(PC) -c $(PFLAGS)}.@refill
+
+@item Compiling Fortran, EFL and Ratfor programs
+@file{@var{n}.o} will be made automatically from @file{@var{n}.e},
+@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
+
+@table @samp
+@item .e
+@samp{$(FC) -c $(EFLAGS)}.
+@item .f
+@samp{$(FC) -c $(FFLAGS)}.
+@item .F
+@samp{$(FC) -c $(FFLAGS)}.
+@item .r
+@samp{$(FC) -c $(RFLAGS)}.
+@end table
+
+@item Preprocessing Fortran, EFL and Ratfor programs
+@file{@var{n}.f} will be made automatically from @file{@var{n}.e},
+@file{@var{n}.r} or @file{@var{n}.F}.  This rule runs just the
+preprocessor to convert a Ratfor, EFL or preprocessable Fortran
+program into a strict Fortran program.  The precise command used is as
+follows:@refill
+
+@table @samp
+@item .e
+@samp{$(FC) -F $(EFLAGS)}.
+@item .F
+@samp{$(FC) -F $(FFLAGS)}.
+@item .r
+@samp{$(FC) -F $(RFLAGS)}.
+@end table
+
+@item Assembling assembler programs
+@file{@var{n}.o} will be made automatically from @file{@var{n}.s} by
+running the assembler @code{as}.  The precise command used is
+@samp{$(AS) $(ASFLAGS)}.@refill
+
+@item Linking a single object file
+@file{@var{n}} will be 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) @dots{} $(LOADLIBES)}.@refill
+
+This rule does the right thing for a simple program with only one source
+file.  In more complicated cases, you must write an explicit command for
+linking.
+
+@item Compiling C into assembler code
+@file{@var{n}.s} will be made automatically from @file{@var{n}.c}
+with the command @samp{$(CC) -S $(CFLAGS)}.@refill
+
+It would be possible for @code{make} to convert @file{@var{n}.c} into
+@file{@var{n}.o} by way of @file{@var{n}.s}, using this rule and the
+rule for running the assembler.  But that is not what @code{make}
+does, because the rule for compiling @file{@var{n}.c} into
+@file{@var{n}.o} directly comes earlier in the order of rules.  The
+upshot is that the file @file{@var{n}.s} is not created or changed
+when @file{@var{n}.o} is being remade.  This rule is used only if you
+explicitly specify @file{@var{n}.s} as a goal or needed dependency.
+
+This is a deliberate decision, for the sake of compatibility with Unix
+@code{make}.@refill
+
+If you want @code{make} update @file{@var{n}.s} on the way to updating
+@file{@var{n}.o}, you can request this by cancelling the other rule
+that allows direct compilation.  @xref{Cancelling Rules}.@refill
+
+@item Compiling Pascal, Fortran, EFL or Ratfor into assembler code
+@file{@var{n}.s} will be made automatically from @file{@var{n}.p},
+@file{@var{n}.e}, @file{@var{n}.r}, @file{@var{n}.F} or @file{@var{n}.F}
+by running the appropriate compiler with the @samp{-S} flag
+instead of the @samp{-c} flag.@refill
+
+For compatibility with Unix @code{make}, these rules apply only if you
+expressly request @code{make} to update @file{@var{n}.s}.  See the
+information immediately above.
+
+@item Yacc for C programs
+@file{@var{n}.c} will be made automatically from @file{@var{n}.y} by
+running Yacc with the command @samp{$(YACC) $(YFLAGS)}.
+
+@item Yacc for Ratfor programs
+@file{@var{n}.r} will be made automatically from @file{@var{n}.yr} by
+running Yacc with the command @samp{$(YACCR) $(YFLAGS)}.
+
+@item Yacc for EFL programs
+@file{@var{n}.e} will be made automatically from @file{@var{n}.ye} by
+running Yacc with the command @samp{$(YACCE) $(YFLAGS)}.
+
+@item Lex for C programs
+@file{@var{n}.c} will be 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
+by running Lex.  The actual command is @samp{$(LEX) $(LFLAGS)}.
+
+The traditional custom of using the same suffix @samp{.l} for all Lex
+files regardless of whether they produce C code or Ratfor code makes
+it impossible for @code{make} to determine autmatically which of the
+two languages you are using in any particular case.  If @code{make} is
+called upon to remake an object file from a @samp{.l} file, it must
+guess which compiler to use.  It will guess the C compiler, because
+that is more common.  If you are using Ratfor, make sure @code{make}
+knows this by mentioning @file{@var{n}.r} in the makefile.
+
+@item RCS
+Any file @file{@var{n}} will be 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)}.  The variable
+@code{CO} has default value @samp{co}.
+
+@item SCCS
+Any file @file{@var{n}} will be 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)}.
+
+I recommend that you avoid the use of SCCS.  RCS is widely held to be
+superior, and RCS is also free.  By choosing free software in place of
+comparable proprietary software, you support the free software
+movement.
+@end table
+
+@node Implicit Variables, Chained Rules, Catalogue of Rules, Implicit
+@section Variables Used by Implicit Rules
+@cindex flags for compilers
+
+The commands in built-in implicit rules make liberal use of certain
+predefined variables.  You can redefine these variables, either in the
+makefile or with arguments to @code{make}, to alter how the implicit rules
+work without actually redefining them.
+
+For example, the command used to compile a C source file actually says
+@samp{$(CC) -c $(CFLAGS)}.  The default values of the variables used
+are @samp{cc} and nothing, resulting in the command @samp{cc -c}.  By
+redefining @samp{$(CC)} to @samp{ncc}, you could cause @samp{ncc} to
+be used for all C compilations performed by the implicit rule.  By
+redefining @samp{$(CFLAGS)} to be @samp{-g}, you could pass the
+@samp{-g} option to each compilation.  @emph{All} implicit rules that
+do C compilation use @samp{$(CC)} to get the program name for the
+compiler and @emph{all} include @samp{$(CFLAGS)} among the arguments
+given to the compiler.@refill
+
+The variables used in implicit rules fall into two classes: those that are
+names of programs (like @code{CC}) and those that contain arguments for the
+programs (like @code{CFLAGS}).  (The ``name of a program'' may also contain
+some command arguments, but it must start with an actual executable program
+name.)  If a variable value contains more than one argument, separate them
+with spaces.
+
+Here is a table of variables used as names of programs:
+
+@table @code
+@item AS
+@vindex AS
+Program for doing assembly; default @samp{as}.
+
+@item CC
+@vindex CC
+Program for compiling C programs; default @samp{cc}.
+
+@item CO
+@vindex CO
+Program for extracting a file from RCS; default @samp{co}.
+
+@item FC
+@vindex FC
+Program for compiling or preprocessing Fortran programs (or Ratfor or
+EFL programs); default @samp{f77}.
+
+@item GET
+@vindex GET
+Program for extracting a file from SCCS; default @samp{get}.
+
+@item LEX
+@vindex LEX
+Program to use to turn Lex grammars into C programs or Ratfor programs;
+default @samp{lex}.
+
+@item PC
+@vindex PC
+Program for compiling Pascal programs; default @samp{pc}.
+
+@item YACC
+@vindex YACC
+Program to use to turn Yacc grammars into C programs; default
+@samp{yacc}.
+
+@item YACCR
+@vindex YACCR
+Program to use to turn Yacc grammars into Ratfor programs; default
+@samp{yacc -r}.
+
+@item YACCE
+@vindex YACCE
+Program to use to turn Yacc grammars into EFL programs; default
+@samp{yacc -e}.
+
+@item RANLIB
+@vindex RANLIB
+Program to use to update the symbol-directory of an archive
+(the @file{__.SYMDEF} member); default @samp{ranlib}.
+@end table
+
+Here is a table of variables whose values are additional arguments for the
+programs above:
+
+@table @code
+@item ASFLAGS
+@vindex ASFLAGS
+Extra flags to give to the assembler (when explicitly invoked
+on a @samp{.s} file).
+
+@item CFLAGS
+@vindex CFLAGS
+Extra flags to give to the C compiler; default is empty.
+
+@item EFLAGS
+@vindex EFLAGS
+Extra flags to give to the Fortran compiler for EFL programs; default
+is empty.
+
+@item FFLAGS
+@vindex FFLAGS
+Extra flags to give to the Fortran compiler; default is empty.
+
+@item LFLAGS
+@vindex LFLAGS
+Extra flags to give to Lex; default is empty.
+
+@item LDFLAGS
+@vindex LDFLAGS
+Extra flags to give to compilers when they are supposed to invoke the
+linker, @samp{ld}; default is empty.
+
+@item PFLAGS
+@vindex PFLAGS
+Extra flags to give to the Pascal compiler; default is empty.
+
+@item RFLAGS
+@vindex RFLAGS
+Extra flags to give to the Fortran compiler for Ratfor programs;
+default is empty.
+
+@item YFLAGS
+@vindex YFLAGS
+Extra flags to give to Yacc; default is empty.
+@end table
+
+@node Chained Rules, Pattern Rules, Implicit Variables, Implicit
+@section Chains of Implicit Rules
+
+@cindex chains of rules
+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}.
+
+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
+used.  Ultimately both @file{@var{n}.c} and @file{@var{n}.o} are
+updated.@refill
+
+@cindex intermediate file
+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
+called an @dfn{intermediate file}.  Once @code{make} has decided to use the
+intermediate file, it is entered in the data base as if it had been
+mentioned in the makefile, along with the implicit rule that says how to
+create it.@refill
+
+Intermediate files are remade using their rules just like all other
+files.  The difference is that the intermediate file is deleted when
+@code{make} is finished.  Therefore, the intermediate file which did
+not exist before @code{make} also does not exist after @code{make}.
+The deletion is reported to you by printing a @code{rm -f} command
+that shows what @code{make} is doing.  (You can optionally define an
+implicit rule so as to preserve certain intermediate files.)
+
+A chain can involve more than two implicit rules.  For example, it is
+possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS,
+Yacc and @code{cc}.  Then both @file{foo.y} and @file{foo.c} are
+intermediate files that are deleted at the end.@refill
+
+No single implicit rule can appear more than once in a chain.  This means
+that @code{make} will not even consider such a ridiculous thing as making
+@file{foo} from @file{foo.o.o} by running the linker twice.  This
+constraint has the added benefit of preventing any infinite loop in the
+search for an implicit rule chain.
+
+There are some special implicit rules to optimize certain cases that would
+otherwise by handled by rule chains.  For example, making @file{foo} from
+@file{foo.c} could be handled by compiling and linking with separate rules,
+using @file{foo.o} as an intermediate file.  But what actually happens is
+that a special rule for this case does the compilation and linking with a
+single @code{cc} command.  The optimized rule is used in preference to the
+step-by-step chain because it comes earlier in the ordering of rules.
+
+@node Pattern Rules, Last Resort, Chained Rules, Implicit
+@section Defining and Redefining Pattern Rules
+
+@cindex pattern rule
+You define an implicit rule by writing a @dfn{pattern rule}.  A pattern
+rule looks like an ordinary rule, except that its target contains the
+character @samp{%} (exactly one of them).  The target is considered a
+pattern for matching file names; the @samp{%} can match any substring,
+while other characters match only themselves.
+
+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
+with @samp{s.}, ends in @samp{.c} and is at least five characters long.
+(There must be at least one character to match the @samp{%}.)  The substring
+that the @samp{%} matches is called the @dfn{stem}.@refill
+
+A pattern rule must have at least one dependency that uses @samp{%}.
+@samp{%} in a dependency of a pattern rule stands for the same stem
+that was matched by the @samp{%} in the target.  In order for
+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.
+
+There may also be dependencies that do not use @samp{%}; such a dependency
+attaches to every file made by this pattern rule.  These unvarying
+dependencies are rarely useful.
+
+The order in which pattern rules appear in the makefile is important
+because the rules are considered in that order.  Of equally applicable
+rules, the first one found is used.  The rules you write take precedence
+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.
+
+@menu
+* Examples: Pattern Examples.  Real examples of pattern rule definitions.
+
+* Vars: Automatic.             The automatic variables enable the commands
+                                in pattern rules to act on the right files.
+
+* Matching: Pattern Match.     Details of how patterns match.
+
+* Match-Anything Rules::       Precautions in defining a rules that can
+                                match any target file whatever.
+
+* Cancelling Rules::           Overriding or cancelling built-in rules.
+
+* Last Resort::                How to define a last-resort rule
+                                that applies to any target that no other
+                                rule applies to.
+
+* Suffix Rules::               The old-fashioned way to define implicit rules.
+@end menu
+
+@node Pattern Examples, Automatic, Pattern Rules, Pattern Rules
+@subsection Pattern Rule Examples
+
+Here are some examples of pattern rules actually predefined in
+@code{make}.  First, the rule that compiles @samp{.c} files into @samp{.o}
+files:@refill
+
+@example
+%.o : %.c
+        $(CC) -c $(CFLAGS) $< -o $@@
+@end example
+
+@noindent
+defines a rule that can make any file @file{@var{x}.o} from
+@file{@var{x}.c}.  The command uses the automatic variables @samp{$@@} and
+@samp{$<} to substitute the names of the target file and the source file
+as they are in each case where the rule apply (@pxref{Automatic}).@refill
+
+Here is a second built-in rule:
+
+@example
+% :: RCS/%,v
+        $(CO) $(COFLAGS) $<
+@end example
+
+@noindent
+defines a rule that can make any file @file{@var{x}} whatever from a
+corresponding file @file{@var{x},v} in the subdirectory @file{RCS}.  Since
+the target is @samp{%}, this rule will apply to any file whatever, provided
+the appropriate dependency file exists.  The double colon makes the rule
+@dfn{terminal}, which means that its dependency may not be an intermediate
+file (@pxref{Match-Anything Rules}).@refill
+
+@node Automatic, Pattern Match, Pattern Examples, Pattern Rules
+@subsection Automatic Variables
+@cindex automatic variables
+@cindex $
+
+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
+on the right source file name?  You can't write the name in the command,
+because the name is different each time the implicit rule is applied.
+
+What you do is use a special feature of @code{make}, the @dfn{automatic
+variables}.  These variables have values computed afresh for each rule that
+is executed, based on the target and dependencies of the rule.  In this
+example, you would use @samp{$@@} for the object file name and @samp{$<}
+for the source file name.
+
+Here is a table of automatic variables:
+
+@table @code
+@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.
+
+@item $%
+The target member name, when the target is an archive member.  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.
+
+@item $<
+The name of the first implicit dependency, when an implicit rule is
+being applied.
+
+@item $?
+The names of all the dependencies that are newer than the target, with
+spaces between them.
+
+@item $^
+The names of all the dependencies, with spaces between them.
+
+@item $*
+The stem with which an implicit rule matches (@pxref{Pattern 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
+
+@item $($@@)
+The same as @code{$@@}, for compatibility with some other versions
+of @code{make}.
+@end table
+
+@samp{$?} is useful even in explicit rules when you wish to operate on only
+the dependencies that have changed.  For example, suppose that an archive
+named @file{lib} is supposed to contain copies of several object files.
+This rule copies just the changed object files into the archive:
+
+@example
+lib: foo.o bar.o lose.o win.o
+        ar c lib $?
+@end example
+
+Of the variables listed above, four have values that are single file names.
+These four have variants that get just the file's directory name or just
+the file name within the directory.  The variant variables' names are
+formed by appending @samp{D} or @samp{F}, respectively.  These variants are
+semi-obsolete in GNU @code{make} since the functions @code{dir} and
+@code{notdir} can be used to get an equivalent effect (@pxref{Filename
+Functions}).  Here is a table of the variants:@refill
+
+@table @samp
+@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/}.
+This value is @file{./} if @samp{$@@} does not contain a slash.
+@samp{$(@@D)} is equivalent to @samp{$(dir $@@)}.@refill
+
+@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 $@@)}.
+
+@item $($/)
+The same as @code{$(@@F)}, for compatibility with some other versions
+of @code{make}.
+
+@item $(%D)
+@itemx $(%F)
+The directory part and the file-within-directory part of the archive
+member name.
+
+@item $(*D)
+@itemx $(*F)
+The directory part and the file-within-directory part of the stem;
+@file{dir/} in this example.
+
+@item $(<D)
+@itemx $(<F)
+The directory part and the file-within-directory part of the first
+implicit dependency.
+@end table
+
+@node Pattern Match, Match-Anything Rules, Automatic, Pattern Rules
+@subsection How Patterns Match
+
+@cindex stem
+A target pattern is composed of a @samp{%} between a prefix and a suffix,
+either of which may be empty.  The pattern matches a file name only if the
+file name starts with the prefix and ends with the suffix, without overlap.
+The text between the prefix and the suffix is called the @dfn{stem}.  Thus,
+when the pattern @samp{%.o} matches the file name @file{test.o}, the stem
+is @samp{test}.  The pattern rule dependencies are turned into actual file
+names by substituting the stem for the character @samp{%}.  Thus, if in the
+same example one of the dependencies is written as @samp{%.c}, it expands
+to @samp{test.c}.@refill
+
+When the target pattern does not contain a slash (and usually it does not),
+directory names in the file names are removed from the file name before it
+is compared with the target prefix and suffix.  The directory names, along
+with the slash that ends them, are added back to the stem.  Thus,
+@samp{e%t} does match the file name @file{src/eat}, with @samp{src/a} as
+the stem.  When dependencies are turned into file names, the directories
+from the stem are added at the front, while the rest of the stem is
+substituted for the @samp{%}.  The stem @samp{src/a} with a dependency
+pattern @samp{c%r} gives the file name @file{src/car}.@refill
+
+@node Match-Anything Rules, Cancelling Rules, Pattern Match, Pattern Rules
+@subsection Match-Anything Pattern Rules
+
+@cindex match-anything rule
+@cindex terminal rule
+When a pattern rule's target is just @samp{%}, it matches any filename
+whatever.  We call these rules @dfn{match-anything} rules.  They are very
+useful, but it can take a lot of time for @code{make} to think about them,
+because it must consider every such rule for each file name listed either
+as a target or as a dependency.
+
+Suppose the makefile mentions @file{foo.c}.  For this target, @code{make}
+would have to consider making it by linking an object file @file{foo.c.o},
+or by C compilation-and-linking in one step from @file{foo.c.c}, or by
+Pascal compilation-and-linking from @file{foo.c.p}, and many other
+possibilities.  We know these possibilities are ridiculous since
+@file{foo.c} is a C source file, not an executable.@refill
+
+If @code{make} did consider these possibilities, it would ultimately reject
+them, because files such as @file{foo.c.o}, @file{foo.c.p}, etc. would not
+exist.  But these possibilities are so numerous that @code{make} would run
+very slowly if it had to consider them.@refill
+
+To gain speed, we have put various constraints on the way @code{make}
+considers match-anything rules.  There are two different constraints that
+can be applied, and each time you define a match-anything rule you must
+choose one or the other for that rule.
+
+One choice is to mark the match-anything rule as @dfn{terminal} by defining
+it with a double colon.  When a rule is terminal, it does not apply
+unless its dependencies actually exist.  Dependencies that could be made
+with other implicit rules are not good enough.
+
+For example, the built-in implicit rules for extracting sources from RCS
+and SCCS files are terminal; as a result, if the file @file{foo.c,v} does
+not exist, @code{make} will not even consider trying to make it as an
+intermediate file from @file{foo.c,v.o} or from @file{RCS/SCCS/s.foo.c,v}.
+RCS and SCCS files are generally ultimate source files, which should not be
+remade from any other files; therefore, @code{make} can save time by not
+looking for ways to remake them.@refill
+
+If you do not mark the match-anything rule as terminal, then it is
+nonterminal.  A nonterminal match-anything rule cannot apply to a file name
+that indicates a specific type of data.  A file name indicates a specific
+type of data if some non-match-anything implicit rule target matches it.
+
+For example, the file name @file{foo.c} matches the target for the pattern
+rule @samp{%.c : %.y} (the rule to run Yacc).  Regardless of whether this
+rule is actually applicable (which happens only if there is a file
+@file{foo.y}), the fact that its target matches is enough to prevent
+consideration of any nonterminal match-everything rules for the file
+@file{foo.c}.  Thus, @code{make} will not even consider trying to make
+@file{foo.c} as an executable file from @file{foo.c.o}, @file{foo.c.c},
+@file{foo.c.p}, etc.@refill
+
+The motivation for this constraint is that nonterminal match-everything
+rules are used for making files containing specific types of data (such as
+executable files) and a file name with a recognized suffix indicates a
+specific different type of data (such as a C source file).
+
+Special built-in dummy pattern rules are provided solely to recognize
+certain file names so that nonterminal match-everything rules won't be
+considered.  These dummy rules have no dependencies and no commands, and
+they are ignored for all other purposes.  For example, the built-in
+implicit rule
+
+@example
+%.p :
+@end example
+
+@noindent
+exists to make sure that Pascal source files such as @file{foo.p} match a
+specific target pattern and thereby prevent time from being wasted looking
+for @file{foo.p.o} or @file{foo.p.c}.
+
+@node Cancelling Rules,, Match-Anything Rules, Pattern Rules
+@subsection Cancelling Implicit Rules
+
+You can override a built-in implicit rule by defining a new pattern rule
+with the same target and dependencies, but different commands.  When the
+new rule is defined, the built-in one is replaced.  The new rule's position
+in the sequence of implicit rules is determined by where you write the new
+rule.
+
+You can cancel a built-in implicit rule by defining a pattern rule with the
+same target and dependencies, but no commands.  For example, the following
+would cancel the rule that runs the assembler:
+
+@example
+%.o : %.s
+@end example
+
+@node Last Resort, Suffix Rules, Pattern Rules, Implicit
+@section Defining Last-Resort Default Rules
+
+@findex .DEFAULT
+You can define a last-resort implicit rule by writing a rule for the target
+@code{.DEFAULT}.  Such a rule's commands are used for all targets and
+dependencies that have no commands of their own and for which no other
+implicit rule applies.  Naturally, there is no @code{.DEFAULT} rule unless
+you write one.
+
+For example, when testing a makefile, you might not care if the source
+files contain real data, only that they exist.  Then you might do this:
+
+@example
+.DEFAULT:
+        touch $@@
+@end example
+
+@noindent
+to cause all the source files needed (as dependencies) to be created
+silently.
+
+@node Suffix Rules, Search Algorithm, Last Resort, Implicit
+@section Old-Fashioned Suffix Rules
+@cindex 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
+general and clearer.  They are supported in GNU @code{make} for
+compatibility with old makefiles.  They come in two kinds:
+@dfn{double-suffix} and @dfn{single-suffix}.@refill
+
+A double-suffix rule is defined by a pair of suffixes: the target suffix
+and the source suffix.  It matches any file whose name ends with the target
+suffix.  The corresponding implicit dependency is to the file name made by
+replacing the target suffix with the source suffix.  A two-suffix rule
+whose target and source suffixes are @samp{.o} and @samp{.c} is equivalent
+to the pattern rule @samp{%.o : %.c}.
+
+A single-suffix rule is defined by a single suffix, which is the source
+suffix.  It matches any file name, and the corresponding implicit
+dependency name is made by appending the source suffix.  A single-suffix
+rule whose source suffix is @samp{.c} is equivalent to the pattern rule
+@samp{% : %.c}.
+
+Suffix rule definitions are recognized by comparing each rule's target
+against a defined list of known suffixes.  When @code{make} sees a rule
+whose target is a known suffix, this rule is considered a single-suffix
+rule.  When @code{make} sees a rule whose target is two known suffixes
+concatenated, this rule is taken as a double-suffix rule.
+
+For example, @samp{.c} and @samp{.o} are both on the default list of known
+suffixes.  Therefore, if you define a rule whose target is @samp{.c.o},
+@code{make} takes it to be a double-suffix rule with source suffix
+@samp{.c} and target suffix @samp{.o}.  For example, here is the old
+fashioned way to define the rule for compiling a C source:@refill
+
+@example
+.c.o:
+        $(CC) -c $(CFLAGS) -o $@@ $<
+@end example
+
+@findex .SUFFIXES
+The known suffixes are simply the names of the dependencies of the special
+target @code{.SUFFIXES}.  You can add your own suffixes by writing a rule
+for @code{.SUFFIXES} that adds more dependencies, as in
+
+@example
+.SUFFIXES: .hack .win
+@end example
+
+@noindent
+which adds @samp{.hack} and @samp{.win} to the end of the list of suffixes.
+
+If you wish to eliminate the default known suffixes instead of just adding
+to them, write a rule for @code{.SUFFIXES} with no dependencies.  By
+special dispensation, this eliminates all existing dependencies of
+@code{.SUFFIXES}.  You can then write another rule to add the suffixes you
+want.  For example,
+
+@example
+.SUFFIXES:    @r{# Delete the default suffixes}
+.SUFFIXES: .c .o .h   @r{# Define our suffix list}
+@end example
+
+The @samp{-r} flag causes the default list of suffixes to be empty.
+
+@node Search Algorithm,, Last Resort, Implicit
+@section Implicit Rule Search Algorithm
+
+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
+rule with no commands, for each target of ordinary rules none of which have
+commands, and for each dependency that is not the target of any rule.  It
+is also followed recursively for dependencies that come from implicit
+rules, in the search for a chain of rules.
+
+Suffix rules are not mentioned in this algorithm because suffix rules are
+converted to equivalent pattern rules after the makefiles have been read
+in.
+
+For an archive member target of the form
+@samp{@var{archive}(@var{member})}, the following algorithm is run twice,
+first using @samp{(@var{member})} as the target @var{t}, and second using
+the entire target if the first run found no rule.@refill
+
+@enumerate
+@item
+Split @var{t} into a directory part, called @var{d}, and the rest,
+called @var{n}.  For example, if @var{t} is @samp{src/foo.o}, then
+@var{d} is @samp{src/} and @var{n} is @samp{foo.o}.@refill
+
+@item
+Make a list of the pattern rules whose target matches @var{d} or
+@var{n}.  If the target pattern contains a slash, it is matched
+against @var{t}; otherwise, against @var{n}.
+
+@item
+If any rule in that list is @emph{not} a match-anything rule, then
+remove all nonterminal match-anything rules from the list.
+
+@item
+Remove any rules with no dependencies from the list.
+
+@item
+For each pattern rule in the list:
+
+@enumerate
+@item
+Find the stem @var{s}: the part of @var{d} or @var{n} that the
+@samp{%} in the target pattern matches.@refill
+
+@item
+Compute the dependency names by substituting @var{s} for @samp{%}; if
+the target pattern does not contain a slash, @var{d} is appended to
+the front of each dependency name.
+
+@item
+Test whether all the dependencies exist or ought to exist.  (If a
+file name mentioned in the makefile as a target or as an explicit
+dependency then we say it ought to exist.)
+
+If all dependencies exist or ought to exist, then this rule applies.
+@end enumerate
+
+@item
+If no pattern rule has been found so far, try harder.  For
+each pattern rule in the list:
+
+@enumerate
+@item
+If the rule is a terminal match-anything rule, ignore it and go
+on to the next rule.
+
+@item
+Compute the dependency names as before.
+
+@item
+Test whether all the dependencies exist or ought to exist.
+
+@item
+For each dependency that does not exist, follow this algorithm
+recursively to see if the dependency can be made by an implicit
+rule.
+
+@item
+If all dependencies exist, ought to exist, or can be made by
+implicit rules, then this rule applies.
+@end enumerate
+
+@item
+If no rule has been found so far, this target cannot be made by an
+implicit rule.  Return failure.
+
+@item
+If no implicit rule applies, the rule for @code{.DEFAULT}, if any,
+applies.  In that case, give @var{t} the same commands that
+@code{.DEFAULT} has.  Otherwise, there are no commands for @var{t}.
+@end enumerate
+
+When the commands of a pattern rule are executed for @var{t}, the automatic
+variables @samp{$@@}, @samp{$*} and @samp{$<} are set as follows:
+
+@table @samp
+@item $@@
+@var{t}
+@item $*
+If the target pattern contains a slash, this is @var{s}; otherwise, it
+is @var{d}@var{s}.
+@item $<
+The name of the first dependency that came via the implicit rule.
+@end table
+
+For @code{.DEFAULT} commands, as for non-implicit commands, @samp{$*}
+and @samp{$<} are empty.  @samp{$@@} is @var{t}, as always.
+
+@node Archives, Missing, Implicit, Top
+@chapter Using @code{make} to Update Archive Files
+@cindex archive
+
+@dfn{Archive files} are files containing named subfiles called
+@dfn{members}; they are maintained with the program @code{ar} and their
+main use is as subroutine libraries for linking.
+
+@menu
+* Members: Archive Members.    How to name an archive member
+				as a target or dependency.
+* Update: Archive Update.      An implicit rule can update
+				most archive member targets just right.
+* Symbols: Archive Symbols.    Another implicit rule runs @code{ranlib}
+				to update the special member @file{__.SYMDEF}.
+@end menu
+
+@node Archive Members, Archive Update, Archives, Archives
+@section Archive Members as Targets
+@cindex archive member targets
+
+An individual member of an archive file can be used as a target or
+dependency in @code{make}.  The archive file must already exist, but the
+member need not exist.  You specify the member named @var{member} in
+archive file @var{archive} as follows:
+
+@example
+@var{archive}(@var{member})
+@end example
+
+@noindent
+This construct is available only in targets and dependencies, not in
+commands!  Most programs that you might use in commands do not support this
+syntax and cannot act directly on archive members.  Only @code{ar} and
+other programs specifically designed to operate on archives can do so.
+Therefore, valid commands to update an archive member target probably must
+use @code{ar}.  For example, this rule says to create a member
+@file{hack.o} in archive @file{foolib} by copying the file @file{hack.o}:
+
+@example
+foolib(hack.o) : hack.o
+        ar r foolib hack.o
+@end example
+
+In fact, nearly all archive member targets are updated in just this way
+and there is an implicit rule to do it for you.
+
+@node Archive Update, Archive Symbols, Archive Members, Archives
+@section Implicit Rule for Archive Member Targets
+
+Recall that a target that looks like @file{@var{a}(@var{m})} stands for the
+member named @var{m} in the archive file @var{a}.
+
+When @code{make} looks for an implicit rule for such a target, as a special
+feature it considers implicit rules that match @file{(@var{m})}, as well as
+those that match the actual target @file{@var{a}(@var{m})}.
+
+This causes one special rule whose target is @file{(%)} to match.  This
+rule updates the target @file{@var{a}(@var{m})} by copying the file @var{m}
+into the archive.  For example, it will update the archive member target
+@file{foo.a(bar.o)} by copying the @emph{file} @file{bar.o} into the
+archive @file{foo.a} as a member named @file{bar.o}.
+
+When this rule is chained with others, the result is very powerful.  The
+command @samp{make "foo.a(bar.o)"} in the presence of a file @file{bar.c}
+is enough to cause the following commands to be run, even without a
+makefile:
+
+@example
+cc -c bar.c -o bar.o
+ar r foo.a bar.o
+rm -f bar.o
+@end example
+
+@noindent
+Here the file @file{bar.o} has been invented as an intermediate file.
+
+@node Archive Symbols,, Archive Update, Archives
+@subsection Updating Archive Symbol Directories
+@cindex __.SYMDEF
+
+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
+names defined by all the other members.  After you update any other
+members, you need to update @file{__.SYMDEF} so that it will summarize the
+other members properly.  This is done by running the @code{ranlib} program:
+
+@example
+ranlib @var{archivefile}
+@end example
+
+Normally you would put this command in the rule for the archive file,
+and make all the members of the archive file dependents of that rule.
+For example,
+
+@example
+libfoo.a: libfoo.a(x.o) libfoo.a(y.o) @dots{}
+        ranlib libfoo.a
+@end example
+
+@noindent
+The effect of this is to update archive members @file{x.o}, @file{y.o},
+etc., and then update the symbol directory member @file{__.SYMDEF} by
+running @code{ranlib}.  The rules for updating the members are not shown
+here; most likely you can omit them and use the implicit rule which copies
+files into the archive, as described in the preceding section.
+
+@node Missing, Concept Index, Archives, Top
+The variable @code{MAKELEVEL} which keeps track of the current level
+of @code{make} recursion.  @xref{Recursion}.
+The @code{make} programs in various other systems support two features that
+are not implemented in GNU @code{make}.
+Static pattern rules.  @xref{Static Pattern}.
+
+@item
+Selective @code{vpath} search.  @xref{Directory Search}.
+
+@item
+Recursive variable references.  @xref{Reference}.
+@end itemize
+
+@node Missing, Concept Index, Features, Top
+@chapter Missing Features in GNU @code{make}
+
+The @code{make} programs in various other systems support a few features
+that are not implemented in GNU @code{make}.
+
+suffix rule @samp{.c~.o} would make files @file{@var{n}.o} file from
+@item
+A target of the form @samp{@var{file}((@var{entry}))} stands for a member
+of archive file @var{file}.  The member is chosen, not by name, but by
+being an object file which defines the linker symbol @var{entry}.@refill
+
+This feature was not put into GNU @code{make} because of the
+@noindent
+can be replaced with the GNU @code{make} static pattern rule:
+
+@example
+$(targets): %: %.o lib.a
+@end example
+
+@item
+In System V and 4.3 BSD @code{make}, files found by @code{VPATH} search
+(@pxref{Directory Search}) have their names changed inside command strings.
+We feel it is much cleaner to always use automatic variables and thus
+obviate the need for this feature.  We are still debating whether to
+implement this to be compatible or to leave it out to avoid such ugliness.
+@end itemize
+
+@node Concept Index, Name Index, Missing, Top
+@unnumbered Index of Concepts
+
+@printindex cp
+
+@node Name Index,, Concept Index, Top
+@unnumbered Index of Functions, Directives and Variables
+
+@printindex fn
+
+@contents
+@bye