doc/transversal.texi

   1 @node Modules that modify the way other modules work
   2 @section Modules that modify the way other modules work
   3
   4 The normal way to design modules is that each module has its own code,
   5 and the module dependencies provide the facilities on which this code
   6 can rely.  But sometimes it is necessary to use more advanced
   7 techniques.  For example:
   8 @itemize
   9 @item
  10 You may want to have optional module dependencies: Let module A use
  11 facilities provided by module B, if module B is present, but without
  12 requiring that module B is present.
  13 @item
  14 A module can indicate support for particular behaviours.  For example,
  15 Gnulib has a module @samp{sigpipe} that requests POSIX compatible
  16 SIGPIPE behaviour from all other modules -- something that is not
  17 enabled by default.  Or consider the @samp{nonblocking} module, that is
  18 an indicator that all I/O functions should handle non-blocking file
  19 descriptors -- something that, equally, is not enabled by default.
  20 @item
  21 A module can indicate to other modules that they can rely on certain
  22 guarantees, and thus omit specific code.  For example, when Gnulib's
  23 @samp{malloc-gnu} module is present, you can omit code that test
  24 @code{n} against zero when you call @code{malloc (n)}.
  25 @end itemize
  26
  27 Be aware that these advanced techniques likely cause breakage in the
  28 situation of multiple @code{gnulib-tool} invocations in the scope of a
  29 single @code{configure} file.  This is because the question ``is module
  30 B present?'' does not have a unique answer in such situations.
  31 @code{gnulib-tool} has support for these techniques in the situation of
  32 @code{--create-testdir --single-configure}, which basically has two
  33 @code{gnulib-tool} invocations, one for a set of modules that end up in
  34 @code{gllib}, and one for the set of modules that end up in
  35 @code{gltests}.  But you should be aware that this does not cover the
  36 general situation.
  37
  38 Which technique to use, depends on the answer to the question: ``If my
  39 module occurs among the modules of @code{gltests}, should it have an
  40 effect on the modules in @code{gllib}?''
  41
  42 If the answer is ``no'', your module description should invoke the
  43 Autoconf macro @code{gl_MODULE_INDICATOR}.  This Autoconf macro takes
  44 one argument: the name of your module.  The effect of
  45 @code{gl_MODULE_INDICATOR([@var{my-module}])} is to define, in
  46 @code{config.h}, a C macro @code{GNULIB_@var{MY_MODULE}} that indicates
  47 whether your macro is considered to be present.  This works even when
  48 your macro is used in @code{gltests}: @code{GNULIB_@var{MY_MODULE}}
  49 will then evaluate to 1 in @code{gltests} but to 0 in @code{gllib}.
  50
  51 If the answer is ``yes'', you have two techniques available.  The first
  52 one is to invoke a similar Autoconf macro, named
  53 @code{gl_MODULE_INDICATOR_FOR_TESTS}.  It works similarly.  However,
  54 when your macro is used in @code{gltests}, @code{GNULIB_@var{MY_MODULE}}
  55 will evaluate to 1 both in @code{gltests} and in @code{gllib}.
  56
  57 The second one is to define a shell variable in the @code{configure}
  58 file that tells whether your module is present, through use of
  59 @code{m4_divert_text}.  The Autoconf macros of a dependency module will
  60 initialize this shell variable, through
  61 @samp{m4_divert_text([DEFAULTS], [@var{my_shell_var}=no])}.  The
  62 Autoconf macros of your module will override this value, through
  63 @samp{m4_divert_text([INIT_PREPARE], [@var{my_shell_var}=yes])}.  Then
  64 you can use @code{@var{my_shell_var}} in the Autoconf macros of both
  65 modules.  You can find more details about this technique in the Gnulib
  66 module @code{getopt-gnu}.
  67
  68 Reminder: These techniques are advanced.  They have the potential to
  69 cause lots of headaches if you apply them incorrectly.