automake
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Stefano Lattarini
Subject: [RFC] Docs: document silent make rules in a new chapter (was: Re: AM_V_GEN - better docs)
Date: Thu, 18 Nov 2010 20:31:26 +0100
User-agent: KMail/1.13.3 (Linux/2.6.30-2-686; KDE/4.4.4; i686; ; )

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 <address@hidden> 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 <address@hidden>
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  <address@hidden>
+
+       Docs: document silent make rules in a new dedicated chapter.
+       * doc/automake.texi (Options): Detailed description of the automake
+       option `silent-rules' moved from here ...
+       (Silent Make): ... to this new chapter, with its two ...
+       (Tricks For Silencing Make, Automake silent-rules Option): ... new
+       sections (FIXME: to be finished).
+       (@menu, @detailmenu): Update.
+
 2010-11-14  Ralf Wildenhues  <address@hidden>
 
        Rebuild menus in the manual.
diff --git a/doc/automake.texi b/doc/automake.texi
index 5a805b3..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
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 +9623,177 @@ 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
+* 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 Tricks For Silencing Make
address@hidden Standard and generic ways to silence make
+
address@hidden: Maybe a short introduction on how makes violates the
+``silence is golden'' UNIX rule.
+
address@hidden of having a quieter make output in general: warning and
+error messages from make-invoked tools stick out much better, and are
+not drowned in a flood of uninteresting and seldom useful messages.
+This might be very useful from a developer's point of view.
+
address@hidden: 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.
+
address@hidden @bullet
+
address@hidden @command{make -s}
+
address@hidden: Explain what it does.
+
address@hidden: It's easy to use and understand, and it's mandated by
+POSIX.
+
address@hidden: Its output might turn out to be too much terse; in
+case of errors, the user won't be able to easily see what rule or
+command have caused them, or even, in case of tools with poor
+error reporting, what the error was!
+
address@hidden @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?).
+
address@hidden @command{gmake --no-print-directory}
+
+This is GNU make specific.
+
address@hidden: TODO.
+
address@hidden: TODO.
+
address@hidden @emph{TODO}: other tricks?
+
address@hidden itemize
+
address@hidden Automake silent-rules Option
address@hidden How Automake can help in silencing make
+
+As we've seen, the tricks and idioms for silencing make described in the
+previous section, while useful from time to time, all have some serious
+drawbacks and limitations.  Automake comes to the rescue!
+
+Problem of silent rules: the investigation of user bug reports might be
+more difficult, since the developer cannot see in its completeness the
+command(s) that caused the failure on the user system.
+
+Simple solutions: do not enable silent rules by default!
+
+To enable less verbose build rules, both the developer and the user of the
+package have to take a number of steps (@emph{FIXME}: this is not strictly
+true if the developer uses address@hidden([yes])}'', but we should
+discourage that).
+
+The developer needs to do either of the following:
+
address@hidden @bullet
address@hidden
+Add the @option{silent-rules} option as argument to @code{AM_INIT_AUTOMAKE}.
address@hidden
+Call the @code{AM_SILENT_RULES} macro from within the @file{configure.ac}
+file.
address@hidden itemize
+
+It is not possible to instead specify @option{silent-rules} in a
address@hidden file.
+
address@hidden default verbosity for silent-rules
+If the developer has done either of the above, then the user of the
+package may influence the verbosity at @command{configure} run time as
+well as at @command{make} run time:
+
address@hidden @bullet
address@hidden
address@hidden --enable-silent-rules
address@hidden --disable-silent-rules
+Passing @option{--enable-silent-rules} to @command{configure} will cause
+build rules to be less verbose; the option @option{--disable-silent-rules}
+is the default and will cause normal verbose output.
address@hidden
address@hidden @code{V}
+At @command{make} run time, the default chosen at @command{configure}
+time may be overridden: @code{make V=1} will produce verbose output,
address@hidden V=0} less verbose output.
address@hidden itemize
+
+For portability to different @command{make} implementations, package authors
+are advised to not set the variable @code{V} inside the @file{Makefile.am}
+file, to allow the user to override the value for subdirectories as well.
+
+The current implementation of this feature relies on a non-POSIX, but in
+practice rather widely supported @file{Makefile} construct of nested
+variable expansion @samp{$(@var{var1}$(V))}.  Do not use the
address@hidden option if your package needs to build with
address@hidden implementations that do not support it.  The
address@hidden option turns off warnings about recursive variable
+expansion, which are in turn enabled by @option{-Wportability}
+(@pxref{Invoking Automake}).
+
address@hidden @code{AM_V_GEN}
address@hidden FIXME: wouldn't $(AM_V_SILENT) be clearer?  Should we deprecate
address@hidden $(AM_V_at)?  It should be kept for backward-compatibility, of
address@hidden course.
address@hidden @code{AM_V_at}
address@hidden @code{AM_DEFAULT_VERBOSITY}
+To extend the silent mode to your own rules, you have two choices:
+
address@hidden @bullet
address@hidden
+You can use the predefined variable @code{AM_V_GEN} as a prefix to
+commands that should output a status line in silent mode, and
address@hidden as a prefix to commands that should not output anything
+in silent mode.  When output is to be verbose, both of these variables
+will expand to the empty string.
address@hidden
+You can add your own variables, so strings of your own choice are shown.
+The following snippet shows how you would define your own equivalent of
address@hidden:
+
address@hidden
+pkg_verbose = $(pkg_verbose_$(V))
+pkg_verbose_ = $(pkg_verbose_$(AM_DEFAULT_VERBOSITY))
+pkg_verbose_0 = @@echo PKG-GEN $@@;
+
+foo: foo.in
+        $(pkg_verbose)cp $(srcdir)/foo.in $@@
address@hidden example
+
address@hidden itemize
+
+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


reply via email to

[Prev in Thread] Current Thread [Next in Thread]