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.
>
> > +...@cindex 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 <stefano.lattar...@gmail.com>
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 <stefano.lattar...@gmail.com>
+
+ 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 <stefano.lattar...@gmail.com>
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
-...@var{output-file}. 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:
-
-...@itemize @bullet
-...@item
-Add the @option{silent-rules} option as argument to @code{AM_INIT_AUTOMAKE}.
-...@item
-Call the @code{AM_SILENT_RULES} macro from within the @file{configure.ac}
-file.
-...@end itemize
-
-It is not possible to instead specify @option{silent-rules} in a
-...@file{makefile.am} file.
-
-...@cindex 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:
-
-...@itemize @bullet
-...@item
-...@opindex --enable-silent-rules
-...@opindex --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.
-...@item
-...@vindex @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,
-...@code{make V=0} less verbose output.
-...@end 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
-...@option{silent-rules} option if your package needs to build with
-...@command{make} implementations that do not support it. The
-...@option{silent-rules} option turns off warnings about recursive variable
-expansion, which are in turn enabled by @option{-Wportability}
-(@pxref{Invoking Automake}).
-
-...@vindex @code{AM_V_GEN}
-...@vindex @code{AM_V_at}
-...@vindex @code{AM_DEFAULT_VERBOSITY}
-To extend the silent mode to your own rules, you have two choices:
-
-...@itemize @bullet
-...@item
-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
-...@code{am_v_at} 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.
-...@item
-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
-...@code{am_v_gen}:
-
-...@example
-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 $@@
-...@end example
-...@end itemize
+...@var{output-file} 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}).
+...@node Silencing Make
+...@chapter Silencing @command{make}
+
+...@cindex Silent @command{make}
+...@cindex Silencing @command{make}
+...@cindex Silent rules
+...@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
+
+...@node Make verbosity
+...@section Make is verbose by default
+
+Normally, when executing the set of rules associated with a target,
+...@command{make} 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:
+...@footnote{for more information, see
+...@uref{http://catb.org/~esr/writings/taouu/html/ch01s03.html#rule-silence}
+and @uref{http://catb.org/~esr/writings/taoup/html/ch11s09.html}.}
+
+...@quotation
+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.
+...@end 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.
+
+...@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!)
+...@c TODO: example.
+
+...@node Tricks For Silencing Make
+...@section 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.
+
+...@itemize @bullet
+
+...@item @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!
+
+...@item @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.
+
+...@item @command{make --no-print-directory}
+
+This is GNU @command{make} specific. When called with the
+...@option{--no-print-directory} option, GNU @command{make} will disable
+printing of the working directory by invoked s...@command{make}s (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.
+
+...@c TODO: Other tricks?
+...@c TODO: Maybe speak about the @code{.SILENT} target?
+...@c TODO: - Pros: More granularity on what to silence.
+...@c TODO: - Cons: No easy way to temporarily override.
+
+...@end itemize
+
+...@node Automake silent-rules Option
+...@section 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
+...@command{make} 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:
+
+...@example
+% @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
+...@end example
+
+...@cindex 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}.
+
+...@c TODO: Maybe describe in brief the precedent set by the build
+...@c 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:
+
+...@itemize @bullet
+...@item
+Add the @option{silent-rules} option as argument to @code{AM_INIT_AUTOMAKE}.
+...@item
+Call the @code{AM_SILENT_RULES} macro from within the @file{configure.ac}
+file.
+...@end itemize
+
+It is not possible to instead specify @option{silent-rules} in a
+...@file{makefile.am} 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:
+
+...@itemize @bullet
+...@item
+...@opindex --enable-silent-rules
+...@opindex --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.
+...@item
+...@vindex @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,
+...@code{make V=0} less verbose output.
+...@end itemize
+
+...@cindex 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
+...@command{make} 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
+...@file{configure.ac}. We advise against this approach, though.
+
+Users who prefer to have silent rules enabled by default can edit their
+...@file{config.site} 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
+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
+...@option{silent-rules} option if your package needs to build with
+...@command{make} implementations that do not support it. The
+...@option{silent-rules} option turns off warnings about recursive variable
+expansion, which are in turn enabled by @option{-Wportability}
+(@pxref{Invoking Automake}).
+
+...@vindex @code{AM_V_GEN}
+...@vindex @code{AM_V_at}
+...@vindex @code{AM_DEFAULT_VERBOSITY}
+To extend the silent mode to your own rules, you have two choices:
+
+...@itemize @bullet
+...@item
+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
+...@code{am_v_at} 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.
+...@item
+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
+...@code{am_v_gen}:
+
+...@example
+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 $@@
+...@end example
+
+...@end itemize
+
+As a final note, observe that, even when silent rules are enabled,
+the @option{--no-print-directory} option is still required with GNU
+...@command{make} 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 <stefano.lattar...@gmail.com>
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 <stefano.lattar...@gmail.com>
+2010-12-05 Stefano Lattarini <stefano.lattar...@gmail.com>
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 <stefano.lattar...@gmail.com>
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 s...@command{make}s (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.
-...@emph{todo}: 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:
-...@emph{todo}: Give some examples of @command{make} outputs with silent
-rules respectively enabled and disabled.
-
-...@cindex silent-rules and libtools
-...@emph{todo}: Tell that libtool is automatically used in ``silent mode''
-when @option{silent-rules} are activated.
-
-...@emph{todo}: Maybe describe in brief the precedent set by the build
-system of the Linux Kernel... Links anyone?
+...@example
+% @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
+...@end example
+
+...@cindex 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}.
+
+...@c TODO: Maybe describe in brief the precedent set by the build
+...@c 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.
-
-...@emph{todo}: Explain why the above is a good policy, and how the developer
-can circumvent it using the @code{AM_SILENT_RULES([yes])} macro call.
-
-...@emph{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.
-...@emph{simple 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
+...@command{make} 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
+...@file{configure.ac}. We advise against this approach, though.
+
+Users who prefer to have silent rules enabled by default can edit their
+...@file{config.site} 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
