doc/manywarnings.texi

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