diff options
author | Simon Josefsson <simon@josefsson.org> | 2008-11-12 12:14:55 +0100 |
---|---|---|
committer | Simon Josefsson <simon@josefsson.org> | 2008-11-12 12:14:55 +0100 |
commit | e78c877327ec2761fd7dc5a363f4202f55f39b16 (patch) | |
tree | e34b96f1eaf1d3f634ba321107ce3aacfa8680cb /doc | |
parent | a2d0b11f12ac48a198ac068a981be555191fe208 (diff) | |
download | gnulib-e78c877327ec2761fd7dc5a363f4202f55f39b16.tar.gz |
Add documentation for warnings module, from Bruno.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/gnulib.texi | 3 | ||||
-rw-r--r-- | doc/warnings.texi | 58 |
2 files changed, 61 insertions, 0 deletions
diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 3a9265cc4d..fa0d156f13 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -5756,6 +5756,7 @@ This list of functions is sorted according to the header that declares them. * Regular expressions:: * Supporting Relocation:: * func:: +* warnings:: @end menu @node alloca @@ -5837,6 +5838,8 @@ generated automatically. @include func.texi +@include warnings.texi + @node GNU Free Documentation License @appendix GNU Free Documentation License diff --git a/doc/warnings.texi b/doc/warnings.texi new file mode 100644 index 0000000000..ce4920c8e9 --- /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). |