Re: [RFC] Docs: document silent make rules in a new chapter

[Stefano Lattarini]

[dropping address@hidden

I've elaborated on this a little more.  An updated patch is attached;
here is what I squashed in w.r.t. the previous version:

-*-*-*-

diff --git a/ChangeLog b/ChangeLog
index 7feb9c6..27b00cb 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -4,8 +4,9 @@
        * doc/automake.texi (Options): Detailed description of the automake
        option `silent-rules' moved from here ...
        (Silent Make): ... to this new chapter, with its two ...
-       (Tricks For Silencing Make, Automake silent-rules Option): ... new
-       sections (FIXME: to be finished).
+       (Make verbosity, Tricks For Silencing Make,
+       Automake silent-rules Option): ... new sections (FIXME: to be
+       finished).
        (@menu, @detailmenu): Update.
 
 2010-11-14  Ralf Wildenhues  <address@hidden>
diff --git a/doc/automake.texi b/doc/automake.texi
index 3349942..396fb65 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -333,6 +333,7 @@ Conditionals
 
 Silent Make
 
+* Make verbosity::               Make is verbose by default
 * Tricks For Silencing Make::    Standard and generic ways to silence make
 * Automake silent-rules Option:: How Automake can help in silencing make
 
@@ -9632,52 +9633,73 @@ Libtool Sources}).
 @cindex Silent @command{make} rules
 
 @menu
+* Make verbosity::               Make is verbose by default
 * Tricks For Silencing Make::    Standard and generic ways to silence make
 * Automake silent-rules Option:: How Automake can help in silencing make
 @end menu
 
address@hidden Tricks For Silencing Make
address@hidden Standard and generic ways to silence make
-
address@hidden: Maybe a short introduction on how makes violates the
-``silence is golden'' UNIX rule.
-
address@hidden of having a quieter make output in general: warning and
-error messages from make-invoked tools stick out much better, and are
-not drowned in a flood of uninteresting and seldom useful messages.
-This might be very useful from a developer's point of view.
address@hidden Make verbosity
address@hidden Make is verbose by default
+
+Normally, when executing the set of rules associated with a target,
address@hidden prints each rule before it is executed.  This behaviour,
+while having been in place for a long time (and being even mandated by
+POSIX), starkly violates the ``silence is golden'' UNIX principle
+(@emph{FIXME}: what about a link here, maybe
address@hidden://www.faqs.org/docs/artu/ch01s06.html#id2878450} or
address@hidden://catb.org/~esr/writings/taouu/html/ch01s03.html#rule-silence}
+?)
+
+In fact, while such verbosity can theoretically be useful to track bugs
+and understand reasons of failures right away, it also hide warning and
+error messages from make-invoked tools, drowning them in a flood of
+uninteresting and seldom useful messages, and thus allowing them to go
+easily undetected -- very bad!
+
+This problem can be very annoying especially for developers, which usually
+know quite well what's going on under the scenes, and for whom the verbose
+make messages are just noise preventing easily spotting of warning messages
+they might be very interested into.
 
 @emph{TODO}: having an example showing the woes of an overly verbose
 make output might be nice -- especially a real-world (but short!)
 example.
 
address@hidden Tricks For Silencing Make
address@hidden Standard and generic ways to silence make
+
 Here we describe some common idioms/tricks to obtain a quieter make
-output, with relative advantages and drawbacks.
+output, with relative advantages and drawbacks.  In the next section
+(@ref{Automake silent-rules Option}) we'll see how Automake can help
+in this respect.
 
 @itemize @bullet
 
 @item @command{make -s}
 
address@hidden: Explain what it does.
+This simply causes @command{make} not to print @emph{any} rule before
+executing it.
 
 @emph{Pros}: It's easy to use and understand, and it's mandated by
 POSIX.
 
address@hidden: Its output might turn out to be too much terse; in
-case of errors, the user won't be able to easily see what rule or
-command have caused them, or even, in case of tools with poor
-error reporting, what the error was!
address@hidden: Its an ``all or nothing'' strategy: either everything is
+silenced, or nothing is.  Moreover, when this option is used, the
address@hidden output might turn out to be too much terse; in case of
+errors, the user won't be able to easily see what rule or command have
+caused them, or even, in case of tools with poor error reporting, what
+the error was!
 
address@hidden @command{make >/dev/null 2>&1 || make}
address@hidden @command{make >/dev/null || make}
 
-Apparently, this perfectly obeys the ``silence is golden'' rule:
-output reported is done only in case of error, and in that case
-it should be a verbose-enough output to allow an easy determination
-of the error causes and location.
+Apparently, this perfectly obeys the ``silence is golden'' rule: warnings
+from stderr are passed through, output report is done only in case of
+error, and in that case it should be a verbose-enough report to allow an
+easy determination of the error location and causes.
 
-However, calling make two times might hide errors (especially
-intermittent ones), or subtly change the expected semantic of
-the make call (@emph{FIXME}: examples?).
+However, calling make two times might hide errors (especially intermittent
+ones), or subtly change the expected semantic of the make call
+(@emph{FIXME}: examples?).
 
 @item @command{gmake --no-print-directory}
 
@@ -9687,7 +9709,9 @@ This is GNU make specific.
 
 @emph{Cons}: TODO.
 
address@hidden @emph{TODO}: other tricks?
address@hidden @emph{TODO}: other tricks?  Maybe speak about the @code{.SILENT}
+target? @emph{Pros}: More granularity on what to silence; @emph{Cons}:
+no easy way to temporarily override.
 
 @end itemize
 
@@ -9755,9 +9779,9 @@ expansion, which are in turn enabled by 
@option{-Wportability}
 (@pxref{Invoking Automake}).
 
 @vindex @code{AM_V_GEN}
address@hidden FIXME: wouldn't $(AM_V_SILENT) be clearer?  Should we deprecate
address@hidden $(AM_V_at)?  It should be kept for backward-compatibility, of
address@hidden course.
address@hidden FIXME: wouldn't $(AM_V_SILENT) be clearer that $(AM_V_at)?  
Should we
address@hidden deprecate $(AM_V_at) (it should be kept for 
backward-compatibility, of
address@hidden course).
 @vindex @code{AM_V_at}
 @vindex @code{AM_DEFAULT_VERBOSITY}
 To extend the silent mode to your own rules, you have two choices:
@@ -9785,11 +9809,14 @@ foo: foo.in
 
 @end itemize
 
address@hidden:
 Libtool and silent rules: peculiarities?
 
address@hidden:
 Maybe describe in brief the precedent set by the build system
 of the Linux Kernel... Links?
 
address@hidden:
 Tell that @option{--no-print-directory} might still be useful with
 GNU make, if one wants to avoid the ``Entering/Leaving directory ...''
 messages, since this is out the control of Automake.

-*-*-*-

Regards,
    Stefano

From ac5c53d20ece094a90b33d2be4ce5dcb5b34827c Mon Sep 17 00:00:00 2001
From: Stefano Lattarini <address@hidden>
Date: Fri, 12 Nov 2010 20:26:59 +0100
Subject: [PATCH] Docs: document silent make rules in a new chapter.

---
 ChangeLog         |   11 ++
 doc/automake.texi |  290 ++++++++++++++++++++++++++++++++++++++---------------
 2 files changed, 222 insertions(+), 79 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 7595f3b..27b00cb 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2010-11-18  Stefano Lattarini  <address@hidden>
+
+       Docs: document silent make rules in a new dedicated chapter.
+       * doc/automake.texi (Options): Detailed description of the automake
+       option `silent-rules' moved from here ...
+       (Silent Make): ... to this new chapter, with its two ...
+       (Make verbosity, Tricks For Silencing Make,
+       Automake silent-rules Option): ... new sections (FIXME: to be
+       finished).
+       (@menu, @detailmenu): Update.
+
 2010-11-14  Ralf Wildenhues  <address@hidden>
 
        Rebuild menus in the manual.
diff --git a/doc/automake.texi b/doc/automake.texi
index 5a805b3..396fb65 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -117,6 +117,7 @@ section entitled ``GNU Free Documentation License.''
 * Miscellaneous::               Miscellaneous rules
 * Include::                     Including extra files in an Automake template
 * Conditionals::                Conditionals
+* Silencing Make::              Obtain less verbose output from @command{make}
 * Gnits::                       The effect of @option{--gnu} and 
@option{--gnits}
 * Cygnus::                      The effect of @option{--cygnus}
 * Not Enough::                  When Automake is not Enough
@@ -330,6 +331,12 @@ Conditionals
 * Usage of Conditionals::       Declaring conditional content
 * Limits of Conditionals::      Enclosing complete statements
 
+Silent Make
+
+* Make verbosity::               Make is verbose by default
+* Tricks For Silencing Make::    Standard and generic ways to silence make
+* Automake silent-rules Option:: How Automake can help in silencing make
+
 When Automake Isn't Enough
 
 * Extending::                   Adding new rules or overriding existing ones.
@@ -9131,90 +9138,18 @@ letter; it should be omitted for non-alpha releases.
 @cindex Option, @option{silent-rules}
 @opindex silent-rules
 Enable less verbose build rules.  This can be used to let build rules
-output a status line of the form
-
+output a status line of the form:
 @example
-  GEN @var{output-file}
+GEN @var{output-file}
+ CC @var{object-file}
 @end example
-
 @noindent
 instead of printing the command that will be executed to update
address@hidden  It can also silence @command{libtool} output.
-
-To enable less verbose build rules, both the developer and the user
-of the package have to take a number of steps.  The developer needs
-to do either of the following:
-
address@hidden @bullet
address@hidden
-Add the @option{silent-rules} option as argument to @code{AM_INIT_AUTOMAKE}.
address@hidden
-Call the @code{AM_SILENT_RULES} macro from within the @file{configure.ac}
-file.
address@hidden itemize
-
-It is not possible to instead specify @option{silent-rules} in a
address@hidden file.
-
address@hidden default verbosity for silent-rules
-If the developer has done either of the above, then the user of the
-package may influence the verbosity at @command{configure} run time as
-well as at @command{make} run time:
-
address@hidden @bullet
address@hidden
address@hidden --enable-silent-rules
address@hidden --disable-silent-rules
-Passing @option{--enable-silent-rules} to @command{configure} will cause
-build rules to be less verbose; the option @option{--disable-silent-rules}
-is the default and will cause normal verbose output.
address@hidden
address@hidden @code{V}
-At @command{make} run time, the default chosen at @command{configure}
-time may be overridden: @code{make V=1} will produce verbose output,
address@hidden V=0} less verbose output.
address@hidden itemize
-
-For portability to different @command{make} implementations, package authors
-are advised to not set the variable @code{V} inside the @file{Makefile.am}
-file, to allow the user to override the value for subdirectories as well.
-
-The current implementation of this feature relies on a non-POSIX, but in
-practice rather widely supported @file{Makefile} construct of nested
-variable expansion @samp{$(@var{var1}$(V))}.  Do not use the
address@hidden option if your package needs to build with
address@hidden implementations that do not support it.  The
address@hidden option turns off warnings about recursive variable
-expansion, which are in turn enabled by @option{-Wportability}
-(@pxref{Invoking Automake}).
-
address@hidden @code{AM_V_GEN}
address@hidden @code{AM_V_at}
address@hidden @code{AM_DEFAULT_VERBOSITY}
-To extend the silent mode to your own rules, you have two choices:
-
address@hidden @bullet
address@hidden
-You can use the predefined variable @code{AM_V_GEN} as a prefix to
-commands that should output a status line in silent mode, and
address@hidden as a prefix to commands that should not output anything
-in silent mode.  When output is to be verbose, both of these variables
-will expand to the empty string.
address@hidden
-You can add your own variables, so strings of your own choice are shown.
-The following snippet shows how you would define your own equivalent of
address@hidden:
-
address@hidden
-pkg_verbose = $(pkg_verbose_$(V))
-pkg_verbose_ = $(pkg_verbose_$(AM_DEFAULT_VERBOSITY))
-pkg_verbose_0 = @@echo GEN $@@;
-
-foo: foo.in
-        $(pkg_verbose)cp $(srcdir)/foo.in $@@
address@hidden example
address@hidden itemize
address@hidden or to compile @var{object-file}.  It can also
+silence @command{libtool} output.
 
+For more information about how to use, enable, or disable silent
+rules, @pxref{Automake silent-rules Option}.
 
 @item @option{std-options}
 @cindex Options, @option{std-options}
@@ -9689,6 +9624,203 @@ Subdirectories}, @pxref{Conditional Sources}, 
@pxref{Conditional
 Programs}, @pxref{Conditional Libtool Libraries}, @pxref{Conditional
 Libtool Sources}).
 
address@hidden Silencing Make
address@hidden Silencing @command{make}
+
address@hidden Silent @command{make}
address@hidden Silencing @command{make}
address@hidden Silent rules
address@hidden Silent @command{make} rules
+
address@hidden
+* Make verbosity::               Make is verbose by default
+* Tricks For Silencing Make::    Standard and generic ways to silence make
+* Automake silent-rules Option:: How Automake can help in silencing make
address@hidden menu
+
address@hidden Make verbosity
address@hidden Make is verbose by default
+
+Normally, when executing the set of rules associated with a target,
address@hidden prints each rule before it is executed.  This behaviour,
+while having been in place for a long time (and being even mandated by
+POSIX), starkly violates the ``silence is golden'' UNIX principle
+(@emph{FIXME}: what about a link here, maybe
address@hidden://www.faqs.org/docs/artu/ch01s06.html#id2878450} or
address@hidden://catb.org/~esr/writings/taouu/html/ch01s03.html#rule-silence}
+?)
+
+In fact, while such verbosity can theoretically be useful to track bugs
+and understand reasons of failures right away, it also hide warning and
+error messages from make-invoked tools, drowning them in a flood of
+uninteresting and seldom useful messages, and thus allowing them to go
+easily undetected -- very bad!
+
+This problem can be very annoying especially for developers, which usually
+know quite well what's going on under the scenes, and for whom the verbose
+make messages are just noise preventing easily spotting of warning messages
+they might be very interested into.
+
address@hidden: having an example showing the woes of an overly verbose
+make output might be nice -- especially a real-world (but short!)
+example.
+
address@hidden Tricks For Silencing Make
address@hidden Standard and generic ways to silence make
+
+Here we describe some common idioms/tricks to obtain a quieter make
+output, with relative advantages and drawbacks.  In the next section
+(@ref{Automake silent-rules Option}) we'll see how Automake can help
+in this respect.
+
address@hidden @bullet
+
address@hidden @command{make -s}
+
+This simply causes @command{make} not to print @emph{any} rule before
+executing it.
+
address@hidden: It's easy to use and understand, and it's mandated by
+POSIX.
+
address@hidden: Its an ``all or nothing'' strategy: either everything is
+silenced, or nothing is.  Moreover, when this option is used, the
address@hidden output might turn out to be too much terse; in case of
+errors, the user won't be able to easily see what rule or command have
+caused them, or even, in case of tools with poor error reporting, what
+the error was!
+
address@hidden @command{make >/dev/null || make}
+
+Apparently, this perfectly obeys the ``silence is golden'' rule: warnings
+from stderr are passed through, output report is done only in case of
+error, and in that case it should be a verbose-enough report to allow an
+easy determination of the error location and causes.
+
+However, calling make two times might hide errors (especially intermittent
+ones), or subtly change the expected semantic of the make call
+(@emph{FIXME}: examples?).
+
address@hidden @command{gmake --no-print-directory}
+
+This is GNU make specific.
+
address@hidden: TODO.
+
address@hidden: TODO.
+
address@hidden @emph{TODO}: other tricks?  Maybe speak about the @code{.SILENT}
+target? @emph{Pros}: More granularity on what to silence; @emph{Cons}:
+no easy way to temporarily override.
+
address@hidden itemize
+
address@hidden Automake silent-rules Option
address@hidden How Automake can help in silencing make
+
+As we've seen, the tricks and idioms for silencing make described in the
+previous section, while useful from time to time, all have some serious
+drawbacks and limitations.  Automake comes to the rescue!
+
+Problem of silent rules: the investigation of user bug reports might be
+more difficult, since the developer cannot see in its completeness the
+command(s) that caused the failure on the user system.
+
+Simple solutions: do not enable silent rules by default!
+
+To enable less verbose build rules, both the developer and the user of the
+package have to take a number of steps (@emph{FIXME}: this is not strictly
+true if the developer uses address@hidden([yes])}'', but we should
+discourage that).
+
+The developer needs to do either of the following:
+
address@hidden @bullet
address@hidden
+Add the @option{silent-rules} option as argument to @code{AM_INIT_AUTOMAKE}.
address@hidden
+Call the @code{AM_SILENT_RULES} macro from within the @file{configure.ac}
+file.
address@hidden itemize
+
+It is not possible to instead specify @option{silent-rules} in a
address@hidden file.
+
address@hidden default verbosity for silent-rules
+If the developer has done either of the above, then the user of the
+package may influence the verbosity at @command{configure} run time as
+well as at @command{make} run time:
+
address@hidden @bullet
address@hidden
address@hidden --enable-silent-rules
address@hidden --disable-silent-rules
+Passing @option{--enable-silent-rules} to @command{configure} will cause
+build rules to be less verbose; the option @option{--disable-silent-rules}
+is the default and will cause normal verbose output.
address@hidden
address@hidden @code{V}
+At @command{make} run time, the default chosen at @command{configure}
+time may be overridden: @code{make V=1} will produce verbose output,
address@hidden V=0} less verbose output.
address@hidden itemize
+
+For portability to different @command{make} implementations, package authors
+are advised to not set the variable @code{V} inside the @file{Makefile.am}
+file, to allow the user to override the value for subdirectories as well.
+
+The current implementation of this feature relies on a non-POSIX, but in
+practice rather widely supported @file{Makefile} construct of nested
+variable expansion @samp{$(@var{var1}$(V))}.  Do not use the
address@hidden option if your package needs to build with
address@hidden implementations that do not support it.  The
address@hidden option turns off warnings about recursive variable
+expansion, which are in turn enabled by @option{-Wportability}
+(@pxref{Invoking Automake}).
+
address@hidden @code{AM_V_GEN}
address@hidden FIXME: wouldn't $(AM_V_SILENT) be clearer that $(AM_V_at)?  
Should we
address@hidden deprecate $(AM_V_at) (it should be kept for 
backward-compatibility, of
address@hidden course).
address@hidden @code{AM_V_at}
address@hidden @code{AM_DEFAULT_VERBOSITY}
+To extend the silent mode to your own rules, you have two choices:
+
address@hidden @bullet
address@hidden
+You can use the predefined variable @code{AM_V_GEN} as a prefix to
+commands that should output a status line in silent mode, and
address@hidden as a prefix to commands that should not output anything
+in silent mode.  When output is to be verbose, both of these variables
+will expand to the empty string.
address@hidden
+You can add your own variables, so strings of your own choice are shown.
+The following snippet shows how you would define your own equivalent of
address@hidden:
+
address@hidden
+pkg_verbose = $(pkg_verbose_$(V))
+pkg_verbose_ = $(pkg_verbose_$(AM_DEFAULT_VERBOSITY))
+pkg_verbose_0 = @@echo PKG-GEN $@@;
+
+foo: foo.in
+        $(pkg_verbose)cp $(srcdir)/foo.in $@@
address@hidden example
+
address@hidden itemize
+
address@hidden:
+Libtool and silent rules: peculiarities?
+
address@hidden:
+Maybe describe in brief the precedent set by the build system
+of the Linux Kernel... Links?
+
address@hidden:
+Tell that @option{--no-print-directory} might still be useful with
+GNU make, if one wants to avoid the ``Entering/Leaving directory ...''
+messages, since this is out the control of Automake.
+
 @node Gnits
 @chapter The effect of @option{--gnu} and @option{--gnits}
 
-- 
1.7.1