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 are disabled by default +in @option{foreign} strictness, an usage like this: +@example +AUTOMAKE_OPTIONS = -Wportability foreign +@end example +@noindent +will end up being enabling those portability warnings. + +However, a strictness level specified in a higher-priority context +will override all the explicit warnings specified in a lower-priority +context. For example, if @file{configure.ac} contains: +@example +AM_INIT_AUTOMAKE([-Wportability]) +@end example +@noindent +and @file{Makefile.am} contains: +@example +AUTOMAKE_OPTIONS = foreign +@end example +@noindent +then @samp{portability} warnings will be @emph{disabled} in +@file{Makefile.am}. This is not an implementation accident, +but a conscious design choice. + +@node List of Automake options +@section A comprehensive list of Automake options + @vindex AUTOMAKE_OPTIONS @table @asis -- 1.7.2.3