doc/manywarnings.texi

   1 @node manywarnings
   2 @section manywarnings
   3
   4 The @code{manywarnings} module enables many GCC warnings for your
   5 package.  Here is an example use:
   6
   7 @smallexample
   8 AC_ARG_ENABLE([gcc-warnings],
   9   [AS_HELP_STRING([[--enable-gcc-warnings[=TYPE]]],
  10     [control generation of GCC warnings.  The TYPE 'no' disables
  11      warnings; 'yes' (default) generates cheap warnings;
  12      'expensive' in addition generates expensive warnings.])])
  13
  14 AS_IF([test "$enable_gcc_warnings" != no],
  15   [
  16    # Set up the list of unwanted warning options.
  17    nw=
  18    if test "$enable_gcc_warnings" != expensive; then
  19      nw="$nw -fanalyzer"
  20    fi
  21    nw="$nw -Wbad-function-cast" # Casting a function's result is not more
  22                                 # dangerous than casting any other value.
  23    nw="$nw -Winline"            # It's OK to not inline.
  24    nw="$nw -Wsign-compare"      # Too many false alarms.
  25    nw="$nw -Wstrict-overflow"   # It's OK to optimize strictly.
  26    nw="$nw -Wsystem-headers"    # Don't warn in system headers.
  27
  28    # Setup the list of meaningful warning options for the C compiler.
  29    # The list comes from manywarnings.m4. Warning options that are not
  30    # generally meaningful have already been filtered out (cf.
  31    # build-aux/gcc-warning.spec).
  32    gl_MANYWARN_ALL_GCC([possible_warning_options])
  33
  34    # Compute the list of warning options that are desired.
  35    gl_MANYWARN_COMPLEMENT([desired_warning_options],
  36                           [$possible_warning_options], [$nw])
  37    # Compute the list of remaining undesired warning options.
  38    # Namely those, that were not in manywarnings.m4 because they were
  39    # already listed in build-aux/gcc-warning.spec; this includes those
  40    # that are implied by -Wall.
  41    gl_MANYWARN_COMPLEMENT([remaining_undesired_warning_options],
  42                           [$nw], [$possible_warning_options])
  43
  44    # Add the desired warning options to WARN_CFLAGS.
  45    for w in $desired_warning_options; do
  46      gl_WARN_ADD([$w])
  47    done
  48
  49    # Add the opposites of the remaining undesired warning options to
  50    # WARN_CFLAGS.
  51    for w in `echo "$remaining_undesired_warning_options" | sed -e 's/-W/-Wno-/g'`; do
  52      gl_WARN_ADD([$w])
  53    done
  54 ])
  55 @end smallexample
  56
  57 This module sets up many GCC warning options.
  58
  59 When you use it for the first time, it is common practice to do it as
  60 follows:
  61
  62 @itemize @bullet
  63 @item
  64 Start with the newest major release of GCC.
  65 This will save you time, because some warning options produce many false
  66 alarms with older versions of GCC (such as @code{-Wstrict-overflow} or
  67 @code{-Wunsafe-loop-optimizations}).
  68 @item
  69 Consider the platforms commonly used when enabling GCC warnings.
  70 This includes not only target architectures and operating systems, but also
  71 optimization options, which can greatly affect the warnings generated.
  72 Makefiles generated by @code{configure} default to @option{-O2} optimization.
  73 If you also commonly build with @option{-O0} or other optimization options,
  74 you can compile again with those options.
  75 Using more optimizations catches more bugs, because the compiler does
  76 a better static analysis of the program when optimizing more.
  77 Also, some warning options that diagnose suboptimal code generation,
  78 such as @code{-Winline}, are not effective when not optimizing.
  79 On the other hand, if it's frequent to build the package with warnings but
  80 without optimizations, for debugging purposes, then you don't want to see
  81 undesired warnings in these phases of development either.
  82 @item
  83 Compile the package with an empty @code{nw} value, that is, with all
  84 possible warnings enabled.
  85 @item
  86 Then you will go through the list of warnings.
  87 Since there are likely many warnings, the first time, it's a good idea
  88 to sort them by warning option first:
  89 @smallexample
  90 $ grep warning: make-output.log \
  91   | sed -e 's/^\(.*\) \[\(-W.*\)\]$/\2  \1/' | sort -k1
  92 @end smallexample
  93 @item
  94 You will likely deactivate warnings that occur often and don't point to
  95 mistakes in the code, by adding them to the @samp{nw} variable, then
  96 reconfiguring and recompiling.
  97 When warnings point to real mistakes and bugs in the code, you will of
  98 course not disable them but fix your code to silence the warning
  99 instead.
 100
 101 Many GCC warning options usually don't point to mistakes in the code;
 102 these warnings enforce a certain programming style.
 103 It is a project management decision whether you want your code to follow
 104 any of these styles.
 105 Note that some of these programming styles are conflicting.
 106 You cannot have them all; you have to choose among them.
 107
 108 When a warning option pinpoints real bugs occasionally, but it also
 109 whines about a few code locations which are fine, we recommend to leave
 110 the warning option enabled.
 111 Whether you then live with the remaining few warnings, or choose to
 112 disable them one-by-one through
 113 @code{#pragma GCC diagnostic ignored "@var{option}"}
 114 (@pxref{Diagnostic Pragmas,,, gcc, Using the GNU Compiler Collection},
 115 @url{https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Pragmas.html}),
 116 is again a project management decision.
 117 @end itemize
 118
 119 When a new major version of GCC is released, the Gnulib maintainers add
 120 the newly available warning options into the @code{gl_MANYWARN_ALL_GCC}
 121 macro.
 122 You will then enjoy the benefits of the new warnings, simply by updating
 123 to the newest Gnulib.
 124 If some of the new warnings are undesired, you can add them to the
 125 @samp{nw} variable, as described above.
 126
 127 Comments on particular warning flags:
 128
 129 @table @samp
 130
 131 @item -fanalyzer
 132 The @code{manywarnings} module by default uses GCC's
 133 @option{-fanalyzer} option, as this issues some useful warnings.
 134 (It can also help GCC generate better code.)
 135 However, @code{-fanalyzer} can greatly slow down compilation,
 136 and in programs with large modules it can be so slow as to be unusable,
 137 so it is common for @command{configure} to disable it unless
 138 @command{configure} is given an option like
 139 @option{--enable-gcc-warnings=expensive}.
 140
 141 @item -fstrict-aliasing
 142 Although the @code{manywarnings} module does not enable GCC's
 143 @option{-fstrict-aliasing} option, it is enabled by default if you
 144 compile with @code{-O2} or higher optimization, and can help GCC
 145 generate better warnings.
 146
 147 @item -Wanalyzer-malloc-leak
 148 The @code{-fanalyzer} option generates many false alarms about
 149 @code{malloc} leaks, which @code{manywarnings} suppresses by also
 150 using @option{-Wno-analyzer-malloc-leak}.
 151
 152 @item -fstrict-flex-arrays
 153 The @code{manywarnings} module by default uses GCC's
 154 @option{-fstrict-flex-arrays} option if available, so that GCC can
 155 warn about nonportable usage of flexible array members.
 156 In a few cases this can help GCC generate better code,
 157 so it is not strictly a warning option.
 158
 159 @item -Wsign-compare
 160 GCC and Clang generate too many false alarms with @option{-Wsign-compare},
 161 and we don't recommend that warning.  You can disable it by using
 162 @code{gl_WARN_ADD([-Wno-sign-compare])} as illustrated above.
 163 Programs using Gnulib generally don't enable
 164 that warning when compiling Gnulib code.  If you happen to find a real
 165 bug with that warning we'd like to know it.
 166
 167 @end table