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