Rename the -O "job" mode to "line" and "make" to "recurse".

8 files changed, 81 insertions, 55 deletions

diff --git a/ChangeLog b/ChangeLog
index 8632e1a..56a3361 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,13 @@
 2013-05-05  Paul Smith  <psmith@gnu.org>
 
+	* makeint.h (OUTPUT_SYNC_LINE, OUTPUT_SYNC_RECURSE): Rename
+	output-sync options "job" to "line" and "make" to "recurse".
+	* main.c (decode_output_sync_flags): Ditto.
+	* job.c (reap_children): Ditto.
+	(start_job_command): Ditto.
+	* make.1: Ditto.
+	* doc/make.texi (Parallel Output): Ditto.
+
 	* job.c (child_out): Write newlines explicitly, and don't do
 	anything if the message is empty.
 	(sync_output): Put working dir messages around stdout AND stderr.
diff --git a/doc/make.texi b/doc/make.texi
index ea58d6e..5a95f0c 100644
--- a/doc/make.texi
+++ b/doc/make.texi
@@ -4131,15 +4131,15 @@ running in parallel, they will communicate so that only one of them is
 generating output at a time.
 
 There are four levels of granularity when synchronizing output,
-specified by giving an argument to the option (e.g.,  @samp{-Ojob} or
-@samp{--output-sync=make}).
+specified by giving an argument to the option (e.g.,  @samp{-Oline} or
+@samp{--output-sync=recurse}).
 
 @table @code
 @item none
 This is the default: all output is sent directly as it is generated and
 no synchronization is performed.
 
-@item job
+@item line
 Output from each individual line of the recipe is grouped and printed
 as soon as that line is complete.  If a recipe consists of multiple
 lines, they may be interspersed with lines from other recipes.
@@ -4149,7 +4149,7 @@ Output from the entire recipe for each target is grouped and printed
 once the target is complete.  This is the default if the
 @code{--output-sync} or @code{-O} option is given with no argument.
 
-@item make
+@item recurse
 Output from each recursive invocation of @code{make} is grouped and
 printed once the recursive invocation is complete.
 
@@ -4158,25 +4158,50 @@ printed once the recursive invocation is complete.
 Regardless of the mode chosen, the total build time will be the same.
 The only difference is in how the output appears.
 
-The @samp{make} mode provides the most comprehensive grouping,
-allowing output from all targets built by a given makefile to appear
-together.  However, there will be long interludes during the build
-where no output appears while a recursive @code{make} is running,
-followed by a burst of output.  This mode is best for builds being
-performed in the background, where the output will be examined later.
-
-The @samp{job} mode is mainly useful for front-ends that may be
-watching the output of @code{make} and looking for certain generated
-output to determine when recipes are started and completed.
-
-You should be aware that some programs may act differently when they
-determine they're writing output to a terminal versus a file
-(typically described as ``interactive'' vs. ``non-interactive''
-modes).  If your makefile invokes a program like this then using the
-output synchronization options will cause the program to believe it's
-running in ``non-interactive'' mode even when it's writing to the
-terminal.  Of course, invoking @code{make} with output redirected to a
-file will elicit the same behavior.
+The @samp{target} and @samp{recurse} modes both collect the output of
+the entire recipe of a target and display it uninterrupted when the
+recipe completes.  The difference between them is in how recipes that
+contain recursive invocations of @code{make} are treated
+(@pxref{Recursion, ,Recursive Use of @code{make}}).  For all recipes
+which have no recursive lines, the @samp{target} and @samp{recurse}
+modes behave identically.
+
+If the @samp{recurse} mode is chosen, recipes that contain recursive
+@code{make} invocations are treated the same as other targets: the
+output from the recipe, including the output from the recursive
+@code{make}, is saved and printed after the entire recipe is complete.
+This ensures output from all the targets built by a given recursive
+@code{make} instance are grouped together, which may make the output
+easier to understand.  However it also leads to long periods of time
+during the build where no output is seen, followed by large bursts of
+output.  If you are not watching the build as it proceeds, but instead
+viewing a log of the build after the fact, this may be the best option
+for you.
+
+If you are watching the output, the long gaps of quiet during the
+build can be frustrating.  The @samp{target} output synchronization
+mode detects when @code{make} is going to be invoked recursively,
+using the standard methods, and it will not synchronize the output of
+those lines.  The recursive @code{make} will perform the
+synchronization for its targets and the output from each will be
+displayed immediately when it completes.  Be aware that output from
+recursive lines of the recipe are not synchronized (for example if
+the recursive line prints a message before running @code{make}, that
+message will not be synchronized).
+
+The @samp{line} mode can be useful for front-ends that are watching
+the output of @code{make} to track when recipes are started and
+completed.
+
+Some programs invoked by @code{make} may behave differently if they
+determine they're writing output to a terminal versus a file (often
+described as ``interactive'' vs. ``non-interactive'' modes).  For
+example, many programs that can display colorized output often will
+not do so if they determine they are not displaying on a terminal.  If
+your makefile invokes a program like this then using the output
+synchronization options will cause the program to believe it's running
+in ``non-interactive'' mode even when it's ultimately writing to the
+terminal.
 
 @node Parallel Input,  , Parallel Output, Parallel
 @subsection Input During Parallel Execution
@@ -8702,18 +8727,10 @@ uninterrupted sequence.  This option is only useful when using the
 will be displayed as it is generated by the recipes.@refill
 
 With no type or the type @samp{target}, output from the entire recipe
-of each target is grouped together.  With the type @samp{job}, output
-from each job in the recipe is grouped together.  With the type
-@samp{make}, the output from an entire 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
-entire recursive make has completed (this does not increase the total
-build time, though).  In general @samp{target} mode is useful when
-watching the output while make runs, and @samp{make} mode is useful
-when running a complex parallel build in the background and checking
-its output afterwards.  The @samp{job} mode may be helpful for tools
-which watch the output to determine when recipes have started or
-stopped.
+of each target is grouped together.  With the type @samp{line}, output
+from each line in the recipe is grouped together.  With the type
+@samp{recurse}, the output from an entire recursive make is grouped
+together.  @xref{Parallel Output, ,Output During Parallel Execution}.
 
 @item -q
 @cindex @code{-q}
diff --git a/job.c b/job.c
index 726cca8..a40eb41 100644
--- a/job.c
+++ b/job.c
@@ -1141,7 +1141,7 @@ reap_children (int block, int err)
 #ifdef OUTPUT_SYNC
                   /* If we're sync'ing per line, write the previous line's
                      output before starting the next one.  */
-                  if (output_sync == OUTPUT_SYNC_JOB)
+                  if (output_sync == OUTPUT_SYNC_LINE)
                     sync_output (c);
 #endif
                   /* Check again whether to start remotely.
@@ -1518,7 +1518,7 @@ start_job_command (struct child *child)
   /* Are we going to synchronize this command's output?  Do so if either we're
      in SYNC_MAKE mode or this command is not recursive.  We'll also check
      output_sync separately below in case it changes due to error.  */
-  sync_cmd = output_sync && (output_sync == OUTPUT_SYNC_MAKE
+  sync_cmd = output_sync && (output_sync == OUTPUT_SYNC_RECURSE
                              || !(flags & COMMANDS_RECURSE));
 
 #ifdef OUTPUT_SYNC
diff --git a/main.c b/main.c
index be3d190..f954b3c 100644
--- a/main.c
+++ b/main.c
@@ -517,9 +517,9 @@ int second_expansion;
 
 int one_shell;
 
-/* Either OUTPUT_SYNC_TARGET or OUTPUT_SYNC_MAKE if the "--output-sync" option
-   was given.  This attempts to synchronize the output of parallel jobs such
-   that the results of each job stay together.  */
+/* One of OUTPUT_SYNC_* if the "--output-sync" option was given.  This
+   attempts to synchronize the output of parallel jobs such that the results
+   of each job stay together.  */
 
 int output_sync;
 
@@ -697,12 +697,12 @@ decode_output_sync_flags (void)
 
       if (streq (p, "none"))
         output_sync = OUTPUT_SYNC_NONE;
-      else if (streq (p, "job"))
-        output_sync = OUTPUT_SYNC_JOB;
+      else if (streq (p, "line"))
+        output_sync = OUTPUT_SYNC_LINE;
       else if (streq (p, "target"))
         output_sync = OUTPUT_SYNC_TARGET;
-      else if (streq (p, "make"))
-        output_sync = OUTPUT_SYNC_MAKE;
+      else if (streq (p, "recurse"))
+        output_sync = OUTPUT_SYNC_RECURSE;
       else
         fatal (NILF, _("unknown output-sync type '%s'"), p);
     }
diff --git a/make.1 b/make.1
index 326bf86..ad86db3 100644
--- a/make.1
+++ b/make.1
@@ -230,12 +230,12 @@ is not specified or is
 the output from the entire recipe for each target is grouped together.  If
 .I type
 is
-.B job
-the output from each job within a recipe is grouped together.
+.B line
+the output from each line within a recipe is grouped together.
 If
 .I type
 is
-.B make
+.B recurse
 output from an entire recursive make is grouped together.  If
 .I type
 is
diff --git a/makeint.h b/makeint.h
index 6cce848..9dd22ce 100644
--- a/makeint.h
+++ b/makeint.h
@@ -543,10 +543,10 @@ int strncasecmp (const char *s1, const char *s2, int n);
 # define OUTPUT_SYNC
 #endif
 
-#define OUTPUT_SYNC_NONE   0
-#define OUTPUT_SYNC_JOB    1
-#define OUTPUT_SYNC_TARGET 2
-#define OUTPUT_SYNC_MAKE   3
+#define OUTPUT_SYNC_NONE    0
+#define OUTPUT_SYNC_LINE    1
+#define OUTPUT_SYNC_TARGET  2
+#define OUTPUT_SYNC_RECURSE 3
 
 extern const gmk_floc *reading_file;
 extern const gmk_floc **expanding_var;
diff --git a/tests/ChangeLog b/tests/ChangeLog
index 4d11706..d98e938 100644
--- a/tests/ChangeLog
+++ b/tests/ChangeLog
@@ -3,6 +3,7 @@
 	* scripts/features/output-sync (output_sync_set): Remove
 	extraneous enter/leave lines, which are no longer printed.
 	Add tests for syncing command line printing.
+	(output_sync_set): Rename options: "job"->"line"; "make"->"recurse"
 
 2013-05-04  Paul Smith  <psmith@gnu.org>
 
diff --git a/tests/scripts/features/output-sync b/tests/scripts/features/output-sync
index e7edfce..d760885 100644
--- a/tests/scripts/features/output-sync
+++ b/tests/scripts/features/output-sync
@@ -125,7 +125,7 @@ all: make-foo make-bar
 make-foo: ; \$(MAKE) -C foo
 
 make-bar: ; \$(MAKE) -C bar!,
-              '-j -Omake',
+              '-j -Orecurse',
 "#MAKEPATH# -C foo
 #MAKE#[1]: Entering directory '#PWD#/foo'
 foo: start
@@ -208,7 +208,7 @@ all: make-foo make-bar
 make-foo: ; \$(MAKE) -C foo foo-job
 
 make-bar: ; $sleep_command 1 ; \$(MAKE) -C bar bar-job!,
-              '-j --output-sync=job',
+              '-j --output-sync=line',
 "#MAKEPATH# -C foo foo-job
 $sleep_command 1 ; #MAKEPATH# -C bar bar-job
 #MAKE#[1]: Entering directory '#PWD#/foo'
@@ -234,7 +234,7 @@ all:
 \t\@echo foo
 \t\@+echo bar
 !,
-              '-j -Ojob', "foo\nbar\n");
+              '-j -Oline', "foo\nbar\n");
 
 run_make_test(undef, '-j -Otarget', "foo\nbar\n");
 
@@ -244,7 +244,7 @@ all:
 \t\@echo foobar
 \ttrue
 !,
-              '-j -Ojob', "foobar\ntrue\n");
+              '-j -Oline', "foobar\ntrue\n");
 
 run_make_test(undef, '-j -Otarget', "foobar\ntrue\n");