[dropping autom...@gnu.org]
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 <ralf.wildenh...@gmx.de>
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
-...@node Tricks For Silencing Make
-...@section Standard and generic ways to silence make
-
-...@emph{todo}: Maybe a short introduction on how makes violates the
-``silence is golden'' UNIX rule.
-
-...@emph{pros} 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.
+...@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
+(@emph{FIXME}: what about a link here, maybe
+...@uref{http://www.faqs.org/docs/artu/ch01s06.html#id2878450} or
+...@uref{http://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.
+...@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 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}
-...@emph{todo}: 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.
-...@emph{cons}: 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!
+...@emph{cons}: Its an ``all or nothing'' strategy: either everything is
+silenced, or nothing is. Moreover, when this option 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 error was!
-...@item @command{make >/dev/null 2>&1 || make}
+...@item @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.
-...@item @emph{TODO}: other tricks?
+...@item @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}
-...@c FIXME: wouldn't $(AM_V_SILENT) be clearer? Should we deprecate
-...@c $(AM_V_at)? It should be kept for backward-compatibility, of
-...@c course.
+...@c FIXME: wouldn't $(AM_V_SILENT) be clearer that $(AM_V_at)? Should we
+...@c deprecate $(AM_V_at) (it should be kept for backward-compatibility, of
+...@c 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
+...@emph{todo}:
Libtool and silent rules: peculiarities?
+...@emph{todo}:
Maybe describe in brief the precedent set by the build system
of the Linux Kernel... Links?
+...@emph{todo}:
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 <stefano.lattar...@gmail.com>
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 <stefano.lattar...@gmail.com>
+
+ 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 <ralf.wildenh...@gmx.de>
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
-...@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,203 @@ 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
+(@emph{FIXME}: what about a link here, maybe
+...@uref{http://www.faqs.org/docs/artu/ch01s06.html#id2878450} or
+...@uref{http://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.
+
+...@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 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.
+
+...@emph{pros}: It's easy to use and understand, and it's mandated by
+POSIX.
+
+...@emph{cons}: Its an ``all or nothing'' strategy: either everything is
+silenced, or nothing is. Moreover, when this option 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 error was!
+
+...@item @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?).
+
+...@item @command{gmake --no-print-directory}
+
+This is GNU make specific.
+
+...@emph{pros}: TODO.
+
+...@emph{cons}: TODO.
+
+...@item @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
+
+...@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. 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 `...@code{am_silent_rules([yes])}'', but we should
+discourage that).
+
+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}
+...@c FIXME: wouldn't $(AM_V_SILENT) be clearer that $(AM_V_at)? Should we
+...@c deprecate $(AM_V_at) (it should be kept for backward-compatibility, of
+...@c course).
+...@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
+
+...@emph{todo}:
+Libtool and silent rules: peculiarities?
+
+...@emph{todo}:
+Maybe describe in brief the precedent set by the build system
+of the Linux Kernel... Links?
+
+...@emph{todo}:
+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
