manywarnings: Overhaul documentation.
authorBruno Haible <bruno@clisp.org>
Sun, 4 Jun 2023 22:16:40 +0000 (00:16 +0200)
committerBruno Haible <bruno@clisp.org>
Sun, 4 Jun 2023 22:16:40 +0000 (00:16 +0200)
* 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.

ChangeLog
doc/manywarnings.texi

index eea4e172514ea6a719a89e145b58cae4bfb91c9f..9a30a0fb8a13c9f67e901a85ee662f094b051b69 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2023-06-04  Bruno Haible  <bruno@clisp.org>
+
+       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  <bruno@clisp.org>
 
        error: Fix support for library namespacing (regression 2023-05-27).
index 01e23116cc12a75d8b45e3f3605d664e2f486251..19b58f8e47bfd571f963ebec0991aa701d5ff19c 100644 (file)
@@ -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: