Formerly make.texinfo.~88~

1 files changed, 204 insertions, 82 deletions

diff --git a/make.texinfo b/make.texinfo
index 61df072..1679e8f 100644
--- a/make.texinfo
+++ b/make.texinfo
@@ -3,58 +3,19 @@
 @setfilename make.info
 @settitle GNU @code{make}
 @setchapternewpage odd
-@smallbook
 @c %**end of header
 
+@c For publication, format makebook.texi instead of using this file directly.
+
 @set EDITION 0.41
 @set VERSION 3.64 Beta
-@set UPDATED 11 April 1993
+@set UPDATED 12 April 1993
 @set UPDATE-MONTH April 1993
 
 @c finalout
 
 @c ISPELL CHECK: done, 14 Jan 1993 --bob
 
-@comment @ifset seems to be completely broken.
-@ignore
-@tex
-\message{If you do not have the two-level texindex program, you will lose.}
-% trying for a two-level index
-% You need the rewritten texindex program for this to work.
-
-\gdef\singleindexerfoo#1, #2\par{%
-% Use a box register to test if #2 is empty.
-\setbox0=\hbox{#2}%
-\ifvoid0{%                      % A one-level entry.
-\doind{\indexname}{#1}}\else{%  % A two-level entry.
-\dosubind{\indexname}{#1}{#2}%
-}\fi}
-\gdef\singleindexer#1{\singleindexerfoo#1, \par}
-
-% This version writes two sort strings.
-\gdef\dosubind #1#2#3{%
-{\count10=\lastpenalty%
-{\indexdummies% Must do this here, since \bf, etc expand at this stage
-\escapechar=`\\%
-{\let\folio=0%
-\def\rawbackslashxx{\indexbackslash}%
-%
-% Now process the index-string once, with all font commands turned off,
-% to get the string to sort the index by.
-{\indexnofonts%
-\xdef\tempa{#2}%
-\xdef\tempb{#3}%
-}%
-% Now produce the complete index entry.  We process the index-string again,
-% this time with font commands expanded, to get what to print in the index.
-\edef\temp{%
-\write \csname#1indfile\endcsname{%
-\realbackslash entry {\tempa}{\folio}{#2}{#3}{\tempb}}}%
-\temp}%
-}\penalty\count10}}
-@end tex
-@end ignore
-
 @c Combine the variable and function indices:
 @syncodeindex vr fn
 @c Combine the program and concept indices:
@@ -95,11 +56,9 @@ entitled ``GNU General Public License'' must be approved for accuracy
 by the Foundation.
 @end ifinfo
 
-@ignore
-@ifset shorttitlepage
+@iftex
 @shorttitlepage GNU Make
-@end ifset
-@end ignore
+@end iftex
 @titlepage
 @title GNU Make
 @subtitle A Program for Directing Recompilation
@@ -3069,9 +3028,9 @@ the above example, its value is @samp{CFLAGS=-O}.  If you @emph{do not}
 want these variable definitions done in all recursive @code{make}
 invocations, you can redefine the @code{MAKEOVERRIDES} variable to
 remove them.  You do this in any of the normal ways for defining
-variables: in a makefile (@pxref{Setting Variables}); on the command
+variables: in a makefile (@pxref{Setting, ,Setting Variables}); on the command
 line with an argument like @samp{MAKEOVERRIDES=} 
-(@pxref{Overriding Variables}); or with an environment variable
+(@pxref{Overriding, ,Overriding Variables}); or with an environment variable
 (@pxref{Environment, ,Variables from the Environment}).
 
 As a special feature, using the variable @code{MAKE} in the commands of
@@ -3525,6 +3484,8 @@ command options (@pxref{Overriding, ,Overriding Variables}).
 * Advanced::                    Advanced features for referencing a variable.
 * Values::                      All the ways variables get their values.
 * Setting::                     How to set a variable in the makefile.
+* Appending::                   How to append more text to the old value
+                                  of a variable.
 * Override Directive::          How to set a variable in the makefile even if
                                   the user has set it with a command argument.
 * Defining::                    An alternate way to set a variable 
@@ -3869,8 +3830,10 @@ defines @code{a} as @samp{Hello}: @samp{$($(x))} becomes @samp{$($(y))}
 which becomes @samp{$(z)} which becomes @samp{Hello}.
 
 Nested variable references can also contain modified references and
-function invocations (@pxref{Functions, ,Functions for Transforming Text}), just like any other reference.
-For example, using the @code{subst} function (@pxref{Text Functions, ,Functions for String Substitution and Analysis}):
+function invocations (@pxref{Functions, ,Functions for Transforming Text}),
+just like any other reference.
+For example, using the @code{subst} function 
+(@pxref{Text Functions, ,Functions for String Substitution and Analysis}):
 
 @example
 @group
@@ -4026,9 +3989,10 @@ Several variables have constant initial values.
 @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
 @end itemize
 
-@node Setting, Override Directive, Values, Using Variables
+@node Setting, Appending, Values, Using Variables
 @section Setting Variables
 @cindex setting variables
+@cindex variables, setting
 @cindex =
 @cindex :=
 
@@ -4067,13 +4031,140 @@ Several special variables are set
 automatically to a new value for each rule; these are called the
 @dfn{automatic} variables (@pxref{Automatic, ,Automatic Variables}).
 
-@node Override Directive, Defining, Setting, Using Variables
+@node Appending, Override Directive, Setting, Using Variables
+@section Appending More Text to Variables
+@cindex +=
+@cindex appending to variables
+@cindex variables, appending to
+
+Often it is useful to add more text to the value of a variable already defined.
+You do this with a line containing @samp{+=}, like this:
+
+@example
+objects += another.o
+@end example
+
+@noindent
+This takes the value of the variable @code{objects}, and adds the text
+@samp{another.o} to it (preceded by a single space).  Thus:
+
+@example
+objects = main.o foo.o bar.o utils.o
+objects += another.o
+@end example
+
+@noindent
+sets @code{objects} to @samp{main.o foo.o bar.o utils.o another.o}.
+
+Using @samp{+=} is similar to:
+
+@example
+objects = main.o foo.o bar.o utils.o
+objects := $(objects) another.o
+@end example
+
+@noindent
+but differs in ways that become important when you use more complex values.
+
+When the variable in question has not been defined before, @samp{+=}
+acts just like normal @samp{=}: it defines a recursively-expanded
+variable.  However, when there @emph{is} a previous definition, exactly
+what @samp{+=} does depends on what flavor of variable you defined
+originally.  @xref{Flavors, ,The Two Flavors of Variables}, for an
+explanation of the two flavors of variables.
+
+When you add to a variable's value with @samp{+=}, @code{make} acts
+essentially as if you had included the extra text in the initial
+definition of the variable.  If you defined it first with @samp{:=},
+making it a simply-expanded variable, @samp{+=} adds to that
+simply-expanded definition, and expands the new text before appending it
+to the old value just as @samp{:=} does
+(@pxref{Setting, ,Setting Variables}, for a full explanation of @samp{:=}).
+In fact,
+
+@example
+variable := value
+variable += more
+@end example
+
+@noindent
+is exactly equivalent to:
+
+@noindent
+@example
+variable := value
+variable := $(variable) more
+@end example
+
+On the other hand, when you use @samp{+=} with a variable that you defined
+first to be recursively-expanded using plain @samp{=}, @code{make} does
+something a bit different.  Recall that when you define a
+recursively-expanded variable, @code{make} does not expand the value you set
+for variable and function references immediately.  Instead it stores the text
+verbatim, and saves these variable and function references to be expanded
+later, when you refer to the new variable (@pxref{Flavors, ,The Two Flavors
+of Variables}).  When you use @samp{+=} on a recursively-expanded variable,
+it is this unexpanded text to which @code{make} appends the new text you
+specify.
+
+@example
+variable = value
+variable += more
+@end example
+
+@noindent
+is roughly equivalent to:
+
+@example
+temp = value
+variable = $(temp) more
+@end example
+
+@noindent
+except that of course it never defines a variable called @code{temp}.
+The importance of this comes when the variable's old value contains
+variable references.  Take this common example:
+
+@example
+CFLAGS = $(includes) -O
+@dots{}
+CFLAGS += -pg # enable profiling
+@end example
+
+@noindent
+The first line defines the @code{CFLAGS} variable with a reference to another
+variable, @code{includes}.  (@code{CFLAGS} is used by the rules for C
+compilation; @pxref{Catalogue of Rules, ,Catalogue of Implicit Rules}.)
+Using @samp{=} for the definition makes @code{CFLAGS} a recursively-expanded
+variable, meaning @w{@samp{$(includes) -O}} is @emph{not} expanded when
+@code{make} processes the definition of @code{CFLAGS}.  Thus, @code{includes}
+need not be defined yet for its value to take effect.  It only has to be
+defined before any reference to @code{CFLAGS}.  If we tried to append to the
+value of @code{CFLAGS} without using @samp{+=}, we might do it like this:
+
+@example
+CFLAGS := $(CFLAGS) -pg # enable profiling
+@end example
+
+@noindent
+This is close, but not quite what we want.  Using @samp{:=} redefines
+@code{CFLAGS} as a simply-expanded variable; this means @code{make} expands
+the text @w{@samp{$(CFLAGS) -pg}} before setting the variable.  If
+@code{includes} is not yet defined, we get @w{@samp{ -O -pg}}, and a later
+definition of @code{includes} will have no effect.  Conversely, by using
+@samp{+=} we set @code{CFLAGS} to the @emph{unexpanded} value
+@w{@samp{$(includes) -O -pg}}.  Thus we preserve the reference to
+@code{includes}, so if that variable gets defined at any later point, a
+reference like @samp{$(CFLAGS)} still uses its value.
+
+@node Override Directive, Defining, Appending, Using Variables
 @section The @code{override} Directive
 @findex override
 @cindex overriding with @code{override}
-@cindex variable, overriding
+@cindex variables, overriding
 
-If a variable has been set with a command argument (@pxref{Overriding, ,Overriding Variables}),
+If a variable has been set with a command argument 
+(@pxref{Overriding, ,Overriding Variables}),
 then ordinary assignments in the makefile are ignored.  If you want to set
 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
@@ -4083,6 +4174,7 @@ looks like this:@refill
 override @var{variable} = @var{value}
 @end example
 
+@noindent
 or
 
 @example
@@ -4125,7 +4217,7 @@ See the next section for information about @code{define}.
 @findex endef
 @cindex verbatim variable definition
 @cindex defining variables verbatim
-@cindex variable, defining verbatim
+@cindex variables, defining verbatim
 
 Another way to set the value of a variable is to use the @code{define}
 directive.  This directive has an unusual syntax which allows newline
@@ -4182,7 +4274,7 @@ endef
 @node Environment,  , Defining, Using Variables
 @section Variables from the Environment
 
-@cindex variable, environment
+@cindex variables, environment
 @cindex environment
 Variables in @code{make} can come from the environment in which
 @code{make} is run.  Every environment variable that @code{make} sees when
@@ -5136,7 +5228,7 @@ no?), but it is more likely to be a mistake.
 @node Origin Function, Shell Function, Foreach Function, Functions
 @section The @code{origin} Function
 @findex origin
-@cindex variable, origin of
+@cindex variables, origin of
 @cindex origin of variable
 
 The @code{origin} function is unlike most other functions in that it does
@@ -5609,9 +5701,9 @@ Touch all the object files with @samp{make -t}.
 @node Overriding, Testing, Avoiding Compilation, Running
 @section Overriding Variables
 @cindex overriding variables with arguments
-@cindex variable, overriding with arguments
+@cindex variables, overriding with arguments
 @cindex command line variables
-@cindex variable, command line
+@cindex variables, command line
 
 An argument that contains @samp{=} specifies the value of a variable:
 @samp{@var{v}=@var{x}} sets the value of the variable @var{v} to @var{x}.
@@ -6092,35 +6184,38 @@ available unless the makefile explicitly overrides or cancels them.
 canceling or overriding an implicit rule.  The @samp{-r} or
 @samp{--no-builtin-rules} option cancels all predefined rules.
 
-Not all of these rules will always be defined, even when the @samp{-r}
-option is not given.  Many of the predefined implicit rules are
-implemented in @code{make} as suffix rules, so which ones will be
-defined depends on the @dfn{suffix list} (the list of dependencies of
-the special target @code{.SUFFIXES}).  The default suffix list is:
-@code{.out}, @code{.a}, @code{.ln}, @code{.o}, @code{.c}, @code{.cc},
-@code{.C}, @code{.p}, @code{.f}, @code{.F}, @code{.r}, @code{.y},
-@code{.l}, @code{.s}, @code{.S}, @code{.mod}, @code{.sym},
-@code{.def}, @code{.h}, @code{.info}, @code{.dvi}, @code{.tex},
-@code{.texinfo}, @code{.texi}, @code{.cweb}, @code{.web}, @code{.sh},
-@code{.elc}, @code{.el}.  All of the implicit rules described below
-whose dependencies have one of these suffixes are actually suffix
-rules.  If you modify the suffix list, the only predefined suffix
-rules in effect will be those named by one or two of the suffixes that
-are on the list you specify; rules whose suffixes fail to be on the
-list are disabled.  @xref{Suffix Rules, ,Old-Fashioned Suffix Rules},
-for full details on suffix rules.
+Not all of these rules will always be defined, even when the @samp{-r} option
+is not given.  Many of the predefined implicit rules are implemented in
+@code{make} as suffix rules, so which ones will be defined depends on the
+@dfn{suffix list} (the list of dependencies of the special target
+@code{.SUFFIXES}).  The default suffix list is: @code{.out}, @code{.a},
+@code{.ln}, @code{.o}, @code{.c}, @code{.cc}, @code{.C}, @code{.p},
+@code{.f}, @code{.F}, @code{.r}, @code{.y}, @code{.l}, @code{.s}, @code{.S},
+@code{.mod}, @code{.sym}, @code{.def}, @code{.h}, @code{.info}, @code{.dvi},
+@code{.tex}, @code{.texinfo}, @code{.texi}, @code{.txinfo}, @code{.cweb},
+@code{.web}, @code{.sh}, @code{.elc}, @code{.el}.  All of the implicit rules
+described below whose dependencies have one of these suffixes are actually
+suffix rules.  If you modify the suffix list, the only predefined suffix
+rules in effect will be those named by one or two of the suffixes that are on
+the list you specify; rules whose suffixes fail to be on the list are
+disabled.  @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}, for full details
+on suffix rules.
 
 @table @asis
 @item Compiling C programs
 @cindex C, rule to compile
 @pindex cc
 @pindex gcc
+@pindex .o
+@pindex .c
 @file{@var{n}.o} is made automatically from @file{@var{n}.c} with
 a command of the form @samp{$(CC) -c $(CPPFLAGS) $(CFLAGS)}.@refill
 
 @item Compiling C++ programs
 @cindex C++, rule to compile
 @pindex g++
+@pindex .C
+@pindex .cc
 @file{@var{n}.o} is made automatically from @file{@var{n}.cc} or
 @file{@var{n}.C} with a command of the form @samp{$(CXX) -c $(CPPFLAGS)
 $(CXXFLAGS)}.  We encourage you to use the suffix @samp{.cc} for C++
@@ -6129,6 +6224,7 @@ source files instead of @samp{.C}.@refill
 @item Compiling Pascal programs
 @cindex Pascal, rule to compile
 @pindex pc
+@pindex .p
 @file{@var{n}.o} is made automatically from @file{@var{n}.p}
 with the command @samp{$(PC) -c $(PFLAGS)}.@refill
 
@@ -6136,6 +6232,9 @@ with the command @samp{$(PC) -c $(PFLAGS)}.@refill
 @cindex Fortran, rule to compile
 @cindex Ratfor, rule to compile
 @pindex f77
+@pindex .f
+@pindex .r
+@pindex .F
 @file{@var{n}.o} is made automatically from @file{@var{n}.r},
 @file{@var{n}.F} or @file{@var{n}.f} by running the
 Fortran compiler.  The precise command used is as follows:@refill
@@ -6165,6 +6264,9 @@ program.  The precise command used is as follows:@refill
 @item Compiling Modula-2 programs
 @cindex Modula-2, rule to compile
 @pindex m2c
+@pindex .sym
+@pindex .def
+@pindex .mod
 @file{@var{n}.sym} is made from @file{@var{n}.def} with a command
 of the form @samp{$(M2C) $(M2FLAGS) $(DEFFLAGS)}.  @file{@var{n}.o}
 is made from @file{@var{n}.mod}; the form is:
@@ -6174,10 +6276,12 @@ is made from @file{@var{n}.mod}; the form is:
 @item Assembling and preprocessing assembler programs
 @cindex assembly, rule to compile
 @pindex as
+@pindex .s
 @file{@var{n}.o} is made automatically from @file{@var{n}.s} by
 running the assembler, @code{as}.  The precise command is
 @samp{$(AS) $(ASFLAGS)}.@refill
 
+@pindex .S
 @file{@var{n}.s} is made automatically from @file{@var{n}.S} by
 running the C preprocessor, @code{cpp}.  The precise command is
 @w{@samp{$(CPP) $(CPPFLAGS)}}.
@@ -6228,12 +6332,14 @@ done.@refill
 @item Yacc for C programs
 @pindex yacc
 @cindex Yacc, rule to run
+@pindex .y
 @file{@var{n}.c} is made automatically from @file{@var{n}.y} by
 running Yacc with the command @samp{$(YACC) $(YFLAGS)}.
 
 @item Lex for C programs
 @pindex lex
 @cindex Lex, rule to run
+@pindex .l
 @file{@var{n}.c} is made automatically from @file{@var{n}.l} by
 by running Lex.  The actual command is @samp{$(LEX) $(LFLAGS)}.
 
@@ -6262,6 +6368,7 @@ the list of implicit rule suffixes with:@refill
 @item Making Lint Libraries from C, Yacc, or Lex programs
 @pindex lint
 @cindex @code{lint}, rule to run
+@pindex .ln
 @file{@var{n}.ln} is made from @file{@var{n}.c} with a command of
 the form @w{@samp{$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i}}.  
 The same command is used on the C code produced from 
@@ -6275,6 +6382,10 @@ The same command is used on the C code produced from
 @pindex weave
 @pindex tangle
 @pindex ctangle
+@pindex .dvi
+@pindex .tex
+@pindex .web
+@pindex .cweb
 @file{@var{n}.dvi} is made from @file{@var{n}.tex} with the
 command @samp{$(TEX)}.  @file{@var{n}.tex} is made from
 @file{@var{n}.web} with @samp{$(WEAVE)}, or from @file{@var{n}.cweb}
@@ -6287,14 +6398,19 @@ made from @file{@var{n}.cweb} with @samp{$(CTANGLE)}.@refill
 @cindex Info, rule to format
 @pindex texi2dvi
 @pindex makeinfo
-@file{@var{n}.dvi} is made from @file{@var{n}.texinfo} or
-@file{@var{n}.texi} with the @samp{$(TEXI2DVI)} command.
-@file{@var{n}.info} is made from @file{@var{n}.texinfo} or
-@file{@var{n}.texi} with the @samp{$(MAKEINFO)} command .@refill
+@pindex .texinfo
+@pindex .info
+@pindex .texi
+@pindex .txinfo
+@file{@var{n}.dvi} is made from @file{@var{n}.texinfo}, @file{@var{n}.texi},
+or @file{@var{n}.txinfo}, with the @samp{$(TEXI2DVI)} command.
+@file{@var{n}.info} is made from @file{@var{n}.texinfo}, @file{@var{n}.texi},
+or @file{@var{n}.txinfo}, with the @samp{$(MAKEINFO)} command.@refill
 
 @item RCS
 @cindex RCS, rule to extract from
 @pindex co
+@pindex ,v @r{(RCS file extension)}
 Any file @file{@var{n}} is extracted if necessary from an RCS file
 named either @file{@var{n},v} or @file{RCS/@var{n},v}.  The precise
 command used is @w{@samp{$(CO) $(COFLAGS)}}.  @file{@var{n}} will not be
@@ -6307,6 +6423,7 @@ actually exist.@refill
 @item SCCS
 @cindex SCCS, rule to extract from
 @pindex get
+@pindex s. @r{(SCCS file prefix)}
 Any file @file{@var{n}} is extracted if necessary from an SCCS file
 named either @file{s.@var{n}} or @file{SCCS/s.@var{n}}.  The precise
 command used is @w{@samp{$(GET) $(GFLAGS)}}.  The rules for SCCS are
@@ -6314,6 +6431,7 @@ terminal (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}),
 so SCCS files cannot be generated from another source; they must
 actually exist.@refill
 
+@pindex .sh
 For the benefit of SCCS, a file @file{@var{n}} is copied from
 @file{@var{n}.sh} and made executable (by everyone).  This is for
 shell scripts that are checked into SCCS.  Since RCS preserves the
@@ -6770,8 +6888,8 @@ dependencies, and it will execute happily ever after.)@refill
 @node Automatic, Pattern Match, Pattern Examples, Pattern Rules
 @subsection Automatic Variables
 @cindex automatic variables
-@cindex variable, automatic
-@cindex variable, and implicit rule
+@cindex variables, automatic
+@cindex variables, and implicit rule
 
 Suppose you are writing a pattern rule to compile a @samp{.c} file into a
 @samp{.o} file: how do you write the @samp{cc} command so that it operates
@@ -7631,6 +7749,10 @@ inspired whom, since GNU @code{make} had @code{patsubst} before SunOS
 The special significance of @samp{+} characters preceding command lines
 (@pxref{Instead of Execution, ,Instead of Executing the Commands}) is
 mandated by draft 11.2 of IEEE Std 1003.2 (POSIX).@refill
+
+@item
+The @samp{+=} syntax to append to the value of a variable comes from SunOS
+4.0 @code{make}.  @xref{Appending, , Appending More Text to Variables}.
 @end itemize
 
 The remaining features are inventions new in GNU @code{make}: