Mercurial > gnulib

annotate doc/transversal.texi @ 40196:e63f5d3edab5

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
relocatable-prog: Update documentation. * doc/relocatable-maint.texi (Supporting Relocation): Update to match the recent changes.
author Bruno Haible <bruno@clisp.org>
date Sun, 24 Feb 2019 01:49:15 +0100
parents 99c5c7bed4f9
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
18877
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
1 @node Modules that modify the way other modules work
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
2 @section Modules that modify the way other modules work
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
3
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
4 The normal way to design modules is that each module has its own code,
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
5 and the module dependencies provide the facilities on which this code
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
6 can rely. But sometimes it is necessary to use more advanced
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
7 techniques. For example:
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
8 @itemize
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
9 @item
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
10 You may want to have optional module dependencies: Let module A use
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
11 facilities provided by module B, if module B is present, but without
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
12 requiring that module B is present.
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
13 @item
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
14 A module can indicate support for particular behaviours. For example,
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
15 Gnulib has a module @samp{sigpipe} that requests POSIX compatible
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
16 SIGPIPE behaviour from all other modules -- something that is not
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
17 enabled by default. Or consider the @samp{nonblocking} module, that is
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
18 an indicator that all I/O functions should handle non-blocking file
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
19 descriptors -- something that, equally, is not enabled by default.
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
20 @item
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
21 A module can indicate to other modules that they can rely on certain
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
22 guarantees, and thus omit specific code. For example, when Gnulib's
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
23 @samp{malloc-gnu} module is present, you can omit code that test
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
24 @code{n} against zero when you call @code{malloc (n)}.
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
25 @end itemize
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
26
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
27 Be aware that these advanced techniques likely cause breakage in the
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
28 situation of multiple @code{gnulib-tool} invocations in the scope of a
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
29 single @code{configure} file. This is because the question ``is module
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
30 B present?'' does not have a unique answer in such situations.
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
31 @code{gnulib-tool} has support for these techniques in the situation of
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
32 @code{--create-testdir --single-configure}, which basically has two
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
33 @code{gnulib-tool} invocations, one for a set of modules that end up in
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
34 @code{gllib}, and one for the set of modules that end up in
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
35 @code{gltests}. But you should be aware that this does not cover the
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
36 general situation.
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
37
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
38 Which technique to use, depends on the answer to the question: ``If my
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
39 module occurs among the modules of @code{gltests}, should it have an
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
40 effect on the modules in @code{gllib}?''
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
41
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
42 If the answer is ``no'', your module description should invoke the
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
43 Autoconf macro @code{gl_MODULE_INDICATOR}. This Autoconf macro takes
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
44 one argument: the name of your module. The effect of
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
45 @code{gl_MODULE_INDICATOR([@var{my-module}])} is to define, in
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
46 @code{config.h}, a C macro @code{GNULIB_@var{MY_MODULE}} that indicates
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
47 whether your macro is considered to be present. This works even when
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
48 your macro is used in @code{gltests}: @code{GNULIB_@var{MY_MODULE}}
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
49 will then evaluate to 1 in @code{gltests} but to 0 in @code{gllib}.
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
50
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
51 If the answer is ``yes'', you have two techniques available. The first
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
52 one is to invoke a similar Autoconf macro, named
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
53 @code{gl_MODULE_INDICATOR_FOR_TESTS}. It works similarly. However,
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
54 when your macro is used in @code{gltests}, @code{GNULIB_@var{MY_MODULE}}
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
55 will evaluate to 1 both in @code{gltests} and in @code{gllib}.
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
56
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
57 The second one is to define a shell variable in the @code{configure}
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
58 file that tells whether your module is present, through use of
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
59 @code{m4_divert_text}. The Autoconf macros of a dependency module will
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
60 initialize this shell variable, through
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
61 @samp{m4_divert_text([DEFAULTS], [@var{my_shell_var}=no])}. The
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
62 Autoconf macros of your module will override this value, through
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
63 @samp{m4_divert_text([INIT_PREPARE], [@var{my_shell_var}=yes])}. Then
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
64 you can use @code{@var{my_shell_var}} in the Autoconf macros of both
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
65 modules. You can find more details about this technique in the Gnulib
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
66 module @code{getopt-gnu}.
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
67
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
68 Reminder: These techniques are advanced. They have the potential to
99c5c7bed4f9 Prepare for reordering sections in the manual.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
69 cause lots of headaches if you apply them incorrectly.