doc/warnings.texi

   1 @node warnings
   2 @section warnings
   3
   4 @mindex warnings
   5 @mindex manywarnings
   6 The @code{warnings} module allows to regularly build a package with more
   7 GCC warnings than the default warnings emitted by GCC.  It is often used
   8 indirectly through the @code{manywarnings} module
   9 (@pxref{manywarnings}).
  10
  11 It provides the following functionality:
  12
  13 @itemize @bullet
  14 @item
  15 You can select some warning options, such as @samp{-Wall}, to be enabled
  16 whenever building with a GCC version that supports these options.  The
  17 user can choose to override these warning options by providing the
  18 opposite options in the @code{CFLAGS} variable at configuration time.
  19
  20 @item
  21 You can make these warnings apply to selected directories only.  In
  22 projects where subprojects are maintained by different people, or where
  23 parts of the source code are imported from external sources (for example
  24 from gnulib), it is useful to apply different warning options to
  25 different directories.
  26
  27 @item
  28 It lets you use @samp{-Werror} at @samp{make distcheck} time, to verify
  29 that on the maintainer's system, no warnings remain.  (Note that use of
  30 @samp{-Werror} in @code{CFLAGS} does not work in general, because it may
  31 break autoconfiguration.)
  32
  33 @item
  34 Similarly, it lets you use @samp{-Werror} when the builder runs
  35 @command{configure} with an option such as
  36 @option{--enable-gcc-warnings}.
  37 @end itemize
  38
  39 To use this module, you need the following:
  40
  41 @enumerate
  42 @item
  43 In @file{configure.ac}, use for example
  44 @smallexample
  45 gl_WARN_ADD([-Wall], [WARN_CFLAGS])
  46 gl_WARN_ADD([-Wpointer-arith], [WARN_CFLAGS])
  47 @end smallexample
  48
  49 @item
  50 In the directories which shall use @code{WARN_CFLAGS}, use it in the
  51 definition of @code{AM_CFLAGS}, like this:
  52 @smallexample
  53 AM_CFLAGS = $(WARN_CFLAGS)
  54 @end smallexample
  55
  56 Note that the @code{AM_CFLAGS} is used in combination with @code{CFLAGS}
  57 and before @code{CFLAGS} in build rules emitted by Automake.  This allows
  58 the user to provide @code{CFLAGS} that override the @code{WARN_CFLAGS}.
  59 @end enumerate
  60
  61 @samp{gl_WARN_ADD([-Werror])} is intended for developers, and should be
  62 avoided in contexts where it would affect ordinary installation builds.  The
  63 warnings emitted by GCC depend, to some extent, on the contents of the
  64 system header files, on the size and signedness of built-in types, etc.
  65 Use of @samp{-Werror} would cause frustration to all users on platforms
  66 that the maintainer has not tested before the release.  It is better if
  67 @samp{-Werror} is off by default, and is enabled only by developers.
  68 For example, @samp{-Werror} could affect @samp{make distcheck} or
  69 @samp{configure --enable-gcc-warnings} as mentioned above.