Initial patch for output synchronization. See Savannah bug #33138.

Based on work by David Boyce <David.S.Boyce@gmail.com>.

1 files changed, 24 insertions, 3 deletions

diff --git a/doc/make.texi b/doc/make.texi
index dffa14d..1a760e1 100644
--- a/doc/make.texi
+++ b/doc/make.texi
@@ -4057,9 +4057,12 @@ If there is nothing looking like an integer after the @samp{-j} option,
 there is no limit on the number of job slots.  The default number of job
 slots is one, which means serial execution (one thing at a time).
 
-One unpleasant consequence of running several recipes simultaneously is
-that output generated by the recipes appears whenever each recipe
-sends it, so messages from different recipes may be interspersed.
+One consequence of running several recipes simultaneously is that by
+default, output from each recipe appears as soon as it is generated,
+with the result that messages from different recipes may be interspersed.
+This may create problems in interpreting output. If the @samp{-P} option
+is used, however, recipes will save their output until completion and
+then take turns writing it, with a more coherent result.
 
 Another problem is that two processes cannot both take input from the
 same device; so to make sure that only one recipe tries to take input
@@ -8612,6 +8615,24 @@ The data base output contains file name and line number information for
 recipe and variable definitions, so it can be a useful debugging tool
 in complex environments.
 
+@item -P
+@cindex @code{-P}
+@itemx --parallel-sync
+@cindex @code{--parallel-sync}
+@cindex parallel recipe execution, output
+When jobs are running in parallel under @samp{--jobs}, the output of
+each job is held until the job is complete thus ensuring that the output
+of each recipe is grouped together.
+
+With no argument or the argument @samp{1}, messages from each job in
+recursive makes are grouped together. With the argument @samp{2}, the
+complete output from any recursive make is grouped together. The latter
+achieves better grouping of output from related jobs, but causes longer
+delay, since messages do not appear until the recursive make has
+completed. Therefore @samp{-P} is more useful when watching the output
+while make runs, and @samp{-P2} is better suited when running a complex
+parallel build in the background and checking its output afterwards.
+
 @item -q
 @cindex @code{-q}
 @itemx --question