On Friday 12 November 2010, Stefano Lattarini wrote:
> On Friday 12 November 2010, Ralf Wildenhues wrote:
> > Hello Patrick, Miles,
> >
> > * Miles Bader wrote on Fri, Nov 12, 2010 at 09:00:55AM CET:
> > > Patrick Rutkowski <rutsk...@gmail.com> writes:
> > > > I don't get from that page how to apply to all my $(CC) build
> > > > commands, and I really want to quiet down this very messy "make"
> > > > output I now have.
> > *snip explanations*
> >
> > Thanks. A doc change to improve the situation here would be nice;
> > any volunteers?
>
> I might give it a try (not right now); but I'll probably need some
> guidance, as I'm not well up on the issue.
>
I have a first, very rough draft of the patch (see attachement); it is
nowhere complete, but I'd like to ear from you anyway for early criticism,
suggestions, and maybe contributions ;-)
Regards,
Stefano
From 116853d6c78a0a79ab8f57cea6fbe28486f907fa 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 | 10 ++
doc/automake.texi | 263 +++++++++++++++++++++++++++++++++++++----------------
2 files changed, 194 insertions(+), 79 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 7595f3b..7feb9c6 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+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 ...
+ (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..3349942 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,11 @@ Conditionals
* Usage of Conditionals:: Declaring conditional content
* Limits of Conditionals:: Enclosing complete statements
+Silent Make
+
+* 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 +9137,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 +9623,177 @@ 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
+* 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.
+
+...@emph{todo}: having an example showing the woes of an overly verbose
+make output might be nice -- especially a real-world (but short!)
+example.
+
+Here we describe some common idioms/tricks to obtain a quieter make
+output, with relative advantages and drawbacks.
+
+...@itemize @bullet
+
+...@item @command{make -s}
+
+...@emph{todo}: Explain what it does.
+
+...@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!
+
+...@item @command{make >/dev/null 2>&1 || 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.
+
+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?
+
+...@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? Should we deprecate
+...@c $(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
+
+Libtool and silent rules: peculiarities?
+
+Maybe describe in brief the precedent set by the build system
+of the Linux Kernel... Links?
+
+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
