gnulib/doc/transversal.texi

@node Modules that modify the way other modules work
@section 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:
@itemize
@item
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.
@item
A module can indicate support for particular behaviours.  For example,
Gnulib has a module @samp{sigpipe} that requests POSIX compatible
SIGPIPE behaviour from all other modules -- something that is not
enabled by default.  Or consider the @samp{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.
@item
A module can indicate to other modules that they can rely on certain
guarantees, and thus omit specific code.  For example, when Gnulib's
@samp{malloc-gnu} module is present, you can omit code that test
@code{n} against zero when you call @code{malloc (n)}.
@end itemize

Be aware that these advanced techniques likely cause breakage in the
situation of multiple @code{gnulib-tool} invocations in the scope of a
single @code{configure} file.  This is because the question ``is module
B present?'' does not have a unique answer in such situations.
@code{gnulib-tool} has support for these techniques in the situation of
@code{--create-testdir --single-configure}, which basically has two
@code{gnulib-tool} invocations, one for a set of modules that end up in
@code{gllib}, and one for the set of modules that end up in
@code{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 @code{gltests}, should it have an
effect on the modules in @code{gllib}?''

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

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

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

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