From 0c0a2a11abc9d8e44cadc139df77731532897f0e Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Sat, 6 Dec 2008 12:08:48 +0100 Subject: [PATCH] Document the 'manywarnings' module. --- ChangeLog | 6 ++++++ doc/gnulib.texi | 3 +++ doc/manywarnings.texi | 48 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 57 insertions(+) create mode 100644 doc/manywarnings.texi diff --git a/ChangeLog b/ChangeLog index 7b2fe13986..d34dbab54d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2008-12-06 Bruno Haible + + Document the 'manywarnings' module. + * doc/manywarnings.texi: New file. + * doc/gnulib.texi: Include it. + 2008-12-05 Eric Blake tests: silence some gcc warnings diff --git a/doc/gnulib.texi b/doc/gnulib.texi index fa0d156f13..a93b64345e 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -5757,6 +5757,7 @@ This list of functions is sorted according to the header that declares them. * Supporting Relocation:: * func:: * warnings:: +* manywarnings:: @end menu @node alloca @@ -5840,6 +5841,8 @@ generated automatically. @include warnings.texi +@include manywarnings.texi + @node GNU Free Documentation License @appendix GNU Free Documentation License diff --git a/doc/manywarnings.texi b/doc/manywarnings.texi new file mode 100644 index 0000000000..2ad807e750 --- /dev/null +++ b/doc/manywarnings.texi @@ -0,0 +1,48 @@ +@node manywarnings +@section manywarnings + +The @code{manywarnings} module allows you to enable as many GCC warnings as +possible for your package. The purpose is to protect against introducing new +code that triggers warning that weren't already triggered by the existing code +base. + +An example use of the module is as follows: + +@smallexample +gl_MANYWARN_ALL_GCC([warnings]) +# Set up the list of the pointless, undesired warnings. +nw= +nw="$nw -Wsystem-headers" # Don't let system headers trigger warnings +nw="$nw -Wundef" # All compiler preprocessors support #if UNDEF +nw="$nw -Wtraditional" # All compilers nowadays support ANSI C +nw="$nw -Wconversion" # These warnings usually don't point to mistakes. +nw="$nw -Wsign-conversion" # Likewise. +# Enable all GCC warnings not in this list. +gl_MANYWARN_COMPLEMENT[warnings], [$warnings], [$nw]) +for w in $warnings; do + gl_WARN_ADD([$w]) +done +@end smallexample + +This module is meant to be used by developers who are not very experienced +regarding the various GCC warning option. In the beginning you will set the +list of undesired warnings (@samp{nw} in the example above) to empty, and +compile the package with all possible warnings enabled. The GCC option +@code{-fdiagnostics-show-option}, available in GCC 4.1 or newer, helps +understanding which warnings is originated from which option. Then you will +go through the list of warnings. You will likely deactivate warnings that +occur often and don't point to mistakes in the code, by adding them to the +@samp{nw} variable, then reconfiguring and recompiling. When warnings point +to real mistakes and bugs in the code, you will of course not disable +them. + +There are also many GCC warning options which usually don't point to mistakes +in the code; these warnings enforce a certain programming style. It is a +project management decision whether you want your code to follow any of these +styles. Note that some of these programming styles are conflicting. You +cannot have them all; you have to choose among them. + +When a new version of GCC is released, you can add the new warning options +that it introduces into the @code{gl_MANYWARN_ALL_GCC} macro (and submit your +modification to the Gnulib maintainers :-)), and enjoy the benefits of the +new warnings, while adding the undesired ones to the @samp{nw} variable. -- 2.30.2