doc about modules that modify the way other modules work

[Bruno Haible]

2017-04-23  Bruno Haible  <address@hidden>

        doc: New section "Modules that modify the way other modules work".
        * doc/gnulib.texi (Modules that modify the way other modules work): New
        section.

diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index b2defc0..ea7710c 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -723,6 +723,7 @@ better to share them.
 * Out of memory handling::
 * Obsolete modules::
 * Extra tests modules::
+* Modules that modify the way other modules work::
 * A C++ namespace for gnulib::      A different way of using Gnulib in C++
 * Library version handling::
 * Windows sockets::
@@ -870,6 +871,77 @@ from @code{foo-tests} to @code{foo-extra-tests}, and mark 
the
 @code{foo-extra-tests} with the particular status attribute.
 
 
address@hidden Modules that modify the way other modules work
address@hidden 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:
address@hidden
address@hidden
+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.
address@hidden
+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.
address@hidden
+A module can indicate to other modules that they can rely on certain
+guarantees, and thus omit specific code.  For example, when Gnulib's
address@hidden module is present, you can omit code that test
address@hidden against zero when you call @code{malloc (n)}.
address@hidden 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.
address@hidden has support for these techniques in the situation of
address@hidden --single-configure}, which basically has two
address@hidden invocations, one for a set of modules that end up in
address@hidden, and one for the set of modules that end up in
address@hidden  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
address@hidden(address@hidden)} is to define, in
address@hidden, a C macro @address@hidden that indicates
+whether your macro is considered to be present.  This works even when
+your macro is used in @code{gltests}: @address@hidden
+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
address@hidden  It works similarly.  However,
+when your macro is used in @code{gltests}, @address@hidden
+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
address@hidden  The Autoconf macros of a dependency module will
+initialize this shell variable, through
address@hidden([DEFAULTS], address@hidden)}.  The
+Autoconf macros of your module will override this value, through
address@hidden([INIT_PREPARE], address@hidden)}.  Then
+you can use @address@hidden 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.
+
+
 @node A C++ namespace for gnulib
 @section A C++ namespace for gnulib