doc/warnings.texi

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