Clarify how to enable `silent-rules' and other global options.

* doc/automake.texi (Options): When introducing options, be more
careful to note that not all of them can be specified in
AUTOMAKE_OPTIONS statements, and that some do not make sense in
subdirectories.  Note more prominently that `silent-rules' can
only be specified in configure.ac.
* lib/Automake/Options.pm (_process_option_list): Improve error
message for `silent-rules', `tar-v7', `tar-ustar', `tar-pax'
options specified in Makefile.am files.
Report by Bruno Haible.

Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de>

diff --git a/ChangeLog b/ChangeLog
index 381ee04..7492eaf 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,16 @@
+2009-05-23  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>
+
+       Clarify how to enable `silent-rules' and other global options.
+       * doc/automake.texi (Options): When introducing options, be more
+       careful to note that not all of them can be specified in
+       AUTOMAKE_OPTIONS statements, and that some do not make sense in
+       subdirectories.  Note more prominently that `silent-rules' can
+       only be specified in configure.ac.
+       * lib/Automake/Options.pm (_process_option_list): Improve error
+       message for `silent-rules', `tar-v7', `tar-ustar', `tar-pax'
+       options specified in Makefile.am files.
+       Report by Bruno Haible.
+
 2009-05-21  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>
 
        Skip specflg10.test without a C++ compiler.

diff --git a/doc/automake.texi b/doc/automake.texi
index 1c93024..6c6765f 100644 (file)
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -8912,13 +8912,18 @@ will now be rerun each time the version number is bumped, when only
 @node Options
 @chapter Changing Automake's Behavior
 
-Various features of Automake can be controlled by options in the
-@file{Makefile.am}.  Such options are applied on a per-@file{Makefile}
-basis when listed in a special @file{Makefile} variable named
-@code{AUTOMAKE_OPTIONS}.  They are applied globally to all processed
-@file{Makefiles} when listed in the first argument of
-@code{AM_INIT_AUTOMAKE} in @file{configure.ac}.  Currently understood
-options are:
+Various features of Automake can be controlled by options.  Except where
+noted otherwise, options can be specified in one of several ways: Most
+options can be applied on a per-@file{Makefile} basis when listed in a
+special @file{Makefile} variable named @code{AUTOMAKE_OPTIONS}.  Some
+of these options only make sense when specified in the toplevel
+@file{Makefile.am} file.  Options are applied globally to all processed
+@file{Makefile} files when listed in the first argument of
+@code{AM_INIT_AUTOMAKE} in @file{configure.ac}, and some options which
+require changes to the @command{configure} script can only be specified
+there.  These are annotated below.
+
+Currently understood options are:
 @vindex AUTOMAKE_OPTIONS
 
 @table @asis
@@ -9121,6 +9126,9 @@ 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

diff --git a/lib/Automake/Options.pm b/lib/Automake/Options.pm
index d104414..cacc7d2 100644 (file)
--- a/lib/Automake/Options.pm
+++ b/lib/Automake/Options.pm
@@ -279,13 +279,15 @@ sub _process_option_list (\%$@)
       elsif ($_ eq  'silent-rules')
         {
          error ($where,
-                "option `$_' must be an argument of AM_INIT_AUTOMAKE")
+                "option `$_' can only be used as argument to AM_INIT_AUTOMAKE\n"
+                . "but not in AUTOMAKE_OPTIONS makefile statements")
            if $where->get !~ /^configure\./;
        }
       elsif ($_ eq 'tar-v7' || $_ eq 'tar-ustar' || $_ eq 'tar-pax')
        {
          error ($where,
-                "option `$_' must be an argument of AM_INIT_AUTOMAKE")
+                "option `$_' can only be used as argument to AM_INIT_AUTOMAKE\n"
+                . "but not in AUTOMAKE_OPTIONS makefile statements")
            if $where->get !~ /^configure\./;
          for my $opt ('tar-v7', 'tar-ustar', 'tar-pax')
            {