From 96cdf32954a64884ef28da1e384de5dae49d94e0 Mon Sep 17 00:00:00 2001 From: Stefano Lattarini Date: Tue, 16 Aug 2011 18:31:42 +0200 Subject: docs: other issues with parallel BSD make Motivated by automake bug#9245: and FreeBSD PR bin/159730: * doc/autoconf.texi (Parallel Make): Document other BSD make incompatibilities. Reorganize the existing related documentation accordingly. --- ChangeLog | 11 +++++ doc/autoconf.texi | 142 ++++++++++++++++++++++++++++++++++++------------------ 2 files changed, 107 insertions(+), 46 deletions(-) diff --git a/ChangeLog b/ChangeLog index 6ca51fd6..6e36455c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,14 @@ +2011-08-16 Stefano Lattarini + + docs: other issues with parallel BSD make + Motivated by automake bug#9245: + + and FreeBSD PR bin/159730: + + * doc/autoconf.texi (Parallel Make): Document other BSD make + incompatibilities. Reorganize the existing related documentation + accordingly. + 2011-08-08 Stefano Lattarini docs: fix minor typos diff --git a/doc/autoconf.texi b/doc/autoconf.texi index 7c1818d5..3377afe5 100644 --- a/doc/autoconf.texi +++ b/doc/autoconf.texi @@ -19826,45 +19826,10 @@ sh Support for parallel execution in @command{make} implementation varies. Generally, using GNU make is your best bet. -Some make implementations (among them, FreeBSD @command{make}, NetBSD -@command{make}, and Solaris @command{dmake}), when invoked with a -@option{-j@var{N}} option, connect the standard output and standard -error of all their child processes to pipes or temporary regular -files. This can lead to subtly different semantics in the behaviour -of the spawned processes. For example, even if the @command{make} -standard output is connected to a tty, the recipe command will not be: - -@example -$ @kbd{cat Makefile} -all: - @@test -t 1 && echo "Is a tty" || echo "Is not a tty" -$ @kbd{make -j 2} # FreeBSD make -Is not a tty -$ @kbd{make -j 2} # NetBSD make ---- all --- -Is not a tty -$ @kbd{dmake -j 2} # Solaris dmake -@var{hostname} --> 1 job -@var{hostname} --> Job output -Is not a tty -@end example - -@noindent -On the other hand: - -@example -$ @kbd{make -j 2} # GNU make, Heirloom make -Is a tty -@end example - -Furthermore, parallel runs of those @command{make} implementations will -route standard error from commands that they spawn into their own -standard output, and may remove leading whitespace from output lines. - When NetBSD or FreeBSD @command{make} are run in parallel mode, they will reuse the same shell for multiple commands within one recipe. This can -have unexpected consequences. For example, change of directories or -variables persist between commands: +have various unexpected consequences. For example, changes of directories +or variables persist between recipes, so that: @example all: @@ -19873,10 +19838,10 @@ all: @end example @noindent -may output the following with @code{make -j1}: +may output the following with @code{make -j1}, at least on NetBSD up to +5.1 and FreeBSD up to 8.2: @example ---- all --- / value 32235 @@ -19885,6 +19850,7 @@ value 32235 @end example +@noindent while without @option{-j1}, or with @option{-B}, the output looks less surprising: @@ -19897,19 +19863,103 @@ value 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. +@noindent +Another consequence 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 BSD @command{make} implementations, when run in parallel mode, +will also pass the @command{Makefile} recipes to the shell through +its standard input, thus making it unusable from the recipes: + +@example +$ @kbd{cat Makefile} +read: + @@read line; echo LINE: $$line +@c $$ @c restore font-lock +$ @kbd{echo foo | make read} +LINE: foo +$ @kbd{echo foo | make -j1 read} # NetBSD 5.1 and FreeBSD 8.2 +LINE: +@end example + +@noindent +Moreover, when FreeBSD @command{make} (up at least to 8.2) is run in +parallel mode, it implements the @code{@@} and @code{-} ``recipe +modifiers'' by dynamically modifying the active shell flags. This +behaviour has the effects of potentially clobbering the exit status +of recipes silenced with the @code{@@} modifier if they also unset +the @option{errexit} shell flag, and of mangling the output in +unexpected ways: -The above example also shows additional status output produced by NetBSD -@command{make} (but @emph{not} by FreeBSD @command{make}) in parallel -mode for targets being updated. +@example +$ @kbd{cat Makefile} +a: + @@echo $$-; set +e; false +b: + -echo $$-; false; echo set - +$ @kbd{make a; echo status: $?} +ehBc +*** Error code 1 +status: 1 +$ @kbd{make -j1 a; echo status: $?} +ehB +status: 0 +$ @kbd{make b} +echo $-; echo set - +hBc +set - +$ @kbd{make -j1 b} +echo $-; echo hvB +@end example -You can avoid these issues by using the @option{-B} option to enable +@noindent +You can avoid all 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. +Some make implementations (among them, FreeBSD @command{make}, NetBSD +@command{make}, and Solaris @command{dmake}), when invoked with a +@option{-j@var{N}} option, connect the standard output and standard +error of all their child processes to pipes or temporary regular +files. This can lead to subtly different semantics in the behaviour +of the spawned processes. For example, even if the @command{make} +standard output is connected to a tty, the recipe command will not be: + +@example +$ @kbd{cat Makefile} +all: + @@test -t 1 && echo "Is a tty" || echo "Is not a tty" +$ @kbd{make -j 2} # FreeBSD 8.2 make +Is not a tty +$ @kbd{make -j 2} # NetBSD 5.1 make +--- all --- +Is not a tty +$ @kbd{dmake -j 2} # Solaris 10 dmake +@var{hostname} --> 1 job +@var{hostname} --> Job output +Is not a tty +@end example + +@noindent +On the other hand: + +@example +$ @kbd{make -j 2} # GNU make, Heirloom make +Is a tty +@end example + +@noindent +The above examples also show additional status output produced in parallel +mode for targets being updated by Solaris @command{dmake} and NetBSD +@command{make} (but @emph{not} by FreeBSD @command{make}). + +Furthermore, parallel runs of those @command{make} implementations will +route standard error from commands that they spawn into their own +standard output, and may remove leading whitespace from output lines. + + @node Comments in Make Rules @section Comments in Make Rules @cindex Comments in @file{Makefile} rules -- cgit v1.2.1