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 allows to 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 @end itemize
  29
  30 To use this module, you need the following:
  31
  32 @enumerate
  33 @item
  34 In @file{configure.ac}, use for example
  35 @smallexample
  36 gl_WARN_ADD([-Wall], [WARN_CFLAGS])
  37 gl_WARN_ADD([-Wpointer-arith], [WARN_CFLAGS])
  38 @end smallexample
  39
  40 @item
  41 In the directories which shall use @code{WARN_CFLAGS}, use it in the
  42 definition of @code{AM_CFLAGS}, like this:
  43 @smallexample
  44 AM_CFLAGS = $(WARN_CFLAGS)
  45 @end smallexample
  46
  47 Note that the @code{AM_CFLAGS} is used in combination with @code{CFLAGS}
  48 and before @code{CFLAGS} in build rules emitted by Automake.  This allows
  49 the user to provide @code{CFLAGS} that override the @code{WARN_CFLAGS}.
  50 @end enumerate
  51
  52 Note that it is a bad idea to use @samp{gl_WARN_ADD([-Werror])}.  The
  53 warnings emitted by GCC depend, to some extent, on the contents of the
  54 system header files, on the size and signedness of built-in types, etc.
  55 Use of @samp{-Werror} would cause frustration to all users on platforms
  56 that the maintainer has not tested before the release.  It is better if
  57 maintainers use @samp{-Werror} only for themselves (for example, during
  58 @samp{make distcheck}, as mentioned above).