Mercurial > hg > octave-kai > gnulib-hg
changeset 10797:3c68487be563
Add documentation for warnings module, from Bruno.
author | Simon Josefsson <simon@josefsson.org> |
---|---|
date | Wed, 12 Nov 2008 12:14:55 +0100 |
parents | 442d623111e2 |
children | 3363ce146c2f |
files | ChangeLog doc/gnulib.texi doc/warnings.texi |
diffstat | 3 files changed, 66 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2008-11-12 Simon Josefsson <simon@josefsson.org> + + * doc/warnings.texi: New file, from Bruno Haible <bruno@clisp.org>. + * doc/gnulib.texi: Add section for warnings. + 2008-11-11 Bruno Haible <bruno@clisp.org> * lib/sockets.h: Add a comment.
--- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -5756,6 +5756,7 @@ * Regular expressions:: * Supporting Relocation:: * func:: +* warnings:: @end menu @node alloca @@ -5837,6 +5838,8 @@ @include func.texi +@include warnings.texi + @node GNU Free Documentation License @appendix GNU Free Documentation License
new file mode 100644 --- /dev/null +++ b/doc/warnings.texi @@ -0,0 +1,58 @@ +@node warnings +@section warnings + +The @code{warnings} module allows to regularly build a package with more +GCC warnings than the default warnings emitted by GCC. + +It provides the following functionality: + +@itemize @bullet +@item +You can select some warning options, such as @samp{-Wall}, to be enabled +whenever building with a GCC version that supports these options. The +user can choose to override these warning options by providing the +opposite options in the @code{CFLAGS} variable at configuration time. + +@item +You can make these warnings apply to selected directories only. In +projects where subprojects are maintained by different people, or where +parts of the source code are imported from external sources -- for example +from gnulib --, it is useful to apply different warning options to +different directories. + +@item +It allows to use @samp{-Werror} at @samp{make distcheck} time, to verify +that on the maintainer's system, no warnings remain. (Note that use of +@samp{-Werror} in @code{CFLAGS} does not work in general, because it may +break autoconfiguration.) +@end itemize + +To use this module, you need the following: + +@enumerate +@item +In @file{configure.ac}, use for example +@smallexample +gl_WARN_ADD([-Wall], [WARN_CFLAGS]) +gl_WARN_ADD([-Wpointer-arith], [WARN_CFLAGS]) +@end smallexample + +@item +In the directories which shall use @code{WARN_CFLAGS}, use it in the +definition of @code{AM_CFLAGS}, like this: +@smallexample +AM_CFLAGS = $(WARN_CFLAGS) +@end smallexample + +Note that the @code{AM_CFLAGS} is used in combination with @code{CFLAGS} +and before @code{CFLAGS} in build rules emitted by Automake. This allows +the user to provide @code{CFLAGS} that override the @code{WARN_CFLAGS}. +@end enumerate + +Note that it is a bad idea to use @samp{gl_WARN_ADD([-Werror])}. The +warnings emitted by GCC depend, to some extent, on the contents of the +system header files, on the size and signedness of built-in types, etc. +Use of @samp{-Werror} would cause frustration to all users on platforms +that the maintainer has not tested before the release. It is better if +maintainers use @samp{-Werror} only for themselves (for example, during +@samp{make distcheck}, as mentioned above).