New manual section `Parallel Make'.

* doc/autoconf.texi (Parallel Make): New node, document NetBSD
`make -jN' quirks.
(Top, Portable Make): Adjust menus.

Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de>

diff --git a/ChangeLog b/ChangeLog
index 160449dd5ef8fb290f765143e2f1fa4d1260c2a4..331f2debe79dada834ef43f8876a2a91bbf61092 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2009-05-17  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>
+
+       New manual section `Parallel Make'.
+       * doc/autoconf.texi (Parallel Make): New node, document NetBSD
+       `make -jN' quirks.
+       (Top, Portable Make): Adjust menus.
+
 2009-05-14  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>
 
        testsuite: skip `Multiple languages' test without C++ compiler.

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 928b41789f8895b5002f592abb0dc765f992a087..7f0440800557aabc3f6e069d43e56ec6d0244eb2 100644 (file)
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -509,6 +509,7 @@ Portable Make Programming
 * Macros and Submakes::         @code{make macro=value} and submakes
 * The Make Macro MAKEFLAGS::    @code{$(MAKEFLAGS)} portability issues
 * The Make Macro SHELL::        @code{$(SHELL)} portability issues
+* Parallel Make::               Parallel @command{make} quirks
 * Comments in Make Rules::      Other problems with Make comments
 * obj/ and Make::               Don't name a subdirectory @file{obj}
 * make -k Status::              Exit status of @samp{make -k}
@@ -17567,6 +17568,7 @@ itself.
 * Macros and Submakes::         @code{make macro=value} and submakes
 * The Make Macro MAKEFLAGS::    @code{$(MAKEFLAGS)} portability issues
 * The Make Macro SHELL::        @code{$(SHELL)} portability issues
+* Parallel Make::               Parallel @command{make} quirks
 * Comments in Make Rules::      Other problems with Make comments
 * obj/ and Make::               Don't name a subdirectory @file{obj}
 * make -k Status::              Exit status of @samp{make -k}
@@ -17878,6 +17880,66 @@ $ @kbd{env SHELL=sh gmake -e SHELL=/bin/ksh}  # GNU make 3.81
 sh
 @end example
 
+@node Parallel Make
+@section Parallel Make
+@cindex Parallel @command{make}
+
+Support for parallel execution in @command{make} implementation varies.
+Generally, using @acronym{GNU} make is your best bet.  When NetBSD
+@command{make} is invoked with @option{-j@var{N}}, it will reuse the
+same shell for multiple commands within one recipe.  This can have
+unexpected consequences.@footnote{Note that @acronym{GNU} make has
+heuristics to avoid spawning a shell at all if the command is deemed
+safe to be executed directly.} For example, change of directories or
+variables persist between commands:
+
+@example
+all:
+        @@var=value; cd /; pwd; echo $$var; echo $$$$
+        @@pwd; echo $$var; echo $$$$
+@end example
+
+@noindent
+may output the following with @code{make -j1}:
+
+@example
+--- all ---
+/
+value
+32235
+/
+value
+32235
+@end example
+
+while without @option{-j1}, or with @option{-B}, the output looks less
+surprising:
+
+@example
+/
+value
+32238
+/tmp
+
+32239
+@end example
+
+Another consequence of this is that, if one command in a recipe uses
+@code{exit 0} to indicate a successful exit, the shell will be gone
+and the remaining commands of this recipe will not be executed.
+
+The above example also shows additional status output NetBSD
+@command{make} produces in parallel mode for targets being updated.
+
+Furthermore, parallel NetBSD @command{make} will route standard error
+from commands that it spawns into its own standard output, and may
+remove leading whitespace from output lines.
+
+You can avoid these issues by using the @option{-B} option to enable
+compatibility semantics.  However, that will effectively also disable
+all parallelism as that will cause prerequisites to be updated in the
+order they are listed in a rule.
+
 @node Comments in Make Rules
 @section Comments in Make Rules
 @cindex Comments in @file{Makefile} rules