@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:
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
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
* 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
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
@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 :=
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
override @var{variable} = @var{value}
@end example
+@noindent
or
@example
@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
@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
@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
@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}.
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++
@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
@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
@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:
@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)}}.
@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)}.
@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
@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}
@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
@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
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
@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
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}:
projects / platform / upstream / make.git / commitdiff