Mercurial > gnulib
annotate doc/gnulib-tool.texi @ 39223:c2e83c6de345
doc: Mention another prerequisite for using Gnulib.
Reported at <https://stackoverflow.com/questions/48378214/>.
* doc/gnulib-tool.texi (Initial import): Mention requirement to use
AC_CONFIG_HEADERS.
| author | Bruno Haible <bruno@clisp.org> |
|---|---|
| date | Tue, 23 Jan 2018 09:13:13 +0100 |
| parents | 24e347e0e326 |
| children | 73f0573be7ff |
| rev | line source |
|---|---|
| 25946 | 1 @node Invoking gnulib-tool |
| 2 @chapter Invoking gnulib-tool | |
| 3 | |
|
39199
24e347e0e326
maint: Run 'make update-copyright'
Paul Eggert <eggert@cs.ucla.edu>
parents:
39179
diff
changeset
|
4 @c Copyright (C) 2005-2018 Free Software Foundation, Inc. |
|
26830
61f91ddc6d5a
Add copyright notices to long-enough files that lack them, since
Paul Eggert <eggert@cs.ucla.edu>
parents:
26768
diff
changeset
|
5 |
|
61f91ddc6d5a
Add copyright notices to long-enough files that lack them, since
Paul Eggert <eggert@cs.ucla.edu>
parents:
26768
diff
changeset
|
6 @c Permission is granted to copy, distribute and/or modify this document |
|
30453
655d9a8243af
Change license to GFDLv1.3+.
Simon Josefsson <simon@josefsson.org>
parents:
29942
diff
changeset
|
7 @c under the terms of the GNU Free Documentation License, Version 1.3 or |
|
26830
61f91ddc6d5a
Add copyright notices to long-enough files that lack them, since
Paul Eggert <eggert@cs.ucla.edu>
parents:
26768
diff
changeset
|
8 @c any later version published by the Free Software Foundation; with no |
|
37647
dced390b399a
doc: update FDL template to match FDL examples.
Simon Josefsson <simon@josefsson.org>
parents:
37528
diff
changeset
|
9 @c Invariant Sections, no Front-Cover Texts, and no Back-Cover |
|
26830
61f91ddc6d5a
Add copyright notices to long-enough files that lack them, since
Paul Eggert <eggert@cs.ucla.edu>
parents:
26768
diff
changeset
|
10 @c Texts. A copy of the license is included in the ``GNU Free |
|
61f91ddc6d5a
Add copyright notices to long-enough files that lack them, since
Paul Eggert <eggert@cs.ucla.edu>
parents:
26768
diff
changeset
|
11 @c Documentation License'' file as part of this distribution. |
|
61f91ddc6d5a
Add copyright notices to long-enough files that lack them, since
Paul Eggert <eggert@cs.ucla.edu>
parents:
26768
diff
changeset
|
12 |
| 25946 | 13 @pindex gnulib-tool |
| 14 @cindex invoking @command{gnulib-tool} | |
| 15 | |
|
26533
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
16 The @command{gnulib-tool} command is the recommended way to import |
|
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
17 Gnulib modules. It is possible to borrow Gnulib modules in a package |
|
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
18 without using @command{gnulib-tool}, relying only on the |
|
26636
c135538476a8
* functions.texi, gnulib-tool.texi, gnulib.texi: Fix some typos.
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
26533
diff
changeset
|
19 meta-information stored in the @file{modules/*} files, but with a |
|
26533
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
20 growing number of modules this becomes tedious. @command{gnulib-tool} |
|
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
21 simplifies the management of source files, @file{Makefile.am}s and |
|
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
22 @file{configure.ac} in packages incorporating Gnulib modules. |
| 25946 | 23 |
|
31135
bab1ea6241d7
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
30520
diff
changeset
|
24 @file{gnulib-tool} is not installed in a standard directory that is |
|
bab1ea6241d7
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
30520
diff
changeset
|
25 contained in the @code{PATH} variable. It needs to be run directly in |
|
bab1ea6241d7
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
30520
diff
changeset
|
26 the directory that contains the Gnulib source code. You can do this |
|
bab1ea6241d7
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
30520
diff
changeset
|
27 either by specifying the absolute filename of @file{gnulib-tool}, or |
|
bab1ea6241d7
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
30520
diff
changeset
|
28 you can also use a symbolic link from a place inside your @code{PATH} |
|
bab1ea6241d7
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
30520
diff
changeset
|
29 to the @file{gnulib-tool} file of your preferred and most up-to-date |
|
bab1ea6241d7
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
30520
diff
changeset
|
30 Gnulib checkout, like this: |
|
bab1ea6241d7
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
30520
diff
changeset
|
31 @smallexample |
|
bab1ea6241d7
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
30520
diff
changeset
|
32 $ ln -s $HOME/gnu/src/gnulib.git/gnulib-tool $HOME/bin/gnulib-tool |
|
bab1ea6241d7
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
30520
diff
changeset
|
33 @end smallexample |
|
bab1ea6241d7
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
30520
diff
changeset
|
34 |
|
26533
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
35 Run @samp{gnulib-tool --help} for information. To get familiar with |
|
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
36 @command{gnulib-tool} without affecting your sources, you can also try |
|
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
37 some commands with the option @samp{--dry-run}; then |
|
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
38 @code{gnulib-tool} will only report which actions it would perform in |
|
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
39 a real run without changing anything. |
| 25946 | 40 |
| 41 @menu | |
|
32567
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
42 * Which modules?:: Determining the needed set of Gnulib modules |
| 25946 | 43 * Initial import:: First import of Gnulib modules. |
| 44 * Modified imports:: Changing the import specification. | |
| 45 * Simple update:: Tracking Gnulib development. | |
|
29103
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
46 * Source changes:: Impact of Gnulib on your source files. |
|
39179
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
47 * Modified build rules:: Modifying the build rules of a Gnulib import |
| 39178 | 48 * Multiple instances:: Using Gnulib for both a library and a program |
|
29499
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
49 * gettextize and autopoint:: Caveat: @code{gettextize} and @code{autopoint} users! |
|
29258
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
50 * Localization:: Handling Gnulib's own message translations. |
|
28981
74c961c83b76
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
28955
diff
changeset
|
51 * VCS Issues:: Integration with Version Control Systems. |
| 30520 | 52 * Unit tests:: Bundling the unit tests of the Gnulib modules. |
|
34524
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
53 * Conditional dependencies:: Avoiding unnecessary checks and compilations. |
| 25946 | 54 @end menu |
| 55 | |
| 56 | |
|
32567
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
57 @node Which modules? |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
58 @section Finding modules |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
59 @cindex Finding modules |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
60 |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
61 There are three ways of finding the names of Gnulib modules that you can use |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
62 in your package: |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
63 |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
64 @itemize |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
65 @item |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
66 You have the complete module list, sorted according to categories, in |
|
38843
fe6f0f324ef9
doc: Prefer https URLs where possible.
Bruno Haible <bruno@clisp.org>
parents:
38491
diff
changeset
|
67 @url{https://www.gnu.org/software/gnulib/MODULES.html}. |
|
32567
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
68 |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
69 @item |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
70 If you are looking for a particular POSIX header or function replacement, |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
71 look in the chapters @ref{Header File Substitutes} and |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
72 @ref{Function Substitutes}. For headers and functions that are provided by |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
73 Glibc but not standardized by POSIX, look in the chapters |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
74 @ref{Glibc Header File Substitutes} and @ref{Glibc Function Substitutes}. |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
75 |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
76 @item |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
77 If you have already found the source file in Gnulib and are looking for the |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
78 module that contains this source file, you can use the command |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
79 @samp{gnulib-tool --find @var{filename}}. |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
80 @end itemize |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
81 |
|
cd80080a8294
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
32250
diff
changeset
|
82 |
| 25946 | 83 @node Initial import |
| 84 @section Initial import | |
| 85 @cindex initial import | |
| 86 | |
| 32595 | 87 Gnulib assumes that your project uses Autoconf. When using Gnulib, you |
|
38408
16b1e35e18fa
gnulib-tool: new option --gnu-make
Paul Eggert <eggert@cs.ucla.edu>
parents:
38305
diff
changeset
|
88 will need to have Autoconf among your build tools. |
|
16b1e35e18fa
gnulib-tool: new option --gnu-make
Paul Eggert <eggert@cs.ucla.edu>
parents:
38305
diff
changeset
|
89 |
|
39223
c2e83c6de345
doc: Mention another prerequisite for using Gnulib.
Bruno Haible <bruno@clisp.org>
parents:
39199
diff
changeset
|
90 Gnulib also assumes that your project's @file{configure.ac} contains the |
|
c2e83c6de345
doc: Mention another prerequisite for using Gnulib.
Bruno Haible <bruno@clisp.org>
parents:
39199
diff
changeset
|
91 line |
|
c2e83c6de345
doc: Mention another prerequisite for using Gnulib.
Bruno Haible <bruno@clisp.org>
parents:
39199
diff
changeset
|
92 @smallexample |
|
c2e83c6de345
doc: Mention another prerequisite for using Gnulib.
Bruno Haible <bruno@clisp.org>
parents:
39199
diff
changeset
|
93 AC_CONFIG_HEADERS([config.h]) |
|
c2e83c6de345
doc: Mention another prerequisite for using Gnulib.
Bruno Haible <bruno@clisp.org>
parents:
39199
diff
changeset
|
94 @end smallexample |
|
c2e83c6de345
doc: Mention another prerequisite for using Gnulib.
Bruno Haible <bruno@clisp.org>
parents:
39199
diff
changeset
|
95 The @file{config.h} file gets generated with platform dependent C macro |
|
c2e83c6de345
doc: Mention another prerequisite for using Gnulib.
Bruno Haible <bruno@clisp.org>
parents:
39199
diff
changeset
|
96 definitions, and the source files include it (see @ref{Source changes}). |
|
c2e83c6de345
doc: Mention another prerequisite for using Gnulib.
Bruno Haible <bruno@clisp.org>
parents:
39199
diff
changeset
|
97 |
|
38408
16b1e35e18fa
gnulib-tool: new option --gnu-make
Paul Eggert <eggert@cs.ucla.edu>
parents:
38305
diff
changeset
|
98 Unless you use @command{gnulib-tool}'s @option{--gnu-make} option, |
|
16b1e35e18fa
gnulib-tool: new option --gnu-make
Paul Eggert <eggert@cs.ucla.edu>
parents:
38305
diff
changeset
|
99 Gnulib also assumes that your project uses Automake at least in a |
|
16b1e35e18fa
gnulib-tool: new option --gnu-make
Paul Eggert <eggert@cs.ucla.edu>
parents:
38305
diff
changeset
|
100 subdirectory of your project. While the use of Automake in your |
|
16b1e35e18fa
gnulib-tool: new option --gnu-make
Paul Eggert <eggert@cs.ucla.edu>
parents:
38305
diff
changeset
|
101 project's top level directory is an easy way to fulfil the Makefile |
|
16b1e35e18fa
gnulib-tool: new option --gnu-make
Paul Eggert <eggert@cs.ucla.edu>
parents:
38305
diff
changeset
|
102 conventions of the GNU coding standards, Gnulib does not require it. |
| 32595 | 103 |
| 104 Invoking @samp{gnulib-tool --import} will copy source files, create a | |
| 25946 | 105 @file{Makefile.am} to build them, generate a file @file{gnulib-comp.m4} with |
| 106 Autoconf M4 macro declarations used by @file{configure.ac}, and generate | |
| 107 a file @file{gnulib-cache.m4} containing the cached specification of how | |
| 108 Gnulib is used. | |
| 109 | |
| 110 Our example will be a library that uses Autoconf, Automake and | |
| 111 Libtool. It calls @code{strdup}, and you wish to use gnulib to make | |
|
38491
c7ed2c8c86b7
Target a C99 subset, not a C89 subset
Paul Eggert <eggert@cs.ucla.edu>
parents:
38408
diff
changeset
|
112 the package portable to C99 and C11 (which don't have @code{strdup}). |
| 25946 | 113 |
| 114 @example | |
| 115 ~/src/libfoo$ gnulib-tool --import strdup | |
| 116 Module list with included dependencies: | |
|
27635
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
117 absolute-header |
|
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
118 extensions |
| 25946 | 119 strdup |
|
27635
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
120 string |
| 25946 | 121 File list: |
|
27635
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
122 lib/dummy.c |
| 25946 | 123 lib/strdup.c |
|
28955
82c4f3666255
Rename string_.h to string.in.h.
Bruno Haible <bruno@clisp.org>
parents:
28508
diff
changeset
|
124 lib/string.in.h |
|
27635
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
125 m4/absolute-header.m4 |
|
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
126 m4/extensions.m4 |
|
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
127 m4/gnulib-common.m4 |
| 25946 | 128 m4/strdup.m4 |
|
27635
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
129 m4/string_h.m4 |
|
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
130 Creating directory ./lib |
|
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
131 Creating directory ./m4 |
|
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
132 Copying file lib/dummy.c |
| 25946 | 133 Copying file lib/strdup.c |
|
28955
82c4f3666255
Rename string_.h to string.in.h.
Bruno Haible <bruno@clisp.org>
parents:
28508
diff
changeset
|
134 Copying file lib/string.in.h |
|
27635
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
135 Copying file m4/absolute-header.m4 |
|
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
136 Copying file m4/extensions.m4 |
|
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
137 Copying file m4/gnulib-common.m4 |
|
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
138 Copying file m4/gnulib-tool.m4 |
| 25946 | 139 Copying file m4/strdup.m4 |
|
27635
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
140 Copying file m4/string_h.m4 |
| 25946 | 141 Creating lib/Makefile.am |
| 142 Creating m4/gnulib-cache.m4 | |
| 143 Creating m4/gnulib-comp.m4 | |
| 144 Finished. | |
| 145 | |
| 146 You may need to add #include directives for the following .h files. | |
|
27635
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
147 #include <string.h> |
| 25946 | 148 |
| 149 Don't forget to | |
| 150 - add "lib/Makefile" to AC_CONFIG_FILES in ./configure.ac, | |
| 151 - mention "lib" in SUBDIRS in Makefile.am, | |
| 152 - mention "-I m4" in ACLOCAL_AMFLAGS in Makefile.am, | |
| 153 - invoke gl_EARLY in ./configure.ac, right after AC_PROG_CC, | |
| 154 - invoke gl_INIT in ./configure.ac. | |
| 155 ~/src/libfoo$ | |
| 156 @end example | |
| 157 | |
| 158 By default, the source code is copied into @file{lib/} and the M4 | |
| 159 macros in @file{m4/}. You can override these paths by using | |
| 160 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}. Some | |
| 33328 | 161 modules also provide other files necessary for building. These files |
| 25946 | 162 are copied into the directory specified by @samp{AC_CONFIG_AUX_DIR} in |
| 163 @file{configure.ac} or by the @code{--aux-dir=DIRECTORY} option. If | |
| 164 neither is specified, the current directory is assumed. | |
| 165 | |
| 166 @code{gnulib-tool} can make symbolic links instead of copying the | |
|
27151
8479fd9eda36
Emphasize the drawbacks of the --symlink option.
Bruno Haible <bruno@clisp.org>
parents:
26830
diff
changeset
|
167 source files. The option to specify for this is @samp{--symlink}, or |
|
8479fd9eda36
Emphasize the drawbacks of the --symlink option.
Bruno Haible <bruno@clisp.org>
parents:
26830
diff
changeset
|
168 @samp{-s} for short. This can be useful to save a few kilobytes of disk |
|
8479fd9eda36
Emphasize the drawbacks of the --symlink option.
Bruno Haible <bruno@clisp.org>
parents:
26830
diff
changeset
|
169 space. But it is likely to introduce bugs when @code{gnulib} is updated; |
|
8479fd9eda36
Emphasize the drawbacks of the --symlink option.
Bruno Haible <bruno@clisp.org>
parents:
26830
diff
changeset
|
170 it is more reliable to use @samp{gnulib-tool --update} (see below) |
|
8479fd9eda36
Emphasize the drawbacks of the --symlink option.
Bruno Haible <bruno@clisp.org>
parents:
26830
diff
changeset
|
171 to update to newer versions of @code{gnulib}. Furthermore it requires |
|
8479fd9eda36
Emphasize the drawbacks of the --symlink option.
Bruno Haible <bruno@clisp.org>
parents:
26830
diff
changeset
|
172 extra effort to create self-contained tarballs, and it may disturb some |
|
8479fd9eda36
Emphasize the drawbacks of the --symlink option.
Bruno Haible <bruno@clisp.org>
parents:
26830
diff
changeset
|
173 mechanism the maintainer applies to the sources. For these reasons, |
|
8479fd9eda36
Emphasize the drawbacks of the --symlink option.
Bruno Haible <bruno@clisp.org>
parents:
26830
diff
changeset
|
174 this option is generally discouraged. |
| 25946 | 175 |
| 176 @code{gnulib-tool} will overwrite any pre-existing files, in | |
| 33328 | 177 particular @file{Makefile.am}. It is also possible to separate the |
| 25946 | 178 generated @file{Makefile.am} content (for building the gnulib library) |
| 33328 | 179 into a separate file, say @file{gnulib.mk}, that can be included by your |
| 180 handwritten @file{Makefile.am}, but this is a more advanced use of | |
| 181 @code{gnulib-tool}. | |
| 25946 | 182 |
| 183 Consequently, it is a good idea to choose directories that are not | |
| 184 already used by your projects, to separate gnulib imported files from | |
| 185 your own files. This approach is also useful if you want to avoid | |
| 186 conflicts between other tools (e.g., @code{gettextize} that also copy | |
| 187 M4 files into your package. Simon Josefsson successfully uses a source | |
| 188 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several | |
| 189 packages. | |
| 190 | |
| 191 After the @samp{--import} option on the command line comes the list of | |
| 192 Gnulib modules that you want to incorporate in your package. The names | |
| 193 of the modules coincide with the filenames in Gnulib's @file{modules/} | |
| 194 directory. | |
| 195 | |
| 196 Some Gnulib modules depend on other Gnulib modules. @code{gnulib-tool} | |
| 197 will automatically add the needed modules as well; you need not list | |
|
26636
c135538476a8
* functions.texi, gnulib-tool.texi, gnulib.texi: Fix some typos.
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
26533
diff
changeset
|
198 them explicitly. @code{gnulib-tool} will also memorize which dependent |
| 25946 | 199 modules it has added, so that when someday a dependency is dropped, the |
| 200 implicitly added module is dropped as well (unless you have explicitly | |
| 201 requested that module). | |
| 202 | |
|
26636
c135538476a8
* functions.texi, gnulib-tool.texi, gnulib.texi: Fix some typos.
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
26533
diff
changeset
|
203 If you want to cut a dependency, i.e., not add a module although one of |
| 25946 | 204 your requested modules depends on it, you may use the option |
| 205 @samp{--avoid=@var{module}} to do so. Multiple uses of this option are | |
| 206 possible. Of course, you will then need to implement the same interface | |
| 207 as the removed module. | |
| 208 | |
| 209 A few manual steps are required to finish the initial import. | |
| 210 @code{gnulib-tool} printed a summary of these steps. | |
| 211 | |
|
26533
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
212 First, you must ensure Autoconf can find the macro definitions in |
|
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
213 @file{gnulib-comp.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in |
|
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
214 your top-level @file{Makefile.am} file, as in: |
| 25946 | 215 |
| 216 @example | |
| 217 ACLOCAL_AMFLAGS = -I m4 | |
| 218 @end example | |
| 219 | |
| 220 You are now ready to call the M4 macros in @code{gnulib-comp.m4} from | |
| 221 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon | |
| 222 as possible after verifying that the C compiler is working. | |
| 223 Typically, this is immediately after @code{AC_PROG_CC}, as in: | |
| 224 | |
| 225 @example | |
| 226 ... | |
| 227 AC_PROG_CC | |
| 228 gl_EARLY | |
| 229 ... | |
| 230 @end example | |
| 231 | |
|
35488
9596da93ab6f
doc: Improve doc about gl_EARLY.
Bruno Haible <bruno@clisp.org>
parents:
34524
diff
changeset
|
232 If you are using @code{AC_PROG_CC_STDC}, the macro @code{gl_EARLY} must |
|
9596da93ab6f
doc: Improve doc about gl_EARLY.
Bruno Haible <bruno@clisp.org>
parents:
34524
diff
changeset
|
233 be called after it, like this: |
|
9596da93ab6f
doc: Improve doc about gl_EARLY.
Bruno Haible <bruno@clisp.org>
parents:
34524
diff
changeset
|
234 |
|
9596da93ab6f
doc: Improve doc about gl_EARLY.
Bruno Haible <bruno@clisp.org>
parents:
34524
diff
changeset
|
235 @example |
|
9596da93ab6f
doc: Improve doc about gl_EARLY.
Bruno Haible <bruno@clisp.org>
parents:
34524
diff
changeset
|
236 ... |
|
9596da93ab6f
doc: Improve doc about gl_EARLY.
Bruno Haible <bruno@clisp.org>
parents:
34524
diff
changeset
|
237 AC_PROG_CC |
|
9596da93ab6f
doc: Improve doc about gl_EARLY.
Bruno Haible <bruno@clisp.org>
parents:
34524
diff
changeset
|
238 AC_PROG_CC_STDC |
|
9596da93ab6f
doc: Improve doc about gl_EARLY.
Bruno Haible <bruno@clisp.org>
parents:
34524
diff
changeset
|
239 gl_EARLY |
|
9596da93ab6f
doc: Improve doc about gl_EARLY.
Bruno Haible <bruno@clisp.org>
parents:
34524
diff
changeset
|
240 ... |
|
9596da93ab6f
doc: Improve doc about gl_EARLY.
Bruno Haible <bruno@clisp.org>
parents:
34524
diff
changeset
|
241 @end example |
|
9596da93ab6f
doc: Improve doc about gl_EARLY.
Bruno Haible <bruno@clisp.org>
parents:
34524
diff
changeset
|
242 |
| 25946 | 243 The core part of the gnulib checks are done by the macro |
| 244 @code{gl_INIT}. Place it further down in the file, typically where | |
|
26533
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
245 you normally check for header files or functions. It must come after |
|
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
246 other checks which may affect the compiler invocation, such as |
|
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
247 @code{AC_MINIX}. For example: |
| 25946 | 248 |
| 249 @example | |
| 250 ... | |
| 251 # For gnulib. | |
| 252 gl_INIT | |
| 253 ... | |
| 254 @end example | |
| 255 | |
| 256 @code{gl_INIT} will in turn call the macros related with the | |
| 257 gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA} | |
|
38408
16b1e35e18fa
gnulib-tool: new option --gnu-make
Paul Eggert <eggert@cs.ucla.edu>
parents:
38305
diff
changeset
|
258 or Autoconf or Automake macros like @code{AC_FUNC_ALLOCA} or |
| 25946 | 259 @code{AM_FUNC_GETLINE}. So there is no need to call those macros yourself |
| 260 when you use the corresponding gnulib modules. | |
| 261 | |
| 262 You must also make sure that the gnulib library is built. Add the | |
| 263 @code{Makefile} in the gnulib source base directory to | |
| 264 @code{AC_CONFIG_FILES}, as in: | |
| 265 | |
| 266 @example | |
| 267 AC_CONFIG_FILES(... lib/Makefile ...) | |
| 268 @end example | |
| 269 | |
| 270 You must also make sure that @code{make} will recurse into the gnulib | |
| 271 directory. To achieve this, add the gnulib source base directory to a | |
| 272 @code{SUBDIRS} Makefile.am statement, as in: | |
| 273 | |
| 274 @example | |
| 275 SUBDIRS = lib | |
| 276 @end example | |
| 277 | |
| 278 or if you, more likely, already have a few entries in @code{SUBDIRS}, | |
| 279 you can add something like: | |
| 280 | |
| 281 @example | |
| 282 SUBDIRS += lib | |
| 283 @end example | |
| 284 | |
| 285 Finally, you have to add compiler and linker flags in the appropriate | |
| 286 source directories, so that you can make use of the gnulib library. | |
| 287 Since some modules (@samp{getopt}, for example) may copy files into | |
| 288 the build directory, @file{top_builddir/lib} is needed as well | |
| 289 as @file{top_srcdir/lib}. For example: | |
| 290 | |
| 291 @example | |
| 292 ... | |
|
29036
8530358bbade
Replace paragraph that was explaining old way of handling LIBOBJS.
Bruno Haible <bruno@clisp.org>
parents:
28981
diff
changeset
|
293 AM_CPPFLAGS = -I$(top_builddir)/lib -I$(top_srcdir)/lib |
| 25946 | 294 ... |
|
26533
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
295 LDADD = lib/libgnu.a |
| 25946 | 296 ... |
| 297 @end example | |
| 298 | |
| 299 Don't forget to @code{#include} the various header files. In this | |
|
27635
0bd3697b93f0
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
27151
diff
changeset
|
300 example, you would need to make sure that @samp{#include <string.h>} |
| 25946 | 301 is evaluated when compiling all source code files, that want to make |
| 302 use of @code{strdup}. | |
| 303 | |
|
27837
1b4fb207384e
New module 'time', so that apps can include <time.h> as per
Paul Eggert <eggert@cs.ucla.edu>
parents:
27635
diff
changeset
|
304 In the usual case where Autoconf is creating a @file{config.h} file, |
|
1b4fb207384e
New module 'time', so that apps can include <time.h> as per
Paul Eggert <eggert@cs.ucla.edu>
parents:
27635
diff
changeset
|
305 you should include @file{config.h} first, before any other include |
|
1b4fb207384e
New module 'time', so that apps can include <time.h> as per
Paul Eggert <eggert@cs.ucla.edu>
parents:
27635
diff
changeset
|
306 file. That way, for example, if @file{config.h} defines |
|
38491
c7ed2c8c86b7
Target a C99 subset, not a C89 subset
Paul Eggert <eggert@cs.ucla.edu>
parents:
38408
diff
changeset
|
307 @samp{restrict} to be the empty string on a non-C99 host, or a macro |
|
27967
94c6d2e18615
Followup to the 2007-02-12 patch, using suggestions from Bruno Haible in
Paul Eggert <eggert@cs.ucla.edu>
parents:
27916
diff
changeset
|
308 like @samp{_FILE_OFFSET_BITS} that affects the layout of data |
|
94c6d2e18615
Followup to the 2007-02-12 patch, using suggestions from Bruno Haible in
Paul Eggert <eggert@cs.ucla.edu>
parents:
27916
diff
changeset
|
309 structures, the definition is consistent for all include files. |
|
27974
10dfa5b0b91b
* doc/gnulib-tool.texi (Initial import): Reword description of
Paul Eggert <eggert@cs.ucla.edu>
parents:
27968
diff
changeset
|
310 Also, on some platforms macros like @samp{_FILE_OFFSET_BITS} and |
|
10dfa5b0b91b
* doc/gnulib-tool.texi (Initial import): Reword description of
Paul Eggert <eggert@cs.ucla.edu>
parents:
27968
diff
changeset
|
311 @samp{_GNU_SOURCE} may be ineffective, or may have only a limited |
|
10dfa5b0b91b
* doc/gnulib-tool.texi (Initial import): Reword description of
Paul Eggert <eggert@cs.ucla.edu>
parents:
27968
diff
changeset
|
312 effect, if defined after the first system header file is included. |
| 25946 | 313 |
|
34252
6995aeb3019c
maint: change "can not" to "cannot"
Jim Meyering <meyering@redhat.com>
parents:
34099
diff
changeset
|
314 Finally, note that you cannot use @code{AC_LIBOBJ} or |
|
29036
8530358bbade
Replace paragraph that was explaining old way of handling LIBOBJS.
Bruno Haible <bruno@clisp.org>
parents:
28981
diff
changeset
|
315 @code{AC_REPLACE_FUNCS} in your @file{configure.ac} and expect the |
|
8530358bbade
Replace paragraph that was explaining old way of handling LIBOBJS.
Bruno Haible <bruno@clisp.org>
parents:
28981
diff
changeset
|
316 resulting object files to be automatically added to @file{lib/libgnu.a}. |
|
8530358bbade
Replace paragraph that was explaining old way of handling LIBOBJS.
Bruno Haible <bruno@clisp.org>
parents:
28981
diff
changeset
|
317 This is because your @code{AC_LIBOBJ} and @code{AC_REPLACE_FUNCS} invocations |
|
8530358bbade
Replace paragraph that was explaining old way of handling LIBOBJS.
Bruno Haible <bruno@clisp.org>
parents:
28981
diff
changeset
|
318 from @file{configure.ac} augment a variable @code{@@LIBOBJS@@} (and/or |
|
8530358bbade
Replace paragraph that was explaining old way of handling LIBOBJS.
Bruno Haible <bruno@clisp.org>
parents:
28981
diff
changeset
|
319 @code{@@LTLIBOBJS@@} if using Libtool), whereas @file{lib/libgnu.a} |
| 29037 | 320 is built from the contents of a different variable, usually |
| 321 @code{@@gl_LIBOBJS@@} (or @code{@@gl_LTLIBOBJS@@} if using Libtool). | |
|
26533
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
322 |
|
617eeddf8a76
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
26415
diff
changeset
|
323 |
| 25946 | 324 @node Modified imports |
| 325 @section Modified imports | |
| 326 | |
| 327 You can at any moment decide to use Gnulib differently than the last time. | |
| 328 | |
|
33329
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
329 There are two ways to change how Gnulib is used. Which one you'll use, |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
330 depends on where you keep track of options and module names that you pass |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
331 to @code{gnulib-tool}. |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
332 |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
333 @itemize @bullet |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
334 @item |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
335 If you store the options and module names in a file under your own |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
336 control, such as @file{autogen.sh}, @file{bootstrap}, |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
337 @file{bootstrap.conf}, or similar, simply invoke @command{gnulib-tool} |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
338 again, with modified options and more or fewer module names. |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
339 |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
340 @item |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
341 @code{gnulib-tool} remembers which modules were used last time. If you |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
342 want to rely on @code{gnulib-tool}'s own memory of the last used |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
343 options and module names, you can use the commands |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
344 @command{gnulib-tool --add-import} and |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
345 @command{gnulib-tool --remove-import}. |
| 25946 | 346 |
|
33329
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
347 So, if you only want to use more Gnulib modules, simply invoke |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
348 @command{gnulib-tool --add-import @var{new-modules}}. The list of |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
349 modules that you pass after @samp{--add-import} is @emph{added} to the |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
350 previous list of modules. |
| 25946 | 351 |
|
33329
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
352 Similarly, if you want to use fewer Gnulib modules, simply invoke |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
353 @command{gnulib-tool --remove-import @var{unneeded-modules}}. The list |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
354 of modules that you pass after @samp{--remove-import} is @emph{removed} |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
355 from the previous list of modules. Note that if a module is then still |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
356 needed as dependency of other modules, it will be used nevertheless. |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
357 If you want to @emph{really} not use a module any more, regardless of |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
358 whether other modules may need it, you need to use the @samp{--avoid} |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
359 option. |
| 25946 | 360 |
|
33329
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
361 For other changes, such as different choices of @samp{--lib}, |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
362 @samp{--source-base} or @samp{--aux-dir}, the normal way is to |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
363 modify manually the file @file{gnulib-cache.m4} in the M4 macros |
|
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
364 directory, then launch @samp{gnulib-tool --add-import}. |
| 25946 | 365 |
| 366 The only change for which this doesn't work is a change of the | |
| 367 @samp{--m4-base} directory. Because, when you pass a different value of | |
| 368 @samp{--m4-base}, @code{gnulib-tool} will not find the previous | |
| 33334 | 369 @file{gnulib-cache.m4} file any more. A possible solution is to |
|
33329
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
370 manually copy the @file{gnulib-cache.m4} into the new M4 macro directory. |
| 25946 | 371 |
| 33334 | 372 In the @file{gnulib-cache.m4} file, the macros have the following meaning: |
| 25946 | 373 @table @code |
| 374 @item gl_MODULES | |
| 375 The argument is a space separated list of the requested modules, not including | |
| 376 dependencies. | |
| 377 | |
| 378 @item gl_AVOID | |
| 379 The argument is a space separated list of modules that should not be used, | |
| 380 even if they occur as dependencies. Corresponds to the @samp{--avoid} | |
| 381 command line argument. | |
| 382 | |
| 383 @item gl_SOURCE_BASE | |
|
26415
496f55b8fff4
* gnulib-tool.texi (Modified imports): pathname -> file name.
Paul Eggert <eggert@cs.ucla.edu>
parents:
25946
diff
changeset
|
384 The argument is the relative file name of the directory containing the gnulib |
| 25946 | 385 source files (mostly *.c and *.h files). Corresponds to the |
| 386 @samp{--source-base} command line argument. | |
| 387 | |
| 388 @item gl_M4_BASE | |
|
26415
496f55b8fff4
* gnulib-tool.texi (Modified imports): pathname -> file name.
Paul Eggert <eggert@cs.ucla.edu>
parents:
25946
diff
changeset
|
389 The argument is the relative file name of the directory containing the gnulib |
| 25946 | 390 M4 macros (*.m4 files). Corresponds to the @samp{--m4-base} command line |
| 391 argument. | |
| 392 | |
| 393 @item gl_TESTS_BASE | |
|
26415
496f55b8fff4
* gnulib-tool.texi (Modified imports): pathname -> file name.
Paul Eggert <eggert@cs.ucla.edu>
parents:
25946
diff
changeset
|
394 The argument is the relative file name of the directory containing the gnulib |
| 25946 | 395 unit test files. Corresponds to the @samp{--tests-base} command line argument. |
| 396 | |
| 397 @item gl_LIB | |
| 398 The argument is the name of the library to be created. Corresponds to the | |
| 399 @samp{--lib} command line argument. | |
| 400 | |
| 401 @item gl_LGPL | |
|
29108
225b39c83b0d
Allow specifying the LGPL version number through --lgpl=2 or --lgpl=3.
Bruno Haible <bruno@clisp.org>
parents:
29103
diff
changeset
|
402 The presence of this macro without arguments corresponds to the @samp{--lgpl} |
|
225b39c83b0d
Allow specifying the LGPL version number through --lgpl=2 or --lgpl=3.
Bruno Haible <bruno@clisp.org>
parents:
29103
diff
changeset
|
403 command line argument. The presence of this macro with an argument (whose |
|
225b39c83b0d
Allow specifying the LGPL version number through --lgpl=2 or --lgpl=3.
Bruno Haible <bruno@clisp.org>
parents:
29103
diff
changeset
|
404 value must be 2 or 3) corresponds to the @samp{--lgpl=@var{arg}} command line |
|
225b39c83b0d
Allow specifying the LGPL version number through --lgpl=2 or --lgpl=3.
Bruno Haible <bruno@clisp.org>
parents:
29103
diff
changeset
|
405 argument. |
| 25946 | 406 |
| 407 @item gl_LIBTOOL | |
| 408 The presence of this macro corresponds to the @samp{--libtool} command line | |
| 26768 | 409 argument and to the absence of the @samp{--no-libtool} command line argument. |
| 410 It takes no arguments. | |
| 25946 | 411 |
| 412 @item gl_MACRO_PREFIX | |
| 413 The argument is the prefix to use for macros in the @file{gnulib-comp.m4} | |
| 414 file. Corresponds to the @samp{--macro-prefix} command line argument. | |
| 415 @end table | |
| 416 | |
|
33329
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
417 @end itemize |
|
29103
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
418 |
| 25946 | 419 @node Simple update |
| 420 @section Simple update | |
| 421 | |
| 422 When you want to update to a more recent version of Gnulib, without | |
| 423 changing the list of modules or other parameters, a simple call | |
| 424 does it: | |
| 425 | |
| 426 @smallexample | |
|
33329
a83430863bdd
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
33328
diff
changeset
|
427 $ gnulib-tool --add-import |
| 25946 | 428 @end smallexample |
| 429 | |
|
29103
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
430 @noindent |
| 25946 | 431 This will create, update or remove files, as needed. |
| 432 | |
|
29103
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
433 Note: From time to time, changes are made in Gnulib that are not backward |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
434 compatible. When updating to a more recent Gnulib, you should consult |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
435 Gnulib's @file{NEWS} file to check whether the incompatible changes affect |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
436 your project. |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
437 |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
438 |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
439 @node Source changes |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
440 @section Changing your sources for use with Gnulib |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
441 |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
442 Gnulib contains some header file overrides. This means that when building |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
443 on systems with deficient header files in @file{/usr/include/}, it may create |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
444 files named @file{string.h}, @file{stdlib.h}, @file{stdint.h} or similar in |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
445 the build directory. In the other source directories of your package you |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
446 will usually pass @samp{-I} options to the compiler, so that these Gnulib |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
447 substitutes are visible and take precedence over the files in |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
448 @file{/usr/include/}. |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
449 |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
450 These Gnulib substitute header files rely on @file{<config.h>} being |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
451 already included. Furthermore @file{<config.h>} must be the first include |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
452 in every compilation unit. This means that to @emph{all your source files} |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
453 and likely also to @emph{all your tests source files} you need to add an |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
454 @samp{#include <config.h>} at the top. Which source files are affected? |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
455 Exactly those whose compilation includes a @samp{-I} option that refers to |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
456 the Gnulib library directory. |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
457 |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
458 This is annoying, but inevitable: On many systems, @file{<config.h>} is |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
459 used to set system dependent flags (such as @code{_GNU_SOURCE} on GNU systems), |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
460 and these flags have no effect after any system header file has been included. |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
461 |
|
152580c2c6bc
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
29037
diff
changeset
|
462 |
|
39179
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
463 @node Modified build rules |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
464 @section Modifying the build rules of a Gnulib import directory |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
465 |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
466 In some cases, you may want to set additional compiler options for |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
467 use within the Gnulib import directory. For example, the |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
468 @samp{relocatable} module operates better if you define the C macros |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
469 @code{ENABLE_COSTLY_RELOCATABLE} and @code{INSTALLDIR} during its |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
470 compilation. |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
471 |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
472 There are two ways to do so: Use of the @code{gnulib-tool} option |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
473 @code{--makefile-name}, and a kitchen-sink module. |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
474 |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
475 With the @code{gnulib-tool} option @code{--makefile-name}, you are |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
476 telling @code{gnulib-tool} to generate an includable @code{Makefile.am} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
477 portion, rather than a self-contained @code{Makefile.am}. For example, |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
478 when you use @code{--makefile-name=Makefile.gnulib}, @code{gnulib-tool} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
479 will generate @code{Makefile.gnulib}, and you will provide a |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
480 hand-written @code{Makefile.am} that includes @code{Makefile.gnulib} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
481 through a line such as |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
482 @smallexample |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
483 include Makefile.gnulib |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
484 @end smallexample |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
485 Before this include, you need to initialize this set of @code{Makefile.am} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
486 variables: |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
487 @itemize @bullet |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
488 @item |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
489 @code{AUTOMAKE_OPTIONS} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
490 @item |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
491 @code{SUBDIRS} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
492 @item |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
493 @code{noinst_HEADERS} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
494 @item |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
495 @code{noinst_LIBRARIES} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
496 @item |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
497 @code{noinst_LTLIBRARIES} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
498 @item |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
499 @code{pkgdata_DATA} (only with Automake @geq{} 1.11.4) |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
500 @item |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
501 @code{EXTRA_DIST} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
502 @item |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
503 @code{BUILT_SOURCES} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
504 @item |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
505 @code{SUFFIXES} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
506 @item |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
507 @code{MOSTLYCLEANFILES} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
508 @item |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
509 @code{MOSTLYCLEANDIRS} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
510 @item |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
511 @code{CLEANFILES} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
512 @item |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
513 @code{DISTCLEANFILES} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
514 @item |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
515 @code{MAINTAINERCLEANFILES} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
516 @item |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
517 @code{AM_CPPFLAGS} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
518 @item |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
519 @code{AM_CFLAGS} |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
520 @end itemize |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
521 @code{AUTOMAKE_OPTIONS} should be initialized as described in |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
522 @ref{Options,,Changing Automake's Behavior,automake,GNU Automake}. |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
523 The other variables can be initialized to empty. However, you will most |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
524 likely want to initialize some of them with non-empty values, in order |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
525 to achieve the desired customization. |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
526 |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
527 The other approach, the kitchen-sink module, is more advanced. See |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
528 chapter @ref{Extending Gnulib}. |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
529 |
|
c1c9d3013c37
doc: New section "Modifying the build rules of a Gnulib import directory".
Bruno Haible <bruno@clisp.org>
parents:
39178
diff
changeset
|
530 |
|
37766
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
531 @node Multiple instances |
| 39178 | 532 @section Using Gnulib for both a library and a program |
|
37766
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
533 |
| 39178 | 534 Your project might build both a library and some accompanying programs |
|
37766
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
535 in the same source tree. In that case you might want to use different |
| 39178 | 536 modules for the library than for the programs. Typically the programs |
|
37766
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
537 might want to make use of @code{getopt-posix} or @code{version-etc}, |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
538 while the library wants to stay clear of these modules for technical |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
539 or licensing reasons. |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
540 |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
541 Let's assume that your project contains a @file{lib} directory where |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
542 the source of the library resides and a @file{src} directory for the |
| 39178 | 543 sources of the programs as follows. |
|
37766
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
544 |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
545 @example |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
546 . |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
547 |-- configure.ac |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
548 |-- lib |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
549 | |-- foo.c |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
550 | `-- Makefile.am |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
551 |-- Makefile.am |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
552 `-- src |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
553 |-- bar.c |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
554 `-- Makefile.am |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
555 @end example |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
556 |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
557 You can now add two instances of Gnulib to your project in separate |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
558 source trees: |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
559 |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
560 @example |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
561 ~/src/libfoo$ gnulib-tool --import --lib=libgnu --source-base=gnulib \ |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
562 --m4-base=gnulib/m4 --macro-prefix=gl strndup |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
563 ~/src/libfoo$ gnulib-tool --import --lib=libgnutools \ |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
564 --source-base=src/gnulib --m4-base=src/gnulib/m4 \ |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
565 --macro-prefix=gl_tools getopt-gnu |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
566 @end example |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
567 |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
568 The first one will import the module @code{strndup} in @file{gnulib} |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
569 and the second one will import @code{getopt-gnu} in @file{src/gnulib} |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
570 and you will end up with the following source tree (many files omitted |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
571 in the interest of brevity): |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
572 |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
573 @example |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
574 . |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
575 |-- configure.ac |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
576 |-- gnulib |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
577 | |-- m4 |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
578 | |-- strndup.c |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
579 |-- lib |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
580 | |-- foo.c |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
581 | `-- Makefile.am |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
582 |-- Makefile.am |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
583 `-- src |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
584 |-- bar.c |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
585 |-- gnulib |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
586 | |-- getopt.c |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
587 | |-- getopt.in.h |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
588 | |-- m4 |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
589 `-- Makefile.am |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
590 @end example |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
591 |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
592 Integration with your code is basically the same as outlined in |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
593 @ref{Initial import} with the one exception that you have to add both |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
594 the macro @code{gl_EARLY} and the macro @code{gl_tools_EARLY} to your |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
595 @file{configure.ac} (and of course also both macros @code{gl_INIT} and |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
596 @code{gl_tools_INIT}). Obviously the name of the second macro is |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
597 dependent on the value of the @option{--macro-prefix} option in your |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
598 @command{gnulib-tool} invocation. |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
599 |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
600 @example |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
601 ... |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
602 AC_PROG_CC |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
603 gl_EARLY |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
604 gl_tools_EARLY |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
605 ... |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
606 # For gnulib. |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
607 gl_INIT |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
608 gl_tools_INIT |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
609 ... |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
610 @end example |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
611 |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
612 Also as outlined in @ref{Initial import} you will have to add compiler |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
613 and linker flags. For the library you might have to add something |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
614 along the line of the following to your @file{Makefile.am}: |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
615 |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
616 @example |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
617 ... |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
618 AM_CPPFLAGS = -I$(top_srcdir)/gnulib -I$(top_builddir)/gnulib |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
619 ... |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
620 libfoo_la_LIBADD = $(top_builddir)/gnulib/libgnu.la |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
621 ... |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
622 @end example |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
623 |
| 39178 | 624 Correspondingly for the programs you will have to add something like |
| 625 this: | |
|
37766
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
626 |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
627 @example |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
628 ... |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
629 AM_CPPFLAGS = -I$(top_srcdir)/src/gnulib -I$(top_builddir)/src/gnulib |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
630 ... |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
631 LIBADD = $(top_builddir)/src/gnulib/libgnutools.la |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
632 ... |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
633 @end example |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
634 |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
635 The name of the library that you have pass in the linker option |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
636 depends on the @option{--lib} option in @command{gnulib-tool} |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
637 invocation. |
|
d517f4a2f2d6
doc: Describe to use multiple instances of gnulib
Christian Egli <christian.egli@sbs.ch>
parents:
37647
diff
changeset
|
638 |
| 39178 | 639 |
|
29499
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
640 @node gettextize and autopoint |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
641 @section Caveat: @code{gettextize} and @code{autopoint} users |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
642 |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
643 @cindex gettextize, caveat |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
644 @cindex autopoint, caveat |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
645 The programs @code{gettextize} and @code{autopoint}, part of |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
646 GNU @code{gettext}, import or update the internationalization infrastructure. |
|
38408
16b1e35e18fa
gnulib-tool: new option --gnu-make
Paul Eggert <eggert@cs.ucla.edu>
parents:
38305
diff
changeset
|
647 Some of this infrastructure, namely ca.@: 20 Autoconf macro files and the |
|
29499
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
648 @file{config.rpath} file, is also contained in Gnulib and may be imported |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
649 by @code{gnulib-tool}. The use of @code{gettextize} or @code{autopoint} |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
650 will therefore overwrite some of the files that @code{gnulib-tool} has |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
651 imported, and vice versa. |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
652 |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
653 Avoiding to use @code{gettextize} (manually, as package maintainer) or |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
654 @code{autopoint} (as part of a script like @code{autoreconf} or |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
655 @code{autogen.sh}) is not the solution: These programs also import the |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
656 infrastructure in the @file{po/} and optionally in the @file{intl/} directory. |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
657 |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
658 The copies of the conflicting files in Gnulib are more up-to-date than |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
659 the copies brought in by @code{gettextize} and @code{autopoint}. When a |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
660 new @code{gettext} release is made, the copies of the files in Gnulib will |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
661 be updated immediately. |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
662 |
|
36528
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
663 The choice of which version of gettext to require depends on the needs |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
664 of your package. For a package that wants to comply to GNU Coding |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
665 Standards, the steps are: |
|
29499
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
666 |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
667 @enumerate |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
668 @item |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
669 When you run @code{gettextize}, always use the @code{gettextize} from the |
|
29505
e3453373813e
Tweak the "gettextize and autopoint" section.
Bruno Haible <bruno@clisp.org>
parents:
29499
diff
changeset
|
670 matching GNU gettext release. For the most recent Gnulib checkout, this is |
|
38843
fe6f0f324ef9
doc: Prefer https URLs where possible.
Bruno Haible <bruno@clisp.org>
parents:
38491
diff
changeset
|
671 the newest release found on @url{https://ftp.gnu.org/gnu/gettext/}. For an |
|
29505
e3453373813e
Tweak the "gettextize and autopoint" section.
Bruno Haible <bruno@clisp.org>
parents:
29499
diff
changeset
|
672 older Gnulib snapshot, it is the release that was the most recent release |
|
36528
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
673 at the time the Gnulib snapshot was taken. |
|
29499
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
674 |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
675 @item |
|
36528
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
676 After running @code{gettextize}, invoke @code{gnulib-tool} and import |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
677 the @code{gettext} module. Also, copy the latest version of gnulib's |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
678 @file{build-aux/po/Makefile.in.in} to your @file{po/} directory (this |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
679 is done for you if you use gnulib's @file{bootstrap} script). |
|
29499
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
680 |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
681 @item |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
682 If you get an error message like |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
683 @code{*** error: gettext infrastructure mismatch: |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
684 using a Makefile.in.in from gettext version ... |
|
38408
16b1e35e18fa
gnulib-tool: new option --gnu-make
Paul Eggert <eggert@cs.ucla.edu>
parents:
38305
diff
changeset
|
685 but the Autoconf macros are from gettext version ...}, |
|
16b1e35e18fa
gnulib-tool: new option --gnu-make
Paul Eggert <eggert@cs.ucla.edu>
parents:
38305
diff
changeset
|
686 it means that a new GNU gettext release was made, and its Autoconf macros |
|
29499
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
687 were integrated into Gnulib and now mismatch the @file{po/} infrastructure. |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
688 In this case, fetch and install the new GNU gettext release and run |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
689 @code{gettextize} followed by @code{gnulib-tool}. |
|
36528
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
690 @end enumerate |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
691 |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
692 On the other hand, if your package is not as concerned with compliance |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
693 to the latest standards, but instead favors development on stable |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
694 environments, the steps are: |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
695 |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
696 @enumerate |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
697 @item |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
698 Determine the oldest version of @code{gettext} that you intend to |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
699 support during development (at this time, gnulib recommends going no |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
700 older than version 0.17). Run @code{autopoint} (not |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
701 @code{gettextize}) to copy infrastructure into place (newer versions |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
702 of gettext will install the older infrastructure that you requested). |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
703 |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
704 @item |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
705 Invoke @code{gnulib-tool}, and import the @code{gettext-h} module. |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
706 @end enumerate |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
707 |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
708 Regardless of which approach you used to get the infrastructure in |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
709 place, the following steps must then be used to preserve that |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
710 infrastructure (gnulib's @file{bootstrap} script follows these rules): |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
711 |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
712 @enumerate |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
713 @item |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
714 When a script of yours run @code{autopoint}, invoke @code{gnulib-tool} |
|
33b8797bd9e2
doc: recommendations on gettext version
Eric Blake <eblake@redhat.com>
parents:
35892
diff
changeset
|
715 afterwards. |
|
34099
10845a2c58d2
doc: Improve doc regarding autopoint vs. gnulib.
Bruno Haible <bruno@clisp.org>
parents:
33770
diff
changeset
|
716 |
|
10845a2c58d2
doc: Improve doc regarding autopoint vs. gnulib.
Bruno Haible <bruno@clisp.org>
parents:
33770
diff
changeset
|
717 @item |
|
10845a2c58d2
doc: Improve doc regarding autopoint vs. gnulib.
Bruno Haible <bruno@clisp.org>
parents:
33770
diff
changeset
|
718 When you invoke @code{autoreconf} after @code{gnulib-tool}, make sure to |
|
10845a2c58d2
doc: Improve doc regarding autopoint vs. gnulib.
Bruno Haible <bruno@clisp.org>
parents:
33770
diff
changeset
|
719 not invoke @code{autopoint} a second time, by setting the @code{AUTOPOINT} |
|
10845a2c58d2
doc: Improve doc regarding autopoint vs. gnulib.
Bruno Haible <bruno@clisp.org>
parents:
33770
diff
changeset
|
720 environment variable, like this: |
|
10845a2c58d2
doc: Improve doc regarding autopoint vs. gnulib.
Bruno Haible <bruno@clisp.org>
parents:
33770
diff
changeset
|
721 @smallexample |
|
10845a2c58d2
doc: Improve doc regarding autopoint vs. gnulib.
Bruno Haible <bruno@clisp.org>
parents:
33770
diff
changeset
|
722 $ env AUTOPOINT=true autoreconf --install |
|
10845a2c58d2
doc: Improve doc regarding autopoint vs. gnulib.
Bruno Haible <bruno@clisp.org>
parents:
33770
diff
changeset
|
723 @end smallexample |
|
29499
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
724 @end enumerate |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
725 |
|
d64c477e66ff
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
29456
diff
changeset
|
726 |
|
29258
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
727 @node Localization |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
728 @section Handling Gnulib's own message translations |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
729 |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
730 Gnulib provides some functions that emit translatable messages using GNU |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
731 @code{gettext}. The @samp{gnulib} domain at the |
|
38843
fe6f0f324ef9
doc: Prefer https URLs where possible.
Bruno Haible <bruno@clisp.org>
parents:
38491
diff
changeset
|
732 @url{https://translationproject.org/, Translation Project} collects |
|
29258
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
733 translations of these messages, which you should incorporate into your |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
734 own programs. |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
735 |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
736 There are two basic ways to achieve this. The first, and older, method |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
737 is to list all the source files you use from Gnulib in your own |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
738 @file{po/POTFILES.in} file. This will cause all the relevant |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
739 translatable strings to be included in your POT file. When you send |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
740 this POT file to the Translation Project, translators will normally fill |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
741 in the translations of the Gnulib strings from their ``translation |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
742 memory'', and send you back updated PO files. |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
743 |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
744 However, this process is error-prone: you might forget to list some |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
745 source files, or the translator might not be using a translation memory |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
746 and provide a different translation than another translator, or the |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
747 translation might not be kept in sync between Gnulib and your package. |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
748 It is also slow and causes substantial extra work, because a human |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
749 translator must be in the loop for each language and you will need to |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
750 incorporate their work on request. |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
751 |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
752 For these reasons, a new method was designed and is now recommended. If |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
753 you pass the @code{--po-base=@var{directory}} and @code{--po-domain=@var{domain}} |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
754 options to @code{gnulib-tool}, then @code{gnulib-tool} will create a |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
755 separate directory with its own @file{POTFILES.in}, and fetch current |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
756 translations directly from the Translation Project (using |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
757 @command{rsync} or @command{wget}, whichever is available). |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
758 The POT file in this directory will be called |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
759 @file{@var{domain}-gnulib.pot}, depending on the @var{domain} you gave to the |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
760 @code{--po-domain} option (typically the same as the package name). |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
761 This causes these translations to reside in a separate message domain, |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
762 so that they do not clash either with the translations for the main part |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
763 of your package nor with those of other packages on the system that use |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
764 possibly different versions of Gnulib. |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
765 When you use these options, the functions in Gnulib are built |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
766 in such a way that they will always use this domain regardless of the |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
767 default domain set by @code{textdomain}. |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
768 |
| 36914 | 769 In order to use this method, you must---in each program that might use |
| 770 Gnulib code---add an extra line to the part of the program that | |
|
29258
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
771 initializes locale-dependent behavior. Where you would normally write |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
772 something like: |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
773 |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
774 @example |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
775 @group |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
776 setlocale (LC_ALL, ""); |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
777 bindtextdomain (PACKAGE, LOCALEDIR); |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
778 textdomain (PACKAGE); |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
779 @end group |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
780 @end example |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
781 |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
782 @noindent |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
783 you should add an additional @code{bindtextdomain} call to inform |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
784 gettext of where the MO files for the extra message domain may be found: |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
785 |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
786 @example |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
787 @group |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
788 bindtextdomain (PACKAGE "-gnulib", LOCALEDIR); |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
789 @end group |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
790 @end example |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
791 |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
792 (This example assumes that the @var{domain} that you specified |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
793 to @code{gnulib-tool} is the same as the value of the @code{PACKAGE} |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
794 preprocessor macro.) |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
795 |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
796 Since you do not change the @code{textdomain} call, the default message |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
797 domain for your program remains the same and your own use of @code{gettext} |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
798 functions will not be affected. |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
799 |
|
0618cf2b1692
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
29108
diff
changeset
|
800 |
|
28981
74c961c83b76
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
28955
diff
changeset
|
801 @node VCS Issues |
|
74c961c83b76
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
28955
diff
changeset
|
802 @section Issues with Version Control Systems |
|
74c961c83b76
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
28955
diff
changeset
|
803 |
|
74c961c83b76
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
28955
diff
changeset
|
804 If a project stores its source files in a version control system (VCS), |
|
32667
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
805 such as CVS, Subversion, or Git, one needs to decide which files to commit. |
| 25946 | 806 |
|
32667
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
807 In principle, all files created by @code{gnulib-tool}, except |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
808 @file{gnulib-cache.m4}, can be treated like generated source files, |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
809 like for example a @file{parser.c} file generated from |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
810 @file{parser.y}. Alternatively, they can be considered source files |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
811 and updated manually. |
| 25946 | 812 |
|
32667
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
813 Here are the three different approaches in common use. Each has its |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
814 place, and you should use whichever best suits your particular project |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
815 and development methods. |
|
27916
b550daf1fa3a
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
27837
diff
changeset
|
816 |
|
32667
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
817 @enumerate |
|
27916
b550daf1fa3a
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
27837
diff
changeset
|
818 @item |
|
32667
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
819 In projects which commit all source files, whether generated or not, |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
820 into their VCS, the @code{gnulib-tool} generated files should all be |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
821 committed. In this case, you should pass the option |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
822 @samp{--no-vc-files} to @code{gnulib-tool}, which avoids alteration of |
|
37069
ad409ab5c454
Assume gnulib is checked out from Git, not CVS
Stefano Lattarini <stefano.lattarini@gmail.com>
parents:
36940
diff
changeset
|
823 VCS-related files such as @file{.gitignore}. |
| 25946 | 824 |
|
27916
b550daf1fa3a
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
27837
diff
changeset
|
825 Gnulib also contains files generated by @command{make} (and removed by |
|
32667
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
826 @code{make clean}), using information determined by |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
827 @command{configure}. For a Gnulib source file of the form |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
828 @file{lib/foo.in.h}, the corresponding @file{lib/foo.h} is such a |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
829 @command{make}-generated file. These should @emph{not} be checked |
|
37069
ad409ab5c454
Assume gnulib is checked out from Git, not CVS
Stefano Lattarini <stefano.lattarini@gmail.com>
parents:
36940
diff
changeset
|
830 into the VCS, but instead added to @file{.gitignore} or equivalent. |
|
27916
b550daf1fa3a
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
27837
diff
changeset
|
831 |
|
b550daf1fa3a
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
27837
diff
changeset
|
832 @item |
|
32667
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
833 In projects which customarily omit from their VCS all files that are |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
834 generated from other source files, none of these files and directories |
|
33330
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
835 are added into the VCS. As described in @ref{Modified imports}, there |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
836 are two ways to keep track of options and module names that are passed |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
837 to @code{gnulib-tool}. The command for restoring the omitted files |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
838 depends on it: |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
839 |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
840 @itemize @bullet |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
841 @item |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
842 If they are stored in a file other than @code{gnulib-cache.m4}, such as |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
843 @file{autogen.sh}, @file{bootstrap}, @file{bootstrap.conf}, or similar, |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
844 the restoration command is the entire @code{gnulib-tool ... --import ...} |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
845 invocation with all options and module names. |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
846 |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
847 @item |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
848 If the project relies on @code{gnulib-tool}'s memory of the last used |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
849 options and module names, then the file @file{gnulib-cache.m4} in the M4 |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
850 macros directory must be added to the VCS, and the restoration command |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
851 is: |
| 25946 | 852 |
| 853 @smallexample | |
| 854 $ gnulib-tool --update | |
| 855 @end smallexample | |
| 856 | |
|
33330
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
857 The @samp{--update} option operates much like the @samp{--add-import} |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
858 option, but it does not offer the possibility to change the way Gnulib is |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
859 used. Also it does not report in the ChangeLogs the files that it had to |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
860 add because they were missing. |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
861 |
|
8692458fd366
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
33329
diff
changeset
|
862 @end itemize |
|
27916
b550daf1fa3a
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
27837
diff
changeset
|
863 |
|
32668
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
864 Gnulib includes the file @file{build-aux/bootstrap} to aid a developer |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
865 in using this setup. Furthermore, in projects that use git for |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
866 version control, it is possible to use a git submodule containing the |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
867 precise commit of the gnulib repository, so that each developer |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
868 running @file{bootstrap} will get the same version of all |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
869 gnulib-provided files. The location of the submodule can be chosen to |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
870 fit the package's needs; here's how to initially create the submodule |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
871 in the directory @file{.gnulib}: |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
872 |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
873 @smallexample |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
874 $ dir=.gnulib |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
875 $ git submodule add -- git://git.sv.gnu.org/gnulib.git $dir |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
876 $ git config alias.syncsub "submodule foreach git pull origin master" |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
877 @end smallexample |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
878 |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
879 @noindent |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
880 Thereafter, @file{bootstrap} can run this command to update the |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
881 submodule to the recorded checkout level: |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
882 |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
883 @smallexample |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
884 git submodule update --init $dir |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
885 @end smallexample |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
886 |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
887 @noindent |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
888 and a developer can use this sequence to update to a newer version of |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
889 gnulib: |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
890 |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
891 @smallexample |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
892 $ git syncsub |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
893 $ git add $dir |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
894 $ ./bootstrap |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
895 @end smallexample |
|
607c3f8326c1
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
32667
diff
changeset
|
896 |
|
32667
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
897 @item |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
898 Some projects take a ``middle road'': they do commit Gnulib source |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
899 files as in the first approach, but they do not commit other derived |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
900 files, such as a @code{Makefile.in} generated by Automake. This |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
901 increases the size and complexity of the repository, but can help |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
902 occasional contributors by not requiring them to have a full Gnulib |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
903 checkout to do a build, and all developers by ensuring that all |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
904 developers are working with the same version of Gnulib in the |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
905 repository. It also supports multiple Gnulib instances within a |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
906 project. It remains important not to commit the |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
907 @command{make}-generated files, as described above. |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
908 |
|
7185262d2112
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
32595
diff
changeset
|
909 @end enumerate |
| 30520 | 910 |
| 911 | |
| 912 @node Unit tests | |
| 913 @section Bundling the unit tests of the Gnulib modules | |
| 914 | |
| 915 You can bundle the unit tests of the Gnulib modules together with your | |
| 916 package, through the @samp{--with-tests} option. Together with | |
| 917 @samp{--with-tests}, you also specify the directory for these tests | |
| 918 through the @samp{--tests-base} option. Of course, you need to add this | |
| 919 directory to the @code{SUBDIRS} variable in the @code{Makefile.am} of | |
| 920 the parent directory. | |
| 921 | |
| 922 The advantage of having the unit tests bundled is that when your program | |
| 923 has a problem on a particular platform, running the unit tests may help | |
| 924 determine quickly if the problem is on Gnulib's side or on your package's | |
| 925 side. Also, it helps verifying Gnulib's portability, of course. | |
| 926 | |
| 927 The unit tests will be compiled and run when the user runs @samp{make check}. | |
| 928 When the user runs only @samp{make}, the unit tests will not be compiled. | |
| 929 | |
| 930 In the @code{SUBDIRS} variable, it is useful to put the Gnulib tests directory | |
| 931 after the directory containing the other tests, not before: | |
| 932 | |
| 933 @smallexample | |
| 934 SUBDIRS = gnulib-lib src man tests gnulib-tests | |
| 935 @end smallexample | |
| 936 | |
| 937 @noindent | |
| 938 This will ensure that on platforms where there are test failures in either | |
| 939 directory, users will see and report the failures from the tests of your | |
| 940 program. | |
| 941 | |
| 942 Note: In packages which use more than one invocation of @code{gnulib-tool} | |
| 943 in the scope of the same @code{configure.ac}, you cannot use | |
| 944 @samp{--with-tests}. You will have to use a separate @code{configure.ac} | |
| 945 in this case. | |
|
34524
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
946 |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
947 |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
948 @node Conditional dependencies |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
949 @section Avoiding unnecessary checks and compilations |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
950 |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
951 @cindex conditional dependencies |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
952 In some cases, a module is needed by another module only on specific |
|
38408
16b1e35e18fa
gnulib-tool: new option --gnu-make
Paul Eggert <eggert@cs.ucla.edu>
parents:
38305
diff
changeset
|
953 platforms. But when a module is present, its Autoconf checks are always |
|
34524
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
954 executed, and its @code{Makefile.am} additions are always enabled. So |
|
38408
16b1e35e18fa
gnulib-tool: new option --gnu-make
Paul Eggert <eggert@cs.ucla.edu>
parents:
38305
diff
changeset
|
955 it can happen that some Autoconf checks are executed and some source files |
|
34524
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
956 are compiled, although no other module needs them on this particular |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
957 platform, just @emph{in case} some other module would need them. |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
958 |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
959 The option @samp{--conditional-dependencies} enables an optimization of |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
960 configure checks and @code{Makefile.am} snippets that avoids this. With |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
961 this option, whether a module is considered ``present'' is no longer decided |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
962 when @code{gnulib-tool} is invoked, but later, when @code{configure} is run. |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
963 This applies to modules that were added as dependencies while |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
964 @code{gnulib-tool} was run; modules that were passed on the command line |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
965 explicitly are always ``present''. |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
966 |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
967 For example, the @code{timegm} module needs, on platforms |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
968 where the system's @code{timegm} function is missing or buggy, a replacement |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
969 that is based on a function @code{mktime_internal}. The module |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
970 @code{mktime-internal} that provides this function provides it on all |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
971 platforms. So, by default, the file @file{mktime-internal.c} will be |
| 36914 | 972 compiled on all platforms, even on glibc and BSD systems which have a |
|
34524
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
973 working @code{timegm} function. When the option |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
974 @samp{--conditional-dependencies} is given, on the other hand, and if |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
975 @code{mktime-internal} was not explicitly required on the command line, |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
976 the file @file{mktime-internal.c} will only be compiled on the platforms |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
977 where the @code{timegm} needs them. |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
978 |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
979 Conditional dependencies are specified in the module description by putting |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
980 the condition on the same line as the dependent module, enclosed in brackets. |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
981 The condition is a boolean shell expression that can assume that the |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
982 @code{configure.ac} snippet from the module description has already been |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
983 executed. In the example above, the dependency from @code{timegm} to |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
984 @code{mktime-internal} is written like this: |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
985 |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
986 @smallexample |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
987 Depends-on: |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
988 ... |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
989 mktime-internal [test $HAVE_TIMEGM = 0 || test $REPLACE_TIMEGM = 1] |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
990 ... |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
991 @end smallexample |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
992 |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
993 Note: The option @samp{--conditional-dependencies} cannot be used together |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
994 with the option @samp{--with-tests}. It also cannot be used when a package |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
995 uses @code{gnulib-tool} for several subdirectories, with different values |
|
112e9c3223ba
Finish the conditional dependencies mechanism.
Bruno Haible <bruno@clisp.org>
parents:
34252
diff
changeset
|
996 of @samp{--source-base}, in the scope of a single @code{configure.ac} file. |