2017-04-23 Bruno Haible <br...@clisp.org>
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.
+@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.
+
+
@node A C++ namespace for gnulib
@section A C++ namespace for gnulib
