| @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} (without option @code{--two-configures}), | |
| 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. |