[PATCH] {maint} Docs: better documentation for silent make rules.

[Stefano Lattarini]

Hi Eric, and thanks for the review.

On Saturday 04 December 2010, Eric Blake wrote:
> On 12/04/2010 01:48 PM, Stefano Lattarini wrote:
> > Hello automakers.
> > 
> > I've worked some more on this, and I think I've now managed to find
> > the proper layout for the new chapter, and a decently complete list
> > of topics to be touched.  There are still some TODOs and rough edges,
> > but I think the patch is approaching to a state acceptable for
> > application.
> > 
> > Attached are the new version of the patch, plus the diffs from the
> > older version.
> > 
> > Any feedback before I attempt the final respin would be really
> > appreciated.
> 
> > address@hidden default verbosity for silent-rules
> > +Note that silent rules are @emph{enabled} by default; the user have to
> 
> disabled by default
> 
Oops *blush*!  Thank for catching this; it's fixed now.

> > +enable them explicitly at either make at either @command{configure} run
> > +time or at @command{make} run time.
> > +
> 
> One thing that might also be worth mentioning is that a user can set
> their own preferences via a config.site file
>
Good idea.  IMO, this also requires a new testcase, which I've added to
the respinned patch.

> (for example, I have enable_silent_rules=yes as one of the lines in my
> /usr/local/share/config.site).
> 
I'd prefer something like `enable_silent_rules=${enable_silent_rules-yes}'
which allows disabling of silent rules from the configure command line.

-*-*-

I've also made many fixings, rewordings, improvements and extensions
w.r.t. the previous version of the patch.  Attached is what I've
squashed in the previous version, plus the amended patch.  If there
are no objections, I'd like to consider this the final version of the
patch, and apply it to maint.  Further improvements can still be done
later.

OK to apply?

Regards,
    Stefano

From 3ce71c7f997b101fe94229cd9e273d96c5ad9032 Mon Sep 17 00:00:00 2001
From: Stefano Lattarini <address@hidden>
Date: Fri, 12 Nov 2010 20:26:59 +0100
Subject: [PATCH] Docs: better documentation for silent make rules.

Docs: better documentation for silent make rules.
* doc/automake.texi (Options): Detailed description of the
automake option `silent-rules' moved from here ...
(Silent Make): ... into this new chapter, expanded, improved,
and subdivided into ...
(Make verbosity, Tricks For Silencing Make,
Automake silent-rules Option): ... these new sections.
(@menu, @detailmenu): Update.
* tests/silent-configsite.test: New test, checking that the
user can control default mode of silent-rules from config.site,
as is documented in the manual.
* tests/Makefile.am (TESTS): Updated.
---
 ChangeLog                    |   16 ++
 doc/automake.texi            |  372 +++++++++++++++++++++++++++++++++---------
 tests/Makefile.am            |    1 +
 tests/Makefile.in            |    1 +
 tests/silent-configsite.test |   87 ++++++++++
 5 files changed, 398 insertions(+), 79 deletions(-)
 create mode 100755 tests/silent-configsite.test

diff --git a/ChangeLog b/ChangeLog
index e8864f1..3007a76 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,19 @@
+2010-12-05  Stefano Lattarini  <address@hidden>
+
+       Docs: better documentation for silent make rules.
+       * doc/automake.texi (Options): Detailed description of the
+       automake option `silent-rules' moved from here ...
+       (Silent Make): ... to this new chapter, expanded, improved,
+       and complemented with ...
+       (Make verbosity, Tricks For Silencing Make,
+       Automake silent-rules Option): ... these two new introductory
+       sections.
+       (@menu, @detailmenu): Update.
+       * tests/silent-configsite.test: New test, checking that the
+       user can control default mode of silent-rules from config.site,
+       as is documented in the manual.
+       * tests/Makefile.am (TESTS): Updated.
+
 2010-11-25  Stefano Lattarini  <address@hidden>
 
        Fix spurious failures in `silent*.test' for $CC != gcc
diff --git a/doc/automake.texi b/doc/automake.texi
index 5a805b3..d558909 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
 
+Silencing 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 status lines 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,285 @@ 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:
address@hidden more information, see
address@hidden://catb.org/~esr/writings/taouu/html/ch01s03.html#rule-silence}
+and @uref{http://catb.org/~esr/writings/taoup/html/ch11s09.html}.}
+
address@hidden
+When a program has nothing interesting or surprising to say, it should
+say nothing.  Well-behaved Unix programs do their jobs unobtrusively,
+with a minimum of fuss and bother.  Silence is golden.
address@hidden quotation
+
+In fact, while such verbosity of @command{make} can theoretically be
+useful to track bugs and understand reasons of failures right away, it
+can also hide warning and error messages from @command{make}-invoked
+tools, drowning them in a flood of uninteresting and seldom useful
+messages, and thus allowing them to go easily undetected --- which,
+needless to say, is a Very Bad Thing.
+
+This problem can be very annoying especially for developers, who usually
+know quite well what's going on behind the scenes, and thus come to
+consider the verbose @command{make} messages just as noise preventing
+them to easily spot warning messages they might be very interested into.
+
address@hidden TODO: having an example showing the woes of an overly verbose 
make
address@hidden TODO: output might be nice -- especially a real-world (but 
short!)
address@hidden TODO: 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 their 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. 
+
+The @option{-s} flag is mandated by POSIX, universally supported, and
+its purpose and function are easy to understand.
+
+But it also has its serious limitations too.  First of all, it embodies
+an ``all or nothing'' strategy, i.e., either everything is silenced, or
+nothing is; this lack of granularity can sometimes be a fatal flaw.
+Moreover, when the @option{-s} flag is used, the @command{make} 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 errors were!
+
address@hidden @command{make >/dev/null || make}
+
+Apparently, this perfectly obeys the ``silence is golden'' rule: warnings
+from stderr are passed through, output reporting is done only in case of
+error, and in that case it should provide a verbose-enough report to allow
+an easy determination of the error location and causes.
+
+However, calling @command{make} two times in a row might hide errors
+(especially intermittent ones), or subtly change the expected semantic
+of the @command{make} calls --- things these which can clearly make
+debugging and error assessment very difficult.
+
address@hidden @command{make --no-print-directory}
+
+This is GNU @command{make} specific.  When called with the
address@hidden option, GNU @command{make} will disable
+printing of the working directory by invoked address@hidden (the
+well-known ``Entering/Leaving directory ...'' messages).  This helps to
+decrease the verbosity of the output, but experience has shown that it
+can also often render debugging considerably harder in projects using
+deeply-nested @command{make} recursion.
+
+As an aside, notice that the @option{--no-print-directory} option is
+automatically activated if the @option{-s} flag is used.
+
address@hidden TODO: Other tricks?
address@hidden TODO: Maybe speak about the @code{.SILENT} target?
address@hidden TODO:  - Pros: More granularity on what to silence.
address@hidden TODO:  - 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 @command{make} described
+in the previous section, while useful from time to time, all have some
+serious drawbacks and limitations.  That's why automake provides support
+for a more advanced and flexible way of obtaining quieter output from
address@hidden output: the @option{silent-rules} mode.
+
+To give the gist of how @option{silent-rules} works, here is a simple
+comparison between a typical @command{make} output (where silent rules
+are obviously disabled) and one with silent rules enabled:
+
address@hidden
+% @kbd{cat configure.ac}
+AC_INIT([foo], [1.0])
+AM_INIT_AUTOMAKE
+# This will allow the user to request a quieter make output
+AM_SILENT_RULES
+AC_PROG_CC
+AC_PROG_LIBTOOL
+AC_CONFIG_FILES([Makefile])
+AC_OUTPUT
+% @kbd{cat Makefile.am}
+bin_PROGRAMS = bar
+lib_LTLIBRARIES = libfoo.la
+% @kbd{aclocal && autoconf && automake}
+% @kbd{./configure}
+checking for a BSD-compatible install... /usr/bin/install -c
+checking whether build environment is sane... yes
+...
+configure: creating ./config.status
+config.status: creating Makefile
+config.status: executing depfiles commands
+config.status: executing libtool commands
+% @kbd{make # default verbosity: will be awfully verbose}
+/bin/sh ./libtool --tag=CC --mode=compile gcc ... -DLT_OBJDIR=\".libs/\"
+  -I. -g -O2 -MT libfoo.lo -MD -MP -MF .deps/libfoo.Tpo -c -o libfoo.lo
+  libfoo.c
+libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
+  -I. -g -O2 -MT libfoo.lo -MD -MP -MF .deps/libfoo.Tpo -c libfoo.c
+  -fPIC -DPIC -o .libs/libfoo.o
+libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
+  -I. -g -O2 -MT libfoo.lo -MD -MP -MF .deps/libfoo.Tpo -c libfoo.c
+  -o libfoo.o >/dev/null 2>&1
+mv -f .deps/libfoo.Tpo .deps/libfoo.Plo
+/bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libfoo.la libfoo.lo
+libtool: link: gcc -shared .libs/libfoo.o -Wl,-soname -Wl,libfoo.so.0
+  -o .libs/libfoo.so.0.0.0
+libtool: link: (cd ".libs" && rm -f "libfoo.so.0"
+  && ln -s "libfoo.so.0.0.0" "libfoo.so.0")
+libtool: link: (cd ".libs" && rm -f "libfoo.so"
+  && ln -s "libfoo.so.0.0.0" "libfoo.so")
+libtool: link: ar cru .libs/libfoo.a libfoo.o
+libtool: link: ranlib .libs/libfoo.a
+libtool: link: ( cd ".libs" && rm -f "libfoo.la"
+  && ln -s "../libfoo.la" "libfoo.la" )
+gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\" -I. -g -O2
+  -MT bar.o -MD -MP -MF .deps/bar.Tpo -c -o bar.o bar.c
+mv -f .deps/bar.Tpo .deps/bar.Po
+/bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o bar bar.o
+libtool: link: gcc -g -O2 -o bar bar.o
+% @kbd{make clean}
+% @kbd{make V=0 # silent rules enabled: will be very quiet}
+  CC     libfoo.lo
+  CCLD   libfoo.la
+  CC     bar.o
+  CCLD   bar
address@hidden example
+
address@hidden silent-rules and libtool
+By the way, the example above shows how in projects using @command{libtool}
+the use of silent rules automatically enables the @option{--silent} option
+of @command{libtool}.
+
address@hidden TODO: Maybe describe in brief the precedent set by the build
address@hidden system of the Linux Kernel... Links anyone?
+
+To enable the use of @option{silent-rules} in his package, a 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.
+
+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}
+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
+
address@hidden default verbosity for silent-rules
+Note that silent rules are @emph{disabled} by default; the user must
+enable them explicitly at either @command{configure} run time or at
address@hidden run time.  We think that this is a good policy, since
+it provides the casual user with enough information to prepare a good
+bug report in case anything breaks.
+
+Still, notwithstanding the rationales above, a developer who wants to
+make silent rules enabled by default in his own package can do so by
+adding a @samp{yes} argument to the @code{AM_SILENT_RULES} call in
address@hidden  We advise against this approach, though.
+
+Users who prefer to have silent rules enabled by default can edit their
address@hidden file to make the variable @code{enable_silent_rules}
+default to @samp{yes}.  This should still allow disabling silent rules
+at @command{configure} time (and obviously also at @command{make} time).
+
address@hidden FIXME: there's really a need to specify this explicitly?
+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 PKG-GEN $@@;
+
+foo: foo.in
+        $(pkg_verbose)cp $(srcdir)/foo.in $@@
address@hidden example
+
address@hidden itemize
+
+As a final note, observe that, even when silent rules are enabled,
+the @option{--no-print-directory} option is still required with GNU
address@hidden if the ``Entering/Leaving directory ...'' messages
+are to be disabled.
+
 @node Gnits
 @chapter The effect of @option{--gnu} and @option{--gnits}
 
diff --git a/tests/Makefile.am b/tests/Makefile.am
index dab04e3..dfc3649 100644
--- a/tests/Makefile.am
+++ b/tests/Makefile.am
@@ -644,6 +644,7 @@ silent-lex-gcc.test \
 silent-lex-generic.test \
 silent-yacc-gcc.test \
 silent-yacc-generic.test \
+silent-configsite.test \
 sinclude.test \
 srcsub.test \
 srcsub2.test \
diff --git a/tests/Makefile.in b/tests/Makefile.in
index de21f43..c9c48cc 100644
--- a/tests/Makefile.in
+++ b/tests/Makefile.in
@@ -911,6 +911,7 @@ silent-lex-gcc.test \
 silent-lex-generic.test \
 silent-yacc-gcc.test \
 silent-yacc-generic.test \
+silent-configsite.test \
 sinclude.test \
 srcsub.test \
 srcsub2.test \
diff --git a/tests/silent-configsite.test b/tests/silent-configsite.test
new file mode 100755
index 0000000..a383d2d
--- /dev/null
+++ b/tests/silent-configsite.test
@@ -0,0 +1,87 @@
+#!/bin/sh
+# Copyright (C) 2010 Free Software Foundation, Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# Check that the user can control default mode of silent-rules
+# from config.site, and that this default can be overridden from
+# either the ./configure or make command line.
+
+. ./defs || Exit 1
+
+set -e
+
+cat >> configure.in <<'EOF'
+AM_SILENT_RULES
+AC_OUTPUT
+EOF
+
+cat > Makefile.am <<'EOF'
+.PHONY: test-silent test-nosilent
+test-silent:
+       test x'$(AM_DEFAULT_VERBOSITY)' = x'0'
+test-nosilent:
+       test x'$(AM_DEFAULT_VERBOSITY)' = x'1'
+EOF
+
+# Calling it once should be enough, since the list of macros invoked
+# by configure.in don't change (even if their arguments do).
+$ACLOCAL
+
+unset enable_silent_rules || :
+
+: 'No explicit default in configure.in, enable by default in config.site'
+
+$AUTOCONF
+$AUTOMAKE --add-missing
+echo "enable_silent_rules=\${enable_silent_rules-yes}" > config.site
+CONFIG_SITE=./config.site ./configure
+$MAKE test-silent
+$MAKE distclean
+# Command line should win over default values in config.site.
+CONFIG_SITE=./config.site ./configure --disable-silent-rules
+$MAKE test-nosilent
+$MAKE distclean
+
+: 'Disable by default in configure.in, enable by default in config.site'
+
+sed 's/^AM_SILENT_RULES/&([no])/' configure.in > configure.tmp
+mv -f configure.tmp configure.in
+$AUTOCONF
+$AUTOMAKE --add-missing
+echo "enable_silent_rules=\${enable_silent_rules-yes}" > config.site
+CONFIG_SITE=./config.site ./configure
+$MAKE test-silent
+# Command line should win over default values in config.site.
+$MAKE distclean
+CONFIG_SITE=./config.site ./configure --disable-silent-rules
+$MAKE test-nosilent
+$MAKE distclean
+
+: 'Enable by default in configure.in, disable by default in config.site'
+
+sed 's/^AM_SILENT_RULES/&([yes])/' configure.in > configure.tmp
+mv -f configure.tmp configure.in
+$AUTOCONF
+$AUTOMAKE --add-missing
+echo "enable_silent_rules=\${enable_silent_rules-no}" > config.site
+CONFIG_SITE=./config.site ./configure
+$MAKE test-nosilent
+$MAKE distclean
+# Command line should win over default values in config.site.
+CONFIG_SITE=./config.site ./configure --enable-silent-rules
+$MAKE test-silent
+$MAKE distclean
+
+:
-- 
1.7.1

From fe06194cc3f733690585e3f5ff31b4edaddae169 Mon Sep 17 00:00:00 2001
From: Stefano Lattarini <address@hidden>
Date: Sun, 5 Dec 2010 11:10:18 +0100
Subject: [PATCH] SquashMe

---
 ChangeLog                    |   17 ++++--
 doc/automake.texi            |  135 ++++++++++++++++++++++++++++++------------
 tests/Makefile.am            |    1 +
 tests/Makefile.in            |    1 +
 tests/silent-configsite.test |   87 +++++++++++++++++++++++++++
 5 files changed, 197 insertions(+), 44 deletions(-)
 create mode 100755 tests/silent-configsite.test

diff --git a/ChangeLog b/ChangeLog
index 5ca9fbb..3007a76 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,13 +1,18 @@
-2010-12-04  Stefano Lattarini  <address@hidden>
+2010-12-05  Stefano Lattarini  <address@hidden>
 
        Docs: better documentation for silent make rules.
-       * doc/automake.texi (Options): Detailed description of the automake
-       option `silent-rules' moved from here ...
-       (Silent Make): ... to this new chapter, with its two ...
+       * doc/automake.texi (Options): Detailed description of the
+       automake option `silent-rules' moved from here ...
+       (Silent Make): ... to this new chapter, expanded, improved,
+       and complemented with ...
        (Make verbosity, Tricks For Silencing Make,
-       Automake silent-rules Option): ... new sections (FIXME: to be
-       finished).
+       Automake silent-rules Option): ... these two new introductory
+       sections.
        (@menu, @detailmenu): Update.
+       * tests/silent-configsite.test: New test, checking that the
+       user can control default mode of silent-rules from config.site,
+       as is documented in the manual.
+       * tests/Makefile.am (TESTS): Updated.
 
 2010-11-25  Stefano Lattarini  <address@hidden>
 
diff --git a/doc/automake.texi b/doc/automake.texi
index 27ad810..d558909 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -331,7 +331,7 @@ Conditionals
 * Usage of Conditionals::       Declaring conditional content
 * Limits of Conditionals::      Enclosing complete statements
 
-Silent Make
+Silencing Make
 
 * Make verbosity::               Make is verbose by default
 * Tricks For Silencing Make::    Standard and generic ways to silence make
@@ -9138,7 +9138,7 @@ 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 status lines of the form:
 @example
 GEN @var{output-file}
  CC @var{object-file}
@@ -9662,10 +9662,10 @@ tools, drowning them in a flood of uninteresting and 
seldom useful
 messages, and thus allowing them to go easily undetected --- which,
 needless to say, is a Very Bad Thing.
 
-This problem can be very annoying especially for developers, which usually
-know quite well what's going on behind the scenes, and for whom the verbose
-make messages are just noise preventing easily spotting of warning messages
-they might be very interested into.
+This problem can be very annoying especially for developers, who usually
+know quite well what's going on behind the scenes, and thus come to
+consider the verbose @command{make} messages just as noise preventing
+them to easily spot warning messages they might be very interested into.
 
 @c TODO: having an example showing the woes of an overly verbose make
 @c TODO: output might be nice -- especially a real-world (but short!)
@@ -9693,9 +9693,9 @@ But it also has its serious limitations too.  First of 
all, it embodies
 an ``all or nothing'' strategy, i.e., either everything is silenced, or
 nothing is; this lack of granularity can sometimes be a fatal flaw.
 Moreover, when the @option{-s} flag is used, the @command{make} output
-might turn out to be too much terse; in case of error, the user won't
-be able to easily see what rule or command have caused it, or even,
-in case of tools with poor error reporting, what the error was!
+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 errors were!
 
 @item @command{make >/dev/null || make}
 
@@ -9716,8 +9716,8 @@ This is GNU @command{make} specific.  When called with the
 printing of the working directory by invoked address@hidden (the
 well-known ``Entering/Leaving directory ...'' messages).  This helps to
 decrease the verbosity of the output, but experience has shown that it
-can also often render debugging considerably harder in projects that
-use deeply-nested @command{make} recursion.
+can also often render debugging considerably harder in projects using
+deeply-nested @command{make} recursion.
 
 As an aside, notice that the @option{--no-print-directory} option is
 automatically activated if the @option{-s} flag is used.
@@ -9732,24 +9732,80 @@ automatically activated if the @option{-s} flag is used.
 @node Automake silent-rules Option
 @section 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.  That's why automake provides support for
-a more advanced and flexible way of obtaining quieter output from
+As we've seen, the tricks and idioms for silencing @command{make} described
+in the previous section, while useful from time to time, all have some
+serious drawbacks and limitations.  That's why automake provides support
+for a more advanced and flexible way of obtaining quieter output from
 @command{make} output: the @option{silent-rules} mode.
 
address@hidden: Explain how output of @command{make} with silent rules
-enabled differs from usual @command{make} output.
+To give the gist of how @option{silent-rules} works, here is a simple
+comparison between a typical @command{make} output (where silent rules
+are obviously disabled) and one with silent rules enabled:
 
address@hidden: Give some examples of @command{make} outputs with silent
-rules respectively enabled and disabled.
-
address@hidden silent-rules and libtools
address@hidden: Tell that libtool is automatically used in ``silent mode''
-when @option{silent-rules} are activated.
-
address@hidden: Maybe describe in brief the precedent set by the build
-system of the Linux Kernel... Links anyone?
address@hidden
+% @kbd{cat configure.ac}
+AC_INIT([foo], [1.0])
+AM_INIT_AUTOMAKE
+# This will allow the user to request a quieter make output
+AM_SILENT_RULES
+AC_PROG_CC
+AC_PROG_LIBTOOL
+AC_CONFIG_FILES([Makefile])
+AC_OUTPUT
+% @kbd{cat Makefile.am}
+bin_PROGRAMS = bar
+lib_LTLIBRARIES = libfoo.la
+% @kbd{aclocal && autoconf && automake}
+% @kbd{./configure}
+checking for a BSD-compatible install... /usr/bin/install -c
+checking whether build environment is sane... yes
+...
+configure: creating ./config.status
+config.status: creating Makefile
+config.status: executing depfiles commands
+config.status: executing libtool commands
+% @kbd{make # default verbosity: will be awfully verbose}
+/bin/sh ./libtool --tag=CC --mode=compile gcc ... -DLT_OBJDIR=\".libs/\"
+  -I. -g -O2 -MT libfoo.lo -MD -MP -MF .deps/libfoo.Tpo -c -o libfoo.lo
+  libfoo.c
+libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
+  -I. -g -O2 -MT libfoo.lo -MD -MP -MF .deps/libfoo.Tpo -c libfoo.c
+  -fPIC -DPIC -o .libs/libfoo.o
+libtool: compile: gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\"
+  -I. -g -O2 -MT libfoo.lo -MD -MP -MF .deps/libfoo.Tpo -c libfoo.c
+  -o libfoo.o >/dev/null 2>&1
+mv -f .deps/libfoo.Tpo .deps/libfoo.Plo
+/bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o libfoo.la libfoo.lo
+libtool: link: gcc -shared .libs/libfoo.o -Wl,-soname -Wl,libfoo.so.0
+  -o .libs/libfoo.so.0.0.0
+libtool: link: (cd ".libs" && rm -f "libfoo.so.0"
+  && ln -s "libfoo.so.0.0.0" "libfoo.so.0")
+libtool: link: (cd ".libs" && rm -f "libfoo.so"
+  && ln -s "libfoo.so.0.0.0" "libfoo.so")
+libtool: link: ar cru .libs/libfoo.a libfoo.o
+libtool: link: ranlib .libs/libfoo.a
+libtool: link: ( cd ".libs" && rm -f "libfoo.la"
+  && ln -s "../libfoo.la" "libfoo.la" )
+gcc -DPACKAGE_NAME=\"foo\" ... -DLT_OBJDIR=\".libs/\" -I. -g -O2
+  -MT bar.o -MD -MP -MF .deps/bar.Tpo -c -o bar.o bar.c
+mv -f .deps/bar.Tpo .deps/bar.Po
+/bin/sh ./libtool --tag=CC --mode=link gcc -g -O2 -o bar bar.o
+libtool: link: gcc -g -O2 -o bar bar.o
+% @kbd{make clean}
+% @kbd{make V=0 # silent rules enabled: will be very quiet}
+  CC     libfoo.lo
+  CCLD   libfoo.la
+  CC     bar.o
+  CCLD   bar
address@hidden example
+
address@hidden silent-rules and libtool
+By the way, the example above shows how in projects using @command{libtool}
+the use of silent rules automatically enables the @option{--silent} option
+of @command{libtool}.
+
address@hidden TODO: Maybe describe in brief the precedent set by the build
address@hidden system of the Linux Kernel... Links anyone?
 
 To enable the use of @option{silent-rules} in his package, a developer
 needs to do either of the following:
@@ -9784,18 +9840,21 @@ time may be overridden: @code{make V=1} will produce 
verbose output,
 @end itemize
 
 @cindex default verbosity for silent-rules
-Note that silent rules are @emph{enabled} by default; the user have to
-enable them explicitly at either make at either @command{configure} run
-time or at @command{make} run time.
-
address@hidden: Explain why the above is a good policy, and how the developer
-can circumvent it using the @code{AM_SILENT_RULES([yes])} macro call.
-
address@hidden 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.
address@hidden solution}: silent rules are not enabled by default in the
-distributed packages.
+Note that silent rules are @emph{disabled} by default; the user must
+enable them explicitly at either @command{configure} run time or at
address@hidden run time.  We think that this is a good policy, since
+it provides the casual user with enough information to prepare a good
+bug report in case anything breaks.
+
+Still, notwithstanding the rationales above, a developer who wants to
+make silent rules enabled by default in his own package can do so by
+adding a @samp{yes} argument to the @code{AM_SILENT_RULES} call in
address@hidden  We advise against this approach, though.
+
+Users who prefer to have silent rules enabled by default can edit their
address@hidden file to make the variable @code{enable_silent_rules}
+default to @samp{yes}.  This should still allow disabling silent rules
+at @command{configure} time (and obviously also at @command{make} time).
 
 @c FIXME: there's really a need to specify this explicitly?
 For portability to different @command{make} implementations, package authors
diff --git a/tests/Makefile.am b/tests/Makefile.am
index dab04e3..dfc3649 100644
--- a/tests/Makefile.am
+++ b/tests/Makefile.am
@@ -644,6 +644,7 @@ silent-lex-gcc.test \
 silent-lex-generic.test \
 silent-yacc-gcc.test \
 silent-yacc-generic.test \
+silent-configsite.test \
 sinclude.test \
 srcsub.test \
 srcsub2.test \
diff --git a/tests/Makefile.in b/tests/Makefile.in
index de21f43..c9c48cc 100644
--- a/tests/Makefile.in
+++ b/tests/Makefile.in
@@ -911,6 +911,7 @@ silent-lex-gcc.test \
 silent-lex-generic.test \
 silent-yacc-gcc.test \
 silent-yacc-generic.test \
+silent-configsite.test \
 sinclude.test \
 srcsub.test \
 srcsub2.test \
diff --git a/tests/silent-configsite.test b/tests/silent-configsite.test
new file mode 100755
index 0000000..a383d2d
--- /dev/null
+++ b/tests/silent-configsite.test
@@ -0,0 +1,87 @@
+#!/bin/sh
+# Copyright (C) 2010 Free Software Foundation, Inc.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2, or (at your option)
+# any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+# Check that the user can control default mode of silent-rules
+# from config.site, and that this default can be overridden from
+# either the ./configure or make command line.
+
+. ./defs || Exit 1
+
+set -e
+
+cat >> configure.in <<'EOF'
+AM_SILENT_RULES
+AC_OUTPUT
+EOF
+
+cat > Makefile.am <<'EOF'
+.PHONY: test-silent test-nosilent
+test-silent:
+       test x'$(AM_DEFAULT_VERBOSITY)' = x'0'
+test-nosilent:
+       test x'$(AM_DEFAULT_VERBOSITY)' = x'1'
+EOF
+
+# Calling it once should be enough, since the list of macros invoked
+# by configure.in don't change (even if their arguments do).
+$ACLOCAL
+
+unset enable_silent_rules || :
+
+: 'No explicit default in configure.in, enable by default in config.site'
+
+$AUTOCONF
+$AUTOMAKE --add-missing
+echo "enable_silent_rules=\${enable_silent_rules-yes}" > config.site
+CONFIG_SITE=./config.site ./configure
+$MAKE test-silent
+$MAKE distclean
+# Command line should win over default values in config.site.
+CONFIG_SITE=./config.site ./configure --disable-silent-rules
+$MAKE test-nosilent
+$MAKE distclean
+
+: 'Disable by default in configure.in, enable by default in config.site'
+
+sed 's/^AM_SILENT_RULES/&([no])/' configure.in > configure.tmp
+mv -f configure.tmp configure.in
+$AUTOCONF
+$AUTOMAKE --add-missing
+echo "enable_silent_rules=\${enable_silent_rules-yes}" > config.site
+CONFIG_SITE=./config.site ./configure
+$MAKE test-silent
+# Command line should win over default values in config.site.
+$MAKE distclean
+CONFIG_SITE=./config.site ./configure --disable-silent-rules
+$MAKE test-nosilent
+$MAKE distclean
+
+: 'Enable by default in configure.in, disable by default in config.site'
+
+sed 's/^AM_SILENT_RULES/&([yes])/' configure.in > configure.tmp
+mv -f configure.tmp configure.in
+$AUTOCONF
+$AUTOMAKE --add-missing
+echo "enable_silent_rules=\${enable_silent_rules-no}" > config.site
+CONFIG_SITE=./config.site ./configure
+$MAKE test-nosilent
+$MAKE distclean
+# Command line should win over default values in config.site.
+CONFIG_SITE=./config.site ./configure --enable-silent-rules
+$MAKE test-silent
+$MAKE distclean
+
+:
-- 
1.7.1