- Many fixup patches from Savannah.

- Fix the test suite on Solaris (from Boris)
- Update the manual for .ONESHELL

1 files changed, 158 insertions, 45 deletions

diff --git a/doc/make.texi b/doc/make.texi
index 35a40dd..b7c54bf 100644
--- a/doc/make.texi
+++ b/doc/make.texi
@@ -3,7 +3,7 @@
 @setfilename make.info
 
 @include version.texi
-@set EDITION 0.70
+@set EDITION 0.71
 @set RCSID $Id$
 
 @settitle GNU @code{make}
@@ -25,9 +25,9 @@ and issues the commands to recompile them.
 This is Edition @value{EDITION}, last updated @value{UPDATED},
 of @cite{The GNU Make Manual}, for GNU @code{make} version @value{VERSION}.
 
-Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
-1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
-Free Software Foundation, Inc.
+Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
+1996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007,
+2008, 2009, 2010 Free Software Foundation, Inc.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -524,13 +524,13 @@ A @dfn{prerequisite} is a file that is used as input to create the
 target.  A target often depends on several files.
 
 @cindex tabs in rules
-A @dfn{recipe} is an action that @code{make} carries out.
-A recipe may have more than one command, each on its own line.
-@strong{Please note:} you need to put a tab character at the beginning of
-every command line!  This is an obscurity that catches the unwary.  If
-you prefer to prefix your recipes with a character other than tab,
-you can set the @code{.CMDPREFIX} variable to an alternate character
-(@pxref{Special Variables}).
+A @dfn{recipe} is an action that @code{make} carries out.  A recipe
+may have more than one command, either on the same line or each on its
+own line.  @strong{Please note:} you need to put a tab character at
+the beginning of every recipe line!  This is an obscurity that catches
+the unwary.  If you prefer to prefix your recipes with a character
+other than tab, you can set the @code{.RECIPEPREFIX} variable to an
+alternate character (@pxref{Special Variables}).
 
 Usually a recipe is in a rule with prerequisites and serves to create a
 target file if any of the prerequisites change.  However, the rule that
@@ -629,13 +629,13 @@ on the header file @file{defs.h}.
 A recipe may follow each line that contains a target and
 prerequisites.  These recipes say how to update the target file.  A
 tab character (or whatever character is specified by the
-@code{.CMDPREFIX} variable; @pxref{Special Variables}) must come at
+@code{.RECIPEPREFIX} variable; @pxref{Special Variables}) must come at
 the beginning of every line in the recipe to distinguish recipes from
 other lines in the makefile.  (Bear in mind that @code{make} does not
 know anything about how the recipes work.  It is up to you to supply
 recipes that will update the target file properly.  All @code{make}
-does is execute the commands in the recipe you have specified when the
-target file needs to be updated.)@refill
+does is execute the recipe you have specified when the target file
+needs to be updated.)@refill
 @cindex recipe
 
 The target @samp{clean} is not a file, but merely the name of an
@@ -1097,7 +1097,7 @@ include @var{filenames}@dots{}
 
 Extra spaces are allowed and ignored at the beginning of the line, but
 the first character must not be a tab (or the value of
-@code{.CMDPREFIX})---if the line begins with a tab, it will be
+@code{.RECIPEPREFIX})---if the line begins with a tab, it will be
 considered a recipe line.  Whitespace is required between
 @code{include} and the file names, and between file names; extra
 whitespace is ignored there and at the end of the directive.  A
@@ -1768,7 +1768,7 @@ target per rule, but occasionally there is a reason to have more
 @cindex recipes
 @cindex tab character (in commands)
 The @var{recipe} lines start with a tab character (or the first
-character in the value of the @code{.CMDPREFIX} variable;
+character in the value of the @code{.RECIPEPREFIX} variable;
 @pxref{Special Variables}).  The first recipe line may appear on the line
 after the prerequisites, with a tab character, or may appear on the
 same line, with a semicolon.  Either way, the effect is the same.
@@ -1822,12 +1822,12 @@ extra features (@pxref{Recipes, ,Writing Recipes in Rules}).
 There are actually two different types of prerequisites understood by
 GNU @code{make}: normal prerequisites such as described in the
 previous section, and @dfn{order-only} prerequisites.  A normal
-prerequisite makes two statements: first, it imposes an order of
-execution of recipes: any recipes necessary to build any of a
-target's prerequisites will be fully executed before any recipe
-necessary to build the target.  Second, it imposes a dependency
-relationship: if any prerequisite is newer than the target, then the
-target is considered out-of-date and must be rebuilt.
+prerequisite makes two statements: first, it imposes an order in which
+recipes will be invoked: the recipes for all prerequisites of a target
+will be completed before the recipe for the target is run.  Second, it
+imposes a dependency relationship: if any prerequisite is newer than
+the target, then the target is considered out-of-date and must be
+rebuilt.
 
 Normally, this is exactly what you want: if a target's prerequisite is
 updated, then the target should also be updated.
@@ -2874,6 +2874,15 @@ given.  Any recursively invoked @code{make} command will still run
 recipes in parallel (unless its makefile also contains this target).
 Any prerequisites on this target are ignored.
 
+@findex .ONESHELL
+@item .ONESHELL
+@cindex recipe execution, single invocation
+
+If @code{.ONESHELL} is mentioned as a target, then when a target is
+built all lines of the recipe will be given to a single invocation of
+the shell rather than each line being invoked separately
+(@pxref{Execution, ,Recipe Execution}).
+
 @findex .POSIX
 @item .POSIX
 @cindex POSIX-conforming mode, setting
@@ -3387,7 +3396,7 @@ brought up to date.
 
 Users use many different shell programs, but recipes in makefiles are
 always interpreted by @file{/bin/sh} unless the makefile specifies
-otherwise.  @xref{Execution, ,Command Execution}.
+otherwise.  @xref{Execution, ,Recipe Execution}.
 
 @menu
 * Recipe Syntax::               Recipe syntax features and pitfalls.
@@ -3415,7 +3424,7 @@ syntax: it performs only a very few specific translations on the
 content of the recipe before handing it to the shell.
 
 Each line in the recipe must start with a tab (or the first character
-in the value of the @code{.CMDPREFIX} variable; @pxref{Special
+in the value of the @code{.RECIPEPREFIX} variable; @pxref{Special
 Variables}), except that the first recipe line may be attached to the
 target-and-prerequisites line with a semicolon in between.  @emph{Any}
 line in the makefile that begins with a tab and appears in a ``rule
@@ -3690,9 +3699,10 @@ started with @samp{@@}.  A rule in the makefile for the special target
 @vindex @code{SHELL} @r{(recipe execution)}
 
 When it is time to execute recipes to update a target, they are
-executed by invoking a new subshell for each line of the recipe.  (In
-practice, @code{make} may take shortcuts that do not affect the
-results.)
+executed by invoking a new subshell for each line of the recipe,
+unless the @code{.ONESHELL} special target is in effect
+(@pxref{One Shell, ,Using One Shell})  (In practice, @code{make} may
+take shortcuts that do not affect the results.)
 
 @cindex @code{cd} (shell command)
 @cindex shell variables, setting in recipes
@@ -3720,11 +3730,113 @@ problems (in this case it would certainly cause @file{../foo} to be
 truncated, at least).
 
 @menu
+* One Shell::                   One shell for all lines in a recipe
 * Choosing the Shell::          How @code{make} chooses the shell used
                                   to run recipes.
 @end menu
 
-@node Choosing the Shell,  , Execution, Execution
+@node One Shell, Choosing the Shell, Execution, Execution
+@subsection Using One Shell
+@cindex recipe lines, single shell
+@cindex @code{.ONESHELL}, use of
+@findex .ONESHELL
+
+Sometimes you would prefer that all the lines in the recipe be passed
+to a single invocation of the shell.  There are generally two
+situations where this is useful: first, it can improve performance in
+makefiles where recipes consist of many command lines, by avoiding
+extra processes.  Second, you might want newlines to be included in
+your recipe command (for example perhaps you are using a very
+different interpreter as your @code{SHELL}).  If the @code{.ONESHELL}
+special target appears anywhere in the makefile then @emph{all}
+recipe lines for each target will be provided to a single invocation
+of the shell.  Newlines between recipe lines will be preserved.  For
+example:
+
+@example
+.ONESHELL:
+foo : bar/lose
+        cd $(@@D)
+        gobble $(@@F) > ../$@@
+@end example
+
+@noindent
+would now work as expected even though the commands are on different
+recipe lines.
+
+If @code{.ONESHELL} is provided, then only the first line of the
+recipe will be checked for the special prefix characters (@samp{@@},
+@samp{-}, and @samp{+}).  Subsequent lines will include the special
+characters in the recipe line when the @code{SHELL} is invoked.  If
+you want your recipe to start with one of these special characters
+you'll need to arrange for them to not be the first characters on the
+first line, perhaps by adding a comment or similar.  For example, this
+would be a syntax error in Perl because the first @samp{@@} is removed
+by make:
+
+@example
+.ONESHELL:
+SHELL = /usr/bin/perl
+.SHELLFLAGS = -e
+show :
+        @@f = qw(a b c);
+        print "@@f\n";
+@end example
+
+@noindent
+However, either of these alternatives would work properly:
+
+@example
+.ONESHELL:
+SHELL = /usr/bin/perl
+.SHELLFLAGS = -e
+show :
+        # Make sure "@@" is not the first character on the first line
+        @@f = qw(a b c);
+        print "@@f\n";
+@end example
+
+@noindent
+or
+
+@example
+.ONESHELL:
+SHELL = /usr/bin/perl
+.SHELLFLAGS = -e
+show :
+        my @@f = qw(a b c);
+        print "@@f\n";
+@end example
+
+As a special feature, if @code{SHELL} is determined to be a
+POSIX-style shell, the special prefix characters in ``internal''
+recipe lines will @emph{removed} before the recipe is processed.  This
+feature is intended to allow existing makefiles to add the
+@code{.ONESHELL} special target and still run properly without
+extensive modifications.  Since the special prefix characters are not
+legal at the beginning of a line in a POSIX shell script this is not a
+loss in functionality.  For example, this works as expected:
+
+@example
+.ONESHELL:
+foo : bar/lose
+        @@cd $(@@D)
+        @@gobble $(@@F) > ../$@@
+@end example
+
+Even with this special feature, however, makefiles with
+@code{.ONESHELL} will behave differently in ways that could be
+noticeable.  For example, normally if any line in the recipe fails,
+that causes the rule to fail and no more recipe lines are processed.
+Under @code{.ONESHELL} a failure of any but the final recipe line will
+not be noticed by @code{make}.  You can modify @code{.SHELLFLAGS} to
+add the @code{-e} option to the shell which will cause any failure
+anywhere in the command line to cause the shell to fail, but this
+could itself cause your recipe to behave differently.  Ultimately you
+may need to harden your recipe lines to allow them to work with
+@code{.ONESHELL}.
+
+@node Choosing the Shell,  , One Shell, Execution
 @subsection Choosing the Shell
 @cindex shell, choosing the
 @cindex @code{SHELL}, value of
@@ -3828,6 +3940,9 @@ contains @samp{SHELL = /bin/sh} (as many Unix makefiles do), will work
 on MS-DOS unaltered if you have e.g.@: @file{sh.exe} installed in some
 directory along your @code{PATH}.
 
+@vindex SHELL
+@vindex .SHELLFLAGS
+
 @node Parallel, Errors, Execution, Recipes
 @section Parallel Execution
 @cindex recipes, execution in parallel
@@ -5964,8 +6079,8 @@ will contain the number of times this instance has restarted.  Note
 this is not the same as recursion (counted by the @code{MAKELEVEL}
 variable).  You should not set, modify, or export this variable.
 
-@vindex .CMDPREFIX @r{(change the recipe prefix character)}
-@item .CMDPREFIX
+@vindex .RECIPEPREFIX @r{(change the recipe prefix character)}
+@item .RECIPEPREFIX
 The first character of the value of this variable is used as the
 character make assumes is introducing a recipe line.  If the variable
 is empty (as it is by default) that character is the standard tab
@@ -5973,13 +6088,13 @@ character.  For example, this is a valid makefile:
 
 @example
 @group
-.CMDPREFIX = >
+.RECIPEPREFIX = >
 all:
 > @@echo Hello, world
 @end group
 @end example
 
-The value of @code{.CMDPREFIX} can be changed multiple times; once set
+The value of @code{.RECIPEPREFIX} can be changed multiple times; once set
 it stays in effect for all rules parsed until it is modified.
 
 @vindex .VARIABLES @r{(list of variables)}
@@ -10941,7 +11056,7 @@ editors) have attempted to indent your recipe lines with spaces
 instead of a tab character.  In this case, @code{make} will use the
 second form of the error above.  Remember that every line in the
 recipe must begin with a tab character (unless you set
-@code{.CMDPREFIX}; @pxref{Special Variables}).  Eight spaces do not
+@code{.RECIPEPREFIX}; @pxref{Special Variables}).  Eight spaces do not
 count.  @xref{Rule Syntax}.
 
 @item recipe commences before first target.  Stop.
@@ -11201,18 +11316,16 @@ infodir = $(prefix)/info
 
 #### End of system configuration section. ####
 
-SRC1 =  tar.c create.c extract.c buffer.c \
-        getoldopt.c update.c gnu.c mangle.c
-SRC2 =  version.c list.c names.c diffarch.c \
-        port.c wildmat.c getopt.c
-SRC3 =  getopt1.c regex.c getdate.y
-SRCS =  $(SRC1) $(SRC2) $(SRC3)
-OBJ1 =  tar.o create.o extract.o buffer.o \
-        getoldopt.o update.o gnu.o mangle.o
-OBJ2 =  version.o list.o names.o diffarch.o \
-        port.o wildmat.o getopt.o
-OBJ3 =  getopt1.o regex.o getdate.o $(RTAPELIB)
-OBJS =  $(OBJ1) $(OBJ2) $(OBJ3)
+@group
+SRCS_C  = tar.c create.c extract.c buffer.c   \
+          getoldopt.c update.c gnu.c mangle.c \
+          version.c list.c names.c diffarch.c \
+          port.c wildmat.c getopt.c getopt1.c \
+          regex.c
+SRCS_Y  = getdate.y
+SRCS    = $(SRCS_C) $(SRCS_Y)
+OBJS    = $(SRCS_C:.c=.o) $(SRCS_Y:.y=.o) $(RTAPELIB)
+@end group
 @group
 AUX =   README COPYING ChangeLog Makefile.in  \
         makefile.pc configure configure.in \