From: Bruno Haible Date: Sun, 4 Jun 2023 22:16:40 +0000 (+0200) Subject: manywarnings: Overhaul documentation. X-Git-Tag: v1.0~1251 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bdb7dbf8c8fafb67b1d4fe84ce3ddb74595cb1e8;p=thirdparty%2Fgnulib.git manywarnings: Overhaul documentation. * doc/manywarnings.texi: In the example, put all unwanted warning options into 'nw', and use a second gl_MANYWARN_COMPLEMENT invocation to sort out how these options need to get added to WARN_FLAGS. Describe the first-time use in more detail: Recommend a new GCC. Recommend to test builds with -O2 and with -O0. Suggest to sort the warning by warning option. Add reference to the GCC pragma's documentation. --- diff --git a/ChangeLog b/ChangeLog index eea4e17251..9a30a0fb8a 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,14 @@ +2023-06-04 Bruno Haible + + manywarnings: Overhaul documentation. + * doc/manywarnings.texi: In the example, put all unwanted warning + options into 'nw', and use a second gl_MANYWARN_COMPLEMENT invocation to + sort out how these options need to get added to WARN_FLAGS. + Describe the first-time use in more detail: Recommend a new GCC. + Recommend to test builds with -O2 and with -O0. Suggest to sort the + warning by warning option. Add reference to the GCC pragma's + documentation. + 2023-06-04 Bruno Haible error: Fix support for library namespacing (regression 2023-05-27). diff --git a/doc/manywarnings.texi b/doc/manywarnings.texi index 01e23116cc..19b58f8e47 100644 --- a/doc/manywarnings.texi +++ b/doc/manywarnings.texi @@ -12,48 +12,112 @@ AC_ARG_ENABLE([gcc-warnings], 'expensive' in addition generates expensive warnings.])]) AS_IF([test "$enable_gcc_warnings" != no], - [gl_MANYWARN_ALL_GCC([warnings]) - + [ # Set up the list of unwanted warning options. nw= if test "$enable_gcc_warnings" != expensive; then nw="$nw -fanalyzer" fi - nw="$nw -Winline" # It's OK to not inline. - nw="$nw -Wstrict-overflow" # It's OK to optimize strictly. - nw="$nw -Wsystem-headers" # Don't warn in system headers. - - # Enable all GCC warnings not in this list. - gl_MANYWARN_COMPLEMENT([warnings], [$warnings], [$nw]) - for w in $warnings; do + nw="$nw -Wbad-function-cast" # Casting a function's result is not more + # dangerous than casting any other value. + nw="$nw -Winline" # It's OK to not inline. + nw="$nw -Wsign-compare" # Too many false alarms. + nw="$nw -Wstrict-overflow" # It's OK to optimize strictly. + nw="$nw -Wsystem-headers" # Don't warn in system headers. + + # Setup the list of meaningful warning options for the C compiler. + # The list comes from manywarnings.m4. Warning options that are not + # generally meaningful have already been filtered out (cf. + # build-aux/gcc-warning.spec). + gl_MANYWARN_ALL_GCC([possible_warning_options]) + + # Compute the list of warning options that are desired. + gl_MANYWARN_COMPLEMENT([desired_warning_options], + [$possible_warning_options], [$nw]) + # Compute the list of remaining undesired warning options. + # Namely those, that were not in manywarnings.m4 because they were + # already listed in build-aux/gcc-warning.spec; this includes those + # that are implied by -Wall. + gl_MANYWARN_COMPLEMENT([remaining_undesired_warning_options], + [$nw], [$possible_warning_options]) + + # Add the desired warning options to WARN_CFLAGS. + for w in $desired_warning_options; do gl_WARN_ADD([$w]) done - # Disable unwanted warnings enabled by default, -Wall, -Wextra. - gl_WARN_ADD([-Wno-sign-compare]) # Too many false alarms. + # Add the opposites of the remaining undesired warning options to + # WARN_CFLAGS. + for w in `echo "$remaining_undesired_warning_options" | sed -e 's/-W/-Wno-/g'`; do + gl_WARN_ADD([$w]) + done ]) @end smallexample This module sets up many GCC warning options. -When you start to use it, you can set the -list of undesired warnings (@samp{nw} in the example above) to empty, and -compile the package with all possible warnings enabled. 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 but fix your code to silence the warning instead. - -Many GCC warning options 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 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. + +When you use it for the first time, it is common practice to do it as +follows: + +@itemize @bullet +@item +Start with the newest major release of GCC. +This will save you time, because some warning options produce many false +alarms with older versions of GCC (such as @code{-Wstrict-overflow} or +@code{-Wunsafe-loop-optimizations}). +@item +Compile the package with an empty @code{nw} value, that is, with all +possible warnings enabled. +Do this once with optimizations (@code{CPPFLAGS=-O2}) and once with no +optimizations (@code{CPPFLAGS=-O0} or @code{CPPFLAGS=-ggdb}). +The exercise with optimizations will catch more bugs, because the +compiler does a better static analysis of the program when optimizing. +Also, some warning options that diagnose suboptimal code generation, +such as @code{-Winline}, are not effective when not optimizing. +On the other hand, it's frequent to build the package without +optimizations, for debugging purposes, and you don't want to see +undesired warnings in these phases of development either. +@item +Then you will go through the list of warnings. +Since there are likely many warnings, the first time, it's a good idea +to sort them by warning option first: +@smallexample +$ grep warning: make-output.log \ + | sed -e 's/^\(.*\) \[\(-W.*\)\]$/\2 \1/' | sort -k1 +@end smallexample +@item +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 but fix your code to silence the warning +instead. + +Many GCC warning options 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 warning option pinpoints real bugs occasionally, but it also +whines about a few code locations which are fine, we recommend to leave +the warning option enabled. +Whether you then live with the remaining few warnings, or choose to +disable them one-by-one through +@code{#pragma GCC diagnostic ignored "@var{option}"} +(@pxref{Diagnostic Pragmas,,, gcc, Using the GNU Compiler Collection}, +@url{https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Pragmas.html}), +is again a project management decision. +@end itemize + +When a new major version of GCC is released, the Gnulib maintainers add +the newly available warning options into the @code{gl_MANYWARN_ALL_GCC} +macro. +You will then enjoy the benefits of the new warnings, simply by updating +to the newest Gnulib. +If some of the new warnings are undesired, you can add them to the +@samp{nw} variable, as described above. Comments on particular warning flags: