[PATCH] Update docs w.r.t. warning and strictness options.
And here finally is the promised documentation patch, which should
conclude the patch series (this time for good, I hope!).
Thanks, and sorry for the delay,
Stefano
From 2d902e81c6b2fbb939c8b6a3d1c744dfbf03655c Mon Sep 17 00:00:00 2001
From: Stefano Lattarini stefano.lattar...@gmail.com
Date: Fri, 14 Jan 2011 15:18:36 +0100
Subject: [PATCH] Update docs w.r.t. warning and strictness options.
* doc/automake.texi (Strictness): Document that some warnings are
turned off by default in `foreign' strictness.
(Options): Divide into new sections Options generalities and
List of Automake options. Fix typo (colon instead of full
stop). Document option precedence (AUTOMAKE_OPTIONS wins over
AM_INIT_AUTOMAKE which wins over command line). Also document
interactions between options specifying strictness and those
specifying warnings.
---
ChangeLog | 12 +++
doc/automake.texi | 58 ++--
2 files changed, 67 insertions(+), 3 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 751f1a9..bdb3228 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,17 @@
2011-01-02 Stefano Lattarini stefano.lattar...@gmail.com
+ Update docs w.r.t. warning and strictness options.
+ * doc/automake.texi (Strictness): Document that some warnings are
+ turned off by default in `foreign' strictness.
+ (Options): Divide into new sections Options generalities and
+ List of Automake options. Fix typo (colon instead of full
+ stop). Document option precedence (AUTOMAKE_OPTIONS wins over
+ AM_INIT_AUTOMAKE which wins over command line). Also document
+ interactions between options specifying strictness and those
+ specifying warnings.
+
+2011-01-02 Stefano Lattarini stefano.lattar...@gmail.com
+
More checks on warnings/strictness precedence.
* tests/warning-groups-win-over-strictness.test: New test, similar
to `warnings-win-over-strictness.test', but checking the explicit
diff --git a/doc/automake.texi b/doc/automake.texi
index 8c98ce8..3e41966 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -320,6 +320,11 @@ Support for test suites
* DejaGnu Tests:: Interfacing with the external testing framework
* Install Tests:: Running tests on installed packages
+Changing Automake's Behavior
+
+* Options generalities::Automake options, strictness, and their precedence
+* List of Automake options::A comprehensive list of Automake options
+
Miscellaneous Rules
* Tags::Interfacing to cscope, etags and mkid
@@ -1899,7 +1904,9 @@ The valid strictness levels are:
Automake will check for only those things that are absolutely
required for proper operations. For instance, whereas GNU standards
dictate the existence of a @file{NEWS} file, it will not be required in
-this mode. The name comes from the fact that Automake is intended to be
+this mode. This strictness will also turn off some warnings by default
+(among them, the @samp{portability} warnings).
+The name comes from the fact that Automake is intended to be
used for GNU programs; these relaxed rules are not the standard mode of
operation.
@@ -9023,8 +9030,16 @@ will now be rerun each time the version number is bumped, when only
@node Options
@chapter Changing Automake's Behavior
+@menu
+* Options generalities::Automake options, strictness, and their precedence
+* List of Automake options::A comprehensive list of Automake options
+@end menu
+
+@node Options generalities
+@section Automake options, strictness, and their precedence
+
Various features of Automake can be controlled by options. Except where
-noted otherwise, options can be specified in one of several ways: Most
+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
@@ -9034,7 +9049,44 @@ of these options only make sense when specified in the toplevel
require changes to the @command{configure} script can only be specified
there. These are annotated below.
-Currently understood options are:
+As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take
+precedence over those specified in @code{AM_INIT_AUTOMAKE}, which in
+turn take precedence over those specified on the command line@footnote{
+We're painfully aware that this last precedence sounds wrong and is
+against all the established conventions, but it's due to historical
+reasons, and presently cannot be easily changed. It might be fixed
+in a future Automake version though, so try not to rely on it.}.
+
+Also, some care must be taken about the interactions among strictness
+level and warning categories. As a general rule, strictness-implied
+warnings are overridden by those specified by explicit options. For
+example, even if @samp{portability} warnings
Re: [PATCH] Update docs w.r.t. warning and strictness options.
* Stefano Lattarini wrote on Sat, Jan 15, 2011 at 12:41:16PM CET:
And here finally is the promised documentation patch, which should
conclude the patch series (this time for good, I hope!).
Thanks, and sorry for the delay,
No problem. Let's see if we can get through it quickly.
I think you should not let the remainder of the patch series have to
wait for this, though.
Subject: [PATCH] Update docs w.r.t. warning and strictness options.
* doc/automake.texi (Strictness): Document that some warnings are
turned off by default in `foreign' strictness.
(Options): Divide into new sections Options generalities and
s/: /: /
List of Automake options. Fix typo (colon instead of full
s/ / /
stop). Document option precedence (AUTOMAKE_OPTIONS wins over
AM_INIT_AUTOMAKE which wins over command line). Also document
interactions between options specifying strictness and those
specifying warnings.
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -320,6 +320,11 @@ Support for test suites
* DejaGnu Tests:: Interfacing with the external testing
framework
* Install Tests:: Running tests on installed packages
+Changing Automake's Behavior
+
+* Options generalities::Automake options, strictness, and their
precedence
info output should not exceed 80 characters (probably not 79, haven't
checked), this line is too long. How about this instead?
* Options generalities::Semantics of Automake options
Please also rerun emacs ^C ^U ^V before committing, thanks.
+* List of Automake options::A comprehensive list of Automake options
+
Miscellaneous Rules
* Tags::Interfacing to cscope, etags and mkid
@@ -1899,7 +1904,9 @@ The valid strictness levels are:
Automake will check for only those things that are absolutely
required for proper operations. For instance, whereas GNU standards
dictate the existence of a @file{NEWS} file, it will not be required in
-this mode. The name comes from the fact that Automake is intended to be
+this mode. This strictness will also turn off some warnings by default
+(among them, the @samp{portability} warnings).
s/the @samp{\(.*\)}/\1/
+The name comes from the fact that Automake is intended to be
used for GNU programs; these relaxed rules are not the standard mode of
operation.
@@ -9023,8 +9030,16 @@ will now be rerun each time the version number is
bumped, when only
@node Options
@chapter Changing Automake's Behavior
+@menu
+* Options generalities::Automake options, strictness, and their
precedence
+* List of Automake options::A comprehensive list of Automake options
+@end menu
+
+@node Options generalities
+@section Automake options, strictness, and their precedence
Karl recommends section names to be identical to node names in general.
How about just naming this Option generalities?
Various features of Automake can be controlled by options. Except where
-noted otherwise, options can be specified in one of several ways: Most
+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
@@ -9034,7 +9049,44 @@ of these options only make sense when specified in the
toplevel
require changes to the @command{configure} script can only be specified
there. These are annotated below.
-Currently understood options are:
+As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take
+precedence over those specified in @code{AM_INIT_AUTOMAKE}
OK until here.
, which in
+turn take precedence over those specified on the command line@footnote{
+We're painfully aware that this last precedence sounds wrong and is
+against all the established conventions, but it's due to historical
+reasons, and presently cannot be easily changed. It might be fixed
+in a future Automake version though, so try not to rely on it.}.
No. We already agreed to fixing this, so we should not document the
broken behavior. We should fix it instead. Can we just omit this for
the moment? Maybe with a
@comment FIXME: document interaction with command-line args when fixed.
if you prefer that.
+Also, some care must be taken about the interactions among strictness
+level and warning categories. As a general rule, strictness-implied
+warnings are overridden by those specified by explicit options. For
+example, even if @samp{portability} warnings are disabled by default
+in @option{foreign} strictness, an usage like this:
s/an usage like//
(but see below)
+@example
+AUTOMAKE_OPTIONS = -Wportability foreign
+@end example
+@noindent
+will end up being enabling those portability warnings.
s/being //
Empty lines before @example and after @end example, and before
@noindent (the last two should
Re: [PATCH] Update docs w.r.t. warning and strictness options.
On Saturday 15 January 2011, Ralf Wildenhues wrote:
* Stefano Lattarini wrote on Sat, Jan 15, 2011 at 12:41:16PM CET:
And here finally is the promised documentation patch, which should
conclude the patch series (this time for good, I hope!).
Thanks, and sorry for the delay,
No problem. Let's see if we can get through it quickly.
I think you should not let the remainder of the patch series have to
wait for this, though.
OK, if we don't get through this patch today, I'll push the previous
patches to a public branch (after having fixed the dates in the ChangeLog
entries).
BTW, is the name 'warns-win-over-strictness' acceptable for that branch?
Subject: [PATCH] Update docs w.r.t. warning and strictness options.
* doc/automake.texi (Strictness): Document that some warnings are
turned off by default in `foreign' strictness.
(Options): Divide into new sections Options generalities and
s/: /: /
Fixed (in commit message and in ChangeLog entry alike).
List of Automake options. Fix typo (colon instead of full
s/ / /
Likewise.
stop). Document option precedence (AUTOMAKE_OPTIONS wins over
AM_INIT_AUTOMAKE which wins over command line). Also document
interactions between options specifying strictness and those
specifying warnings.
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -320,6 +320,11 @@ Support for test suites
* DejaGnu Tests:: Interfacing with the external testing
framework
* Install Tests:: Running tests on installed packages
+Changing Automake's Behavior
+
+* Options generalities::Automake options, strictness, and their
precedence
info output should not exceed 80 characters (probably not 79, haven't
checked), this line is too long. How about this instead?
* Options generalities::Semantics of Automake options
OK.
Please also rerun emacs ^C ^U ^V before committing, thanks.
You mean ^C ^U ^A, right?
+* List of Automake options::A comprehensive list of Automake options
+
Miscellaneous Rules
* Tags::Interfacing to cscope, etags and mkid
@@ -1899,7 +1904,9 @@ The valid strictness levels are:
Automake will check for only those things that are absolutely
required for proper operations. For instance, whereas GNU standards
dictate the existence of a @file{NEWS} file, it will not be required in
-this mode. The name comes from the fact that Automake is intended to be
+this mode. This strictness will also turn off some warnings by default
+(among them, the @samp{portability} warnings).
s/the @samp{\(.*\)}/\1/
Fixed.
+The name comes from the fact that Automake is intended to be
used for GNU programs; these relaxed rules are not the standard
mode of operation.
@@ -9023,8 +9030,16 @@ will now be rerun each time the version number is
bumped, when only
@node Options
@chapter Changing Automake's Behavior
+@menu
+* Options generalities::Automake options, strictness, and their
precedence
+* List of Automake options::A comprehensive list of Automake options
+@end menu
+
+@node Options generalities
+@section Automake options, strictness, and their precedence
Karl recommends section names to be identical to node names in general.
How about just naming this Option generalities?
I chose the name above only for consistency with the menu entries.
If you tell me this consistency is not needed, I heartily agree with
your proposed renaming, which makes things clearer IMHO.
Various features of Automake can be controlled by options. Except where
-noted otherwise, options can be specified in one of several ways: Most
+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
@@ -9034,7 +9049,44 @@ of these options only make sense when specified in
the toplevel
require changes to the @command{configure} script can only be specified
there. These are annotated below.
-Currently understood options are:
+As a general rule, options specified in @code{AUTOMAKE_OPTIONS} take
+precedence over those specified in @code{AM_INIT_AUTOMAKE}
OK until here.
, which in
+turn take precedence over those specified on the command line@footnote{
+We're painfully aware that this last precedence sounds wrong and is
+against all the established conventions, but it's due to historical
+reasons, and presently cannot be easily changed. It might be fixed
+in a future Automake version though, so try not to rely on it.}.
No. We already agreed to fixing this, so we should not document the
broken behavior. We should fix it instead.
Wait, IMVHO this fix cannot just be in the next automake release
without a clear
Re: [PATCH] Update docs w.r.t. warning and strictness options.
* Stefano Lattarini wrote on Sat, Jan 15, 2011 at 02:23:56PM CET:
On Saturday 15 January 2011, Ralf Wildenhues wrote:
* Stefano Lattarini wrote on Sat, Jan 15, 2011 at 12:41:16PM CET:
And here finally is the promised documentation patch, which should
conclude the patch series (this time for good, I hope!).
Thanks, and sorry for the delay,
No problem. Let's see if we can get through it quickly.
I think you should not let the remainder of the patch series have to
wait for this, though.
OK, if we don't get through this patch today, I'll push the previous
patches to a public branch (after having fixed the dates in the ChangeLog
entries).
BTW, is the name 'warns-win-over-strictness' acceptable for that branch?
Sure.
I have an intended use case where it might not be ideal that warnings
win over other options, by the way. I hope to be able to finish the
gnu-make writeup tomorrow (where it happens).
--- a/doc/automake.texi
+++ b/doc/automake.texi
* Options generalities::Semantics of Automake options
OK.
Please also rerun emacs ^C ^U ^V before committing, thanks.
You mean ^C ^U ^A, right?
Yes, sorry.
@@ -9023,8 +9030,16 @@ will now be rerun each time the version number is
bumped, when only
+@node Options generalities
+@section Automake options, strictness, and their precedence
Karl recommends section names to be identical to node names in general.
How about just naming this Option generalities?
I chose the name above only for consistency with the menu entries.
If you tell me this consistency is not needed, I heartily agree with
your proposed renaming, which makes things clearer IMHO.
OK.
, which in
+turn take precedence over those specified on the command line@footnote{
+We're painfully aware that this last precedence sounds wrong and is
+against all the established conventions, but it's due to historical
+reasons, and presently cannot be easily changed. It might be fixed
+in a future Automake version though, so try not to rely on it.}.
No. We already agreed to fixing this, so we should not document the
broken behavior. We should fix it instead.
Wait, IMVHO this fix cannot just be in the next automake release
without a clear deprecation of the older behaviour first. The
backward-incompatibility would be too great and sharp otherwise.
The right thing to do (again IMVHO) is implement the fix in a proper
master-based branch, and merge it back into master only after automake
1.12 has been released. WDYT?
Hmm. I would prefer to delay this decision until we have to cross that
bridge; i.e.:
- before we release 1.11.2, we should think about deprecation again,
- when we have a patch to change precedence, we can try to evaluate how
disruptive it is, and then decide whether it can go in 1.12 or 1.13.
But anyway I don't want behavior that we want to change be documented
and thus set in stone in the manual now, if it previously hasn't been
documented. So, can we please decouple these things from the patch
series we are discussing here?
Can we just omit this for
the moment? Maybe with a
@comment FIXME: document interaction with command-line args when fixed.
if you prefer that.
Before discussing about this any further, I'll wait for a reply to my
argumentation above.
Empty lines before @example and after @end example, and before
@noindent (the last two should be collapsed to just one).
Oh, sorry. I just copied and pasted from some pre-existing code,
which lacks such spacing.
Indeed. I'll fix them in maint presently.
+@node List of Automake options
+@section A comprehensive list of Automake options
This @section should be renamed as List of Automake options, right?
Yep.
Thanks!
Ralf
docs: ensure example are separated with empty lines in the input (was: [PATCH] Update docs w.r.t. warning and strictness options.)
* Ralf Wildenhues wrote on Sat, Jan 15, 2011 at 02:49:33PM CET:
* Stefano Lattarini wrote on Sat, Jan 15, 2011 at 02:23:56PM CET:
On Saturday 15 January 2011, Ralf Wildenhues wrote:
Empty lines before @example and after @end example, and before
@noindent (the last two should be collapsed to just one).
Oh, sorry. I just copied and pasted from some pre-existing code,
which lacks such spacing.
Indeed. I'll fix them in maint presently.
Pushing as follows.
Cheers,
Ralf
docs: ensure example are separated with empty lines in the input
* doc/automake.texi (Extending aclocal, Emacs Lisp, Rebuilding)
(API Versioning, Renamed Objects, Multiple Outputs): Add empty
lines before `@example' and after `@end example' lines, so info
output is rendered correctly, and a following @noindent honored.
Report by Stefano Lattarini.
diff --git a/doc/automake.texi b/doc/automake.texi
index 80a5ce2..73c0e51 100644
--- a/doc/automake.texi
+++ b/doc/automake.texi
@@ -3456,6 +3456,7 @@ Extending aclocal
current implementation, however it requires a stricter style from the
macro authors. Hopefully it is easy to revise the existing macros.
For instance,
+
@example
# bad style
AC_PREREQ(2.57)
@@ -3465,8 +3466,10 @@ Extending aclocal
AX_BAR
])
@end example
+
@noindent
should be rewritten as
+
@example
AC_DEFUN([AX_FOOBAR],
[AC_PREREQ([2.57])dnl
@@ -7455,18 +7458,20 @@ Emacs Lisp
There are two ways to avoid byte-compiling. Historically, we have
recommended the following construct.
+
@example
lisp_LISP = file1.el file2.el
ELCFILES =
@end example
+
@noindent
@code{ELCFILES} is an internal Automake variable that normally lists
all @file{.elc} files that must be byte-compiled. Automake defines
@code{ELCFILES} automatically from @code{lisp_LISP}. Emptying this
variable explicitly prevents byte-compilation.
-Since Automake 1.8, we now recommend using @code{lisp_DATA} instead. As
-in
+Since Automake 1.8, we now recommend using @code{lisp_DATA} instead:
+
@example
lisp_DATA = file1.el file2.el
@end example
@@ -8925,9 +8930,11 @@ Rebuilding
from @file{configure.ac}. For instance, the following statement will
cause @file{configure} to be rerun each time @file{version.sh} is
changed.
+
@example
AC_SUBST([CONFIG_STATUS_DEPENDENCIES], ['$(top_srcdir)/version.sh'])
@end example
+
@noindent
Note the @samp{$(top_srcdir)/} in the file name. Since this variable
is to be used in all @file{Makefile}s, its value must be sensible at
@@ -8953,12 +8960,14 @@ Rebuilding
today. They are mainly used when the version of a package is updated
automatically by a script (e.g., in daily builds). Here is what some
old-style @file{configure.ac}s may look like:
+
@example
AC_INIT
. $srcdir/version.sh
AM_INIT_AUTOMAKE([name], $VERSION_NUMBER)
@dots{}
@end example
+
@noindent
Here, @file{version.sh} is a shell fragment that sets
@code{VERSION_NUMBER}. The problem with this example is that
@@ -8969,12 +8978,14 @@ Rebuilding
straightforward, because shell variables are not allowed in
@code{AC_INIT}'s arguments. We recommend that @file{version.sh} be
replaced by an M4 file that is included by @file{configure.ac}:
+
@example
m4_include([version.m4])
AC_INIT([name], VERSION_NUMBER)
AM_INIT_AUTOMAKE
@dots{}
@end example
+
@noindent
Here @file{version.m4} could contain something like
@samp{m4_define([VERSION_NUMBER], [1.2])}. The advantage of this
@@ -10300,12 +10311,14 @@ API Versioning
@example
AM_INIT_AUTOMAKE([1.6.1])dnl Require Automake 1.6.1 or better.
@end example
+
@noindent
or, in a particular @file{Makefile.am}:
@example
AUTOMAKE_OPTIONS = 1.6.1 # Require Automake 1.6.1 or better.
@end example
+
@noindent
Automake will print an error message if its version is
older than the requested version.
@@ -11192,6 +11205,7 @@ Renamed Objects
false_SOURCES = generic.c
false_CPPFLAGS = -DEXIT_CODE=1
@end example
+
@noindent
Obviously the two programs are built from the same source, but it
would be bad if they shared the same object, because @file{generic.o}
@@ -11361,6 +11375,7 @@ Multiple Outputs
data.h: data.foo data.c
foo data.foo
@end example
+
@noindent
therefore a parallel @command{make} will have to serialize the builds
of @file{data.c} and @file{data.h}, and will detect that the second is
Re: [PATCH] Update docs w.r.t. warning and strictness options.
On Saturday 15 January 2011, Ralf Wildenhues wrote:
* Stefano Lattarini wrote on Sat, Jan 15, 2011 at 02:23:56PM CET:
On Saturday 15 January 2011, Ralf Wildenhues wrote:
* Stefano Lattarini wrote on Sat, Jan 15, 2011 at 12:41:16PM CET:
, which in
+turn take precedence over those specified on the command line@footnote{
+We're painfully aware that this last precedence sounds wrong and is
+against all the established conventions, but it's due to historical
+reasons, and presently cannot be easily changed. It might be fixed
+in a future Automake version though, so try not to rely on it.}.
No. We already agreed to fixing this, so we should not document the
broken behavior. We should fix it instead.
Wait, IMVHO this fix cannot just be in the next automake release
without a clear deprecation of the older behaviour first. The
backward-incompatibility would be too great and sharp otherwise.
The right thing to do (again IMVHO) is implement the fix in a proper
master-based branch, and merge it back into master only after automake
1.12 has been released. WDYT?
Hmm. I would prefer to delay this decision until we have to cross that
bridge; i.e.:
- before we release 1.11.2, we should think about deprecation again,
- when we have a patch to change precedence, we can try to evaluate how
disruptive it is, and then decide whether it can go in 1.12 or 1.13.
But anyway I don't want behavior that we want to change be documented
and thus set in stone in the manual now, if it previously hasn't been
documented. So, can we please decouple these things from the patch
series we are discussing here?
Yes, of course. I'll remove the footnote, which, as you noted, can
always be re-proposed in a follow-up patch.
Regards,
Stefano
