Modules that modify the way other modules work
==============================================

The normal way to design modules is that each module has its own code, and the module dependencies provide the facilities on which this code can rely.  But sometimes it is necessary to use more advanced techniques.  For example:

  * You may want to have optional module dependencies: Let module A use facilities provided by module B, if module B is present, but without requiring that module B is present.

  * A module can indicate support for particular behaviours.  For example, Gnulib has a module sigpipe that requests POSIX compatible SIGPIPE behaviour from all other modules -- something that is not enabled by default.  Or consider the nonblocking module, that is an indicator that all I/O functions should handle non-blocking file descriptors -- something that, equally, is not enabled by default.

  * A module can indicate to other modules that they can rely on certain guarantees, and thus omit specific code.  For example, when Gnulib's malloc-gnu module is present, you can omit code that test n against zero when you call malloc (n).

Be aware that these advanced techniques likely cause breakage in the situation of multiple gnulib-tool invocations in the scope of a single configure file.  This is because the question ``is module B present?'' does not have a unique answer in such situations. gnulib-tool has support for these techniques in the situation of --create-testdir --single-configure, which basically has two gnulib-tool invocations, one for a set of modules that end up in gllib, and one for the set of modules that end up in gltests.  But you should be aware that this does not cover the general situation.

Which technique to use, depends on the answer to the question: ``If my module occurs among the modules of gltests, should it have an effect on the modules in gllib?''

If the answer is ``no'', your module description should invoke the Autoconf macro gl_MODULE_INDICATOR.  This Autoconf macro takes one argument: the name of your module.  The effect of gl_MODULE_INDICATOR([MY-MODULE]) is to define, in config.h, a C macro GNULIB_MY_MODULE that indicates whether your macro is considered to be present.  This works even when your macro is used in gltests: GNULIB_MY_MODULE will then evaluate to 1 in gltests but to 0 in gllib.

If the answer is ``yes'', you have two techniques available.  The first one is to invoke a similar Autoconf macro, named gl_MODULE_INDICATOR_FOR_TESTS.  It works similarly.  However, when your macro is used in gltests, GNULIB_MY_MODULE will evaluate to 1 both in gltests and in gllib.

The second one is to define a shell variable in the configure file that tells whether your module is present, through use of m4_divert_text.  The Autoconf macros of a dependency module will initialize this shell variable, through m4_divert_text([DEFAULTS], [MY_SHELL_VAR=no]).  The Autoconf macros of your module will override this value, through m4_divert_text([INIT_PREPARE], [MY_SHELL_VAR=yes]).  Then you can use MY_SHELL_VAR in the Autoconf macros of both modules.  You can find more details about this technique in the Gnulib module getopt-gnu.

Reminder: These techniques are advanced.  They have the potential to cause lots of headaches if you apply them incorrectly.