Mercurial > hg > octave-lojdl > gnulib-hg
annotate doc/gnulib-tool.texi @ 11444:9d49a57f4a8c
Document how gnulib-tool can be put into PATH.
| author | Bruno Haible <bruno@clisp.org> |
|---|---|
| date | Thu, 02 Apr 2009 02:20:00 +0200 |
| parents | b88018de1691 |
| children | c2cbabec01dd |
| rev | line source |
|---|---|
| 6255 | 1 @node Invoking gnulib-tool |
| 2 @chapter Invoking gnulib-tool | |
| 3 | |
|
11444
9d49a57f4a8c
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
10829
diff
changeset
|
4 @c Copyright (C) 2005-2009 Free Software Foundation, Inc. |
|
7139
adb21c293305
Add copyright notices to long-enough files that lack them, since
Paul Eggert <eggert@cs.ucla.edu>
parents:
7077
diff
changeset
|
5 |
|
adb21c293305
Add copyright notices to long-enough files that lack them, since
Paul Eggert <eggert@cs.ucla.edu>
parents:
7077
diff
changeset
|
6 @c Permission is granted to copy, distribute and/or modify this document |
|
10762
d67664a4e01c
Change license to GFDLv1.3+.
Simon Josefsson <simon@josefsson.org>
parents:
10251
diff
changeset
|
7 @c under the terms of the GNU Free Documentation License, Version 1.3 or |
|
7139
adb21c293305
Add copyright notices to long-enough files that lack them, since
Paul Eggert <eggert@cs.ucla.edu>
parents:
7077
diff
changeset
|
8 @c any later version published by the Free Software Foundation; with no |
|
adb21c293305
Add copyright notices to long-enough files that lack them, since
Paul Eggert <eggert@cs.ucla.edu>
parents:
7077
diff
changeset
|
9 @c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover |
|
adb21c293305
Add copyright notices to long-enough files that lack them, since
Paul Eggert <eggert@cs.ucla.edu>
parents:
7077
diff
changeset
|
10 @c Texts. A copy of the license is included in the ``GNU Free |
|
adb21c293305
Add copyright notices to long-enough files that lack them, since
Paul Eggert <eggert@cs.ucla.edu>
parents:
7077
diff
changeset
|
11 @c Documentation License'' file as part of this distribution. |
|
adb21c293305
Add copyright notices to long-enough files that lack them, since
Paul Eggert <eggert@cs.ucla.edu>
parents:
7077
diff
changeset
|
12 |
| 6255 | 13 @pindex gnulib-tool |
| 14 @cindex invoking @command{gnulib-tool} | |
| 15 | |
|
6842
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
16 The @command{gnulib-tool} command is the recommended way to import |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
17 Gnulib modules. It is possible to borrow Gnulib modules in a package |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
18 without using @command{gnulib-tool}, relying only on the |
|
6945
aa195d9ecb02
* functions.texi, gnulib-tool.texi, gnulib.texi: Fix some typos.
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
6842
diff
changeset
|
19 meta-information stored in the @file{modules/*} files, but with a |
|
6842
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
20 growing number of modules this becomes tedious. @command{gnulib-tool} |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
21 simplifies the management of source files, @file{Makefile.am}s and |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
22 @file{configure.ac} in packages incorporating Gnulib modules. |
| 6255 | 23 |
|
11444
9d49a57f4a8c
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
10829
diff
changeset
|
24 @file{gnulib-tool} is not installed in a standard directory that is |
|
9d49a57f4a8c
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
10829
diff
changeset
|
25 contained in the @code{PATH} variable. It needs to be run directly in |
|
9d49a57f4a8c
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
10829
diff
changeset
|
26 the directory that contains the Gnulib source code. You can do this |
|
9d49a57f4a8c
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
10829
diff
changeset
|
27 either by specifying the absolute filename of @file{gnulib-tool}, or |
|
9d49a57f4a8c
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
10829
diff
changeset
|
28 you can also use a symbolic link from a place inside your @code{PATH} |
|
9d49a57f4a8c
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
10829
diff
changeset
|
29 to the @file{gnulib-tool} file of your preferred and most up-to-date |
|
9d49a57f4a8c
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
10829
diff
changeset
|
30 Gnulib checkout, like this: |
|
9d49a57f4a8c
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
10829
diff
changeset
|
31 @smallexample |
|
9d49a57f4a8c
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
10829
diff
changeset
|
32 $ ln -s $HOME/gnu/src/gnulib.git/gnulib-tool $HOME/bin/gnulib-tool |
|
9d49a57f4a8c
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
10829
diff
changeset
|
33 @end smallexample |
|
9d49a57f4a8c
Document how gnulib-tool can be put into PATH.
Bruno Haible <bruno@clisp.org>
parents:
10829
diff
changeset
|
34 |
|
6842
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
35 Run @samp{gnulib-tool --help} for information. To get familiar with |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
36 @command{gnulib-tool} without affecting your sources, you can also try |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
37 some commands with the option @samp{--dry-run}; then |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
38 @code{gnulib-tool} will only report which actions it would perform in |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
39 a real run without changing anything. |
| 6255 | 40 |
| 41 @menu | |
| 42 * Initial import:: First import of Gnulib modules. | |
| 43 * Modified imports:: Changing the import specification. | |
| 44 * Simple update:: Tracking Gnulib development. | |
|
9412
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
45 * Source changes:: Impact of Gnulib on your source files. |
|
9808
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
46 * gettextize and autopoint:: Caveat: @code{gettextize} and @code{autopoint} users! |
|
9567
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
47 * Localization:: Handling Gnulib's own message translations. |
|
9290
c525a3ae0f4c
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
9264
diff
changeset
|
48 * VCS Issues:: Integration with Version Control Systems. |
| 10829 | 49 * Unit tests:: Bundling the unit tests of the Gnulib modules. |
| 6255 | 50 @end menu |
| 51 | |
| 52 | |
| 53 @node Initial import | |
| 54 @section Initial import | |
| 55 @cindex initial import | |
| 56 | |
| 57 Gnulib assumes your project uses Autoconf and Automake. Invoking | |
| 58 @samp{gnulib-tool --import} will copy source files, create a | |
| 59 @file{Makefile.am} to build them, generate a file @file{gnulib-comp.m4} with | |
| 60 Autoconf M4 macro declarations used by @file{configure.ac}, and generate | |
| 61 a file @file{gnulib-cache.m4} containing the cached specification of how | |
| 62 Gnulib is used. | |
| 63 | |
| 64 Our example will be a library that uses Autoconf, Automake and | |
| 65 Libtool. It calls @code{strdup}, and you wish to use gnulib to make | |
|
7944
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
66 the package portable to C89 and C99 (which don't have @code{strdup}). |
| 6255 | 67 |
| 68 @example | |
| 69 ~/src/libfoo$ gnulib-tool --import strdup | |
| 70 Module list with included dependencies: | |
|
7944
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
71 absolute-header |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
72 extensions |
| 6255 | 73 strdup |
|
7944
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
74 string |
| 6255 | 75 File list: |
|
7944
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
76 lib/dummy.c |
| 6255 | 77 lib/strdup.c |
|
9264
a1355710e330
Rename string_.h to string.in.h.
Bruno Haible <bruno@clisp.org>
parents:
8817
diff
changeset
|
78 lib/string.in.h |
|
7944
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
79 m4/absolute-header.m4 |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
80 m4/extensions.m4 |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
81 m4/gnulib-common.m4 |
| 6255 | 82 m4/strdup.m4 |
|
7944
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
83 m4/string_h.m4 |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
84 Creating directory ./lib |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
85 Creating directory ./m4 |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
86 Copying file lib/dummy.c |
| 6255 | 87 Copying file lib/strdup.c |
|
9264
a1355710e330
Rename string_.h to string.in.h.
Bruno Haible <bruno@clisp.org>
parents:
8817
diff
changeset
|
88 Copying file lib/string.in.h |
|
7944
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
89 Copying file m4/absolute-header.m4 |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
90 Copying file m4/extensions.m4 |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
91 Copying file m4/gnulib-common.m4 |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
92 Copying file m4/gnulib-tool.m4 |
| 6255 | 93 Copying file m4/strdup.m4 |
|
7944
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
94 Copying file m4/string_h.m4 |
| 6255 | 95 Creating lib/Makefile.am |
| 96 Creating m4/gnulib-cache.m4 | |
| 97 Creating m4/gnulib-comp.m4 | |
| 98 Finished. | |
| 99 | |
| 100 You may need to add #include directives for the following .h files. | |
|
7944
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
101 #include <string.h> |
| 6255 | 102 |
| 103 Don't forget to | |
| 104 - add "lib/Makefile" to AC_CONFIG_FILES in ./configure.ac, | |
| 105 - mention "lib" in SUBDIRS in Makefile.am, | |
| 106 - mention "-I m4" in ACLOCAL_AMFLAGS in Makefile.am, | |
| 107 - invoke gl_EARLY in ./configure.ac, right after AC_PROG_CC, | |
| 108 - invoke gl_INIT in ./configure.ac. | |
| 109 ~/src/libfoo$ | |
| 110 @end example | |
| 111 | |
| 112 By default, the source code is copied into @file{lib/} and the M4 | |
| 113 macros in @file{m4/}. You can override these paths by using | |
| 114 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}. Some | |
| 115 modules also provide other files necessary for building. These files | |
| 116 are copied into the directory specified by @samp{AC_CONFIG_AUX_DIR} in | |
| 117 @file{configure.ac} or by the @code{--aux-dir=DIRECTORY} option. If | |
| 118 neither is specified, the current directory is assumed. | |
| 119 | |
| 120 @code{gnulib-tool} can make symbolic links instead of copying the | |
|
7460
b82874ef9c54
Emphasize the drawbacks of the --symlink option.
Bruno Haible <bruno@clisp.org>
parents:
7139
diff
changeset
|
121 source files. The option to specify for this is @samp{--symlink}, or |
|
b82874ef9c54
Emphasize the drawbacks of the --symlink option.
Bruno Haible <bruno@clisp.org>
parents:
7139
diff
changeset
|
122 @samp{-s} for short. This can be useful to save a few kilobytes of disk |
|
b82874ef9c54
Emphasize the drawbacks of the --symlink option.
Bruno Haible <bruno@clisp.org>
parents:
7139
diff
changeset
|
123 space. But it is likely to introduce bugs when @code{gnulib} is updated; |
|
b82874ef9c54
Emphasize the drawbacks of the --symlink option.
Bruno Haible <bruno@clisp.org>
parents:
7139
diff
changeset
|
124 it is more reliable to use @samp{gnulib-tool --update} (see below) |
|
b82874ef9c54
Emphasize the drawbacks of the --symlink option.
Bruno Haible <bruno@clisp.org>
parents:
7139
diff
changeset
|
125 to update to newer versions of @code{gnulib}. Furthermore it requires |
|
b82874ef9c54
Emphasize the drawbacks of the --symlink option.
Bruno Haible <bruno@clisp.org>
parents:
7139
diff
changeset
|
126 extra effort to create self-contained tarballs, and it may disturb some |
|
b82874ef9c54
Emphasize the drawbacks of the --symlink option.
Bruno Haible <bruno@clisp.org>
parents:
7139
diff
changeset
|
127 mechanism the maintainer applies to the sources. For these reasons, |
|
b82874ef9c54
Emphasize the drawbacks of the --symlink option.
Bruno Haible <bruno@clisp.org>
parents:
7139
diff
changeset
|
128 this option is generally discouraged. |
| 6255 | 129 |
| 130 @code{gnulib-tool} will overwrite any pre-existing files, in | |
| 131 particular @file{Makefile.am}. Unfortunately, separating the | |
| 132 generated @file{Makefile.am} content (for building the gnulib library) | |
| 133 into a separate file, say @file{gnulib.mk}, that could be included | |
| 134 by your handwritten @file{Makefile.am} is not possible, due to how | |
| 135 variable assignments are handled by Automake. | |
| 136 | |
| 137 Consequently, it is a good idea to choose directories that are not | |
| 138 already used by your projects, to separate gnulib imported files from | |
| 139 your own files. This approach is also useful if you want to avoid | |
| 140 conflicts between other tools (e.g., @code{gettextize} that also copy | |
| 141 M4 files into your package. Simon Josefsson successfully uses a source | |
| 142 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several | |
| 143 packages. | |
| 144 | |
| 145 After the @samp{--import} option on the command line comes the list of | |
| 146 Gnulib modules that you want to incorporate in your package. The names | |
| 147 of the modules coincide with the filenames in Gnulib's @file{modules/} | |
| 148 directory. | |
| 149 | |
| 150 Some Gnulib modules depend on other Gnulib modules. @code{gnulib-tool} | |
| 151 will automatically add the needed modules as well; you need not list | |
|
6945
aa195d9ecb02
* functions.texi, gnulib-tool.texi, gnulib.texi: Fix some typos.
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
6842
diff
changeset
|
152 them explicitly. @code{gnulib-tool} will also memorize which dependent |
| 6255 | 153 modules it has added, so that when someday a dependency is dropped, the |
| 154 implicitly added module is dropped as well (unless you have explicitly | |
| 155 requested that module). | |
| 156 | |
|
6945
aa195d9ecb02
* functions.texi, gnulib-tool.texi, gnulib.texi: Fix some typos.
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
6842
diff
changeset
|
157 If you want to cut a dependency, i.e., not add a module although one of |
| 6255 | 158 your requested modules depends on it, you may use the option |
| 159 @samp{--avoid=@var{module}} to do so. Multiple uses of this option are | |
| 160 possible. Of course, you will then need to implement the same interface | |
| 161 as the removed module. | |
| 162 | |
| 163 A few manual steps are required to finish the initial import. | |
| 164 @code{gnulib-tool} printed a summary of these steps. | |
| 165 | |
|
6842
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
166 First, you must ensure Autoconf can find the macro definitions in |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
167 @file{gnulib-comp.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
168 your top-level @file{Makefile.am} file, as in: |
| 6255 | 169 |
| 170 @example | |
| 171 ACLOCAL_AMFLAGS = -I m4 | |
| 172 @end example | |
| 173 | |
| 174 You are now ready to call the M4 macros in @code{gnulib-comp.m4} from | |
| 175 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon | |
| 176 as possible after verifying that the C compiler is working. | |
| 177 Typically, this is immediately after @code{AC_PROG_CC}, as in: | |
| 178 | |
| 179 @example | |
| 180 ... | |
| 181 AC_PROG_CC | |
| 182 gl_EARLY | |
| 183 ... | |
| 184 @end example | |
| 185 | |
| 186 The core part of the gnulib checks are done by the macro | |
| 187 @code{gl_INIT}. Place it further down in the file, typically where | |
|
6842
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
188 you normally check for header files or functions. It must come after |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
189 other checks which may affect the compiler invocation, such as |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
190 @code{AC_MINIX}. For example: |
| 6255 | 191 |
| 192 @example | |
| 193 ... | |
| 194 # For gnulib. | |
| 195 gl_INIT | |
| 196 ... | |
| 197 @end example | |
| 198 | |
| 199 @code{gl_INIT} will in turn call the macros related with the | |
| 200 gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA} | |
| 201 or autoconf or automake macros like @code{AC_FUNC_ALLOCA} or | |
| 202 @code{AM_FUNC_GETLINE}. So there is no need to call those macros yourself | |
| 203 when you use the corresponding gnulib modules. | |
| 204 | |
| 205 You must also make sure that the gnulib library is built. Add the | |
| 206 @code{Makefile} in the gnulib source base directory to | |
| 207 @code{AC_CONFIG_FILES}, as in: | |
| 208 | |
| 209 @example | |
| 210 AC_CONFIG_FILES(... lib/Makefile ...) | |
| 211 @end example | |
| 212 | |
| 213 You must also make sure that @code{make} will recurse into the gnulib | |
| 214 directory. To achieve this, add the gnulib source base directory to a | |
| 215 @code{SUBDIRS} Makefile.am statement, as in: | |
| 216 | |
| 217 @example | |
| 218 SUBDIRS = lib | |
| 219 @end example | |
| 220 | |
| 221 or if you, more likely, already have a few entries in @code{SUBDIRS}, | |
| 222 you can add something like: | |
| 223 | |
| 224 @example | |
| 225 SUBDIRS += lib | |
| 226 @end example | |
| 227 | |
| 228 Finally, you have to add compiler and linker flags in the appropriate | |
| 229 source directories, so that you can make use of the gnulib library. | |
| 230 Since some modules (@samp{getopt}, for example) may copy files into | |
| 231 the build directory, @file{top_builddir/lib} is needed as well | |
| 232 as @file{top_srcdir/lib}. For example: | |
| 233 | |
| 234 @example | |
| 235 ... | |
|
9345
233439805e0a
Replace paragraph that was explaining old way of handling LIBOBJS.
Bruno Haible <bruno@clisp.org>
parents:
9290
diff
changeset
|
236 AM_CPPFLAGS = -I$(top_builddir)/lib -I$(top_srcdir)/lib |
| 6255 | 237 ... |
|
6842
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
238 LDADD = lib/libgnu.a |
| 6255 | 239 ... |
| 240 @end example | |
| 241 | |
| 242 Don't forget to @code{#include} the various header files. In this | |
|
7944
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
243 example, you would need to make sure that @samp{#include <string.h>} |
| 6255 | 244 is evaluated when compiling all source code files, that want to make |
| 245 use of @code{strdup}. | |
| 246 | |
|
8146
b31580167c2b
New module 'time', so that apps can include <time.h> as per
Paul Eggert <eggert@cs.ucla.edu>
parents:
7944
diff
changeset
|
247 In the usual case where Autoconf is creating a @file{config.h} file, |
|
b31580167c2b
New module 'time', so that apps can include <time.h> as per
Paul Eggert <eggert@cs.ucla.edu>
parents:
7944
diff
changeset
|
248 you should include @file{config.h} first, before any other include |
|
b31580167c2b
New module 'time', so that apps can include <time.h> as per
Paul Eggert <eggert@cs.ucla.edu>
parents:
7944
diff
changeset
|
249 file. That way, for example, if @file{config.h} defines |
|
8276
0ead70460e39
Followup to the 2007-02-12 patch, using suggestions from Bruno Haible in
Paul Eggert <eggert@cs.ucla.edu>
parents:
8225
diff
changeset
|
250 @samp{restrict} to be the empty string on a pre-C99 host, or a macro |
|
0ead70460e39
Followup to the 2007-02-12 patch, using suggestions from Bruno Haible in
Paul Eggert <eggert@cs.ucla.edu>
parents:
8225
diff
changeset
|
251 like @samp{_FILE_OFFSET_BITS} that affects the layout of data |
|
0ead70460e39
Followup to the 2007-02-12 patch, using suggestions from Bruno Haible in
Paul Eggert <eggert@cs.ucla.edu>
parents:
8225
diff
changeset
|
252 structures, the definition is consistent for all include files. |
|
8283
b1b93f37d597
* doc/gnulib-tool.texi (Initial import): Reword description of
Paul Eggert <eggert@cs.ucla.edu>
parents:
8277
diff
changeset
|
253 Also, on some platforms macros like @samp{_FILE_OFFSET_BITS} and |
|
b1b93f37d597
* doc/gnulib-tool.texi (Initial import): Reword description of
Paul Eggert <eggert@cs.ucla.edu>
parents:
8277
diff
changeset
|
254 @samp{_GNU_SOURCE} may be ineffective, or may have only a limited |
|
b1b93f37d597
* doc/gnulib-tool.texi (Initial import): Reword description of
Paul Eggert <eggert@cs.ucla.edu>
parents:
8277
diff
changeset
|
255 effect, if defined after the first system header file is included. |
| 6255 | 256 |
|
9345
233439805e0a
Replace paragraph that was explaining old way of handling LIBOBJS.
Bruno Haible <bruno@clisp.org>
parents:
9290
diff
changeset
|
257 Finally, note that you can not use @code{AC_LIBOBJ} or |
|
233439805e0a
Replace paragraph that was explaining old way of handling LIBOBJS.
Bruno Haible <bruno@clisp.org>
parents:
9290
diff
changeset
|
258 @code{AC_REPLACE_FUNCS} in your @file{configure.ac} and expect the |
|
233439805e0a
Replace paragraph that was explaining old way of handling LIBOBJS.
Bruno Haible <bruno@clisp.org>
parents:
9290
diff
changeset
|
259 resulting object files to be automatically added to @file{lib/libgnu.a}. |
|
233439805e0a
Replace paragraph that was explaining old way of handling LIBOBJS.
Bruno Haible <bruno@clisp.org>
parents:
9290
diff
changeset
|
260 This is because your @code{AC_LIBOBJ} and @code{AC_REPLACE_FUNCS} invocations |
|
233439805e0a
Replace paragraph that was explaining old way of handling LIBOBJS.
Bruno Haible <bruno@clisp.org>
parents:
9290
diff
changeset
|
261 from @file{configure.ac} augment a variable @code{@@LIBOBJS@@} (and/or |
|
233439805e0a
Replace paragraph that was explaining old way of handling LIBOBJS.
Bruno Haible <bruno@clisp.org>
parents:
9290
diff
changeset
|
262 @code{@@LTLIBOBJS@@} if using Libtool), whereas @file{lib/libgnu.a} |
| 9346 | 263 is built from the contents of a different variable, usually |
| 264 @code{@@gl_LIBOBJS@@} (or @code{@@gl_LTLIBOBJS@@} if using Libtool). | |
|
6842
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
265 |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
266 |
| 6255 | 267 @node Modified imports |
| 268 @section Modified imports | |
| 269 | |
| 270 You can at any moment decide to use Gnulib differently than the last time. | |
| 271 | |
| 272 If you only want to use more Gnulib modules, simply invoke | |
| 273 @command{gnulib-tool --import @var{new-modules}}. @code{gnulib-tool} | |
| 274 remembers which modules were used last time. The list of modules that | |
| 275 you pass after @samp{--import} is @emph{added} to the previous list of | |
| 276 modules. | |
| 277 | |
| 278 For most changes, such as added or removed modules, or even different | |
| 279 choices of @samp{--lib}, @samp{--source-base} or @samp{--aux-dir}, there | |
| 280 are two ways to perform the change. | |
| 281 | |
| 282 The standard way is to modify manually the file @file{gnulib-cache.m4} | |
| 283 in the M4 macros directory, then launch @samp{gnulib-tool --import}. | |
| 284 | |
| 285 The other way is to call @command{gnulib-tool} again, with the changed | |
| 286 command-line options. Note that this doesn't let you remove modules, | |
| 287 because as you just learned, the list of modules is always cumulated. | |
| 288 Also this way is often impractical, because you don't remember the way | |
| 289 you invoked @code{gnulib-tool} last time. | |
| 290 | |
| 291 The only change for which this doesn't work is a change of the | |
| 292 @samp{--m4-base} directory. Because, when you pass a different value of | |
| 293 @samp{--m4-base}, @code{gnulib-tool} will not find the previous | |
| 294 @file{gnulib-cache.m4} file any more... A possible solution is to manually | |
| 295 copy the @file{gnulib-cache.m4} into the new M4 macro directory. | |
| 296 | |
| 297 In the @file{gnulib-cache.m4}, the macros have the following meaning: | |
| 298 @table @code | |
| 299 @item gl_MODULES | |
| 300 The argument is a space separated list of the requested modules, not including | |
| 301 dependencies. | |
| 302 | |
| 303 @item gl_AVOID | |
| 304 The argument is a space separated list of modules that should not be used, | |
| 305 even if they occur as dependencies. Corresponds to the @samp{--avoid} | |
| 306 command line argument. | |
| 307 | |
| 308 @item gl_SOURCE_BASE | |
|
6724
68cc9b819542
* gnulib-tool.texi (Modified imports): pathname -> file name.
Paul Eggert <eggert@cs.ucla.edu>
parents:
6255
diff
changeset
|
309 The argument is the relative file name of the directory containing the gnulib |
| 6255 | 310 source files (mostly *.c and *.h files). Corresponds to the |
| 311 @samp{--source-base} command line argument. | |
| 312 | |
| 313 @item gl_M4_BASE | |
|
6724
68cc9b819542
* gnulib-tool.texi (Modified imports): pathname -> file name.
Paul Eggert <eggert@cs.ucla.edu>
parents:
6255
diff
changeset
|
314 The argument is the relative file name of the directory containing the gnulib |
| 6255 | 315 M4 macros (*.m4 files). Corresponds to the @samp{--m4-base} command line |
| 316 argument. | |
| 317 | |
| 318 @item gl_TESTS_BASE | |
|
6724
68cc9b819542
* gnulib-tool.texi (Modified imports): pathname -> file name.
Paul Eggert <eggert@cs.ucla.edu>
parents:
6255
diff
changeset
|
319 The argument is the relative file name of the directory containing the gnulib |
| 6255 | 320 unit test files. Corresponds to the @samp{--tests-base} command line argument. |
| 321 | |
| 322 @item gl_LIB | |
| 323 The argument is the name of the library to be created. Corresponds to the | |
| 324 @samp{--lib} command line argument. | |
| 325 | |
| 326 @item gl_LGPL | |
|
9417
95cbd64f5138
Allow specifying the LGPL version number through --lgpl=2 or --lgpl=3.
Bruno Haible <bruno@clisp.org>
parents:
9412
diff
changeset
|
327 The presence of this macro without arguments corresponds to the @samp{--lgpl} |
|
95cbd64f5138
Allow specifying the LGPL version number through --lgpl=2 or --lgpl=3.
Bruno Haible <bruno@clisp.org>
parents:
9412
diff
changeset
|
328 command line argument. The presence of this macro with an argument (whose |
|
95cbd64f5138
Allow specifying the LGPL version number through --lgpl=2 or --lgpl=3.
Bruno Haible <bruno@clisp.org>
parents:
9412
diff
changeset
|
329 value must be 2 or 3) corresponds to the @samp{--lgpl=@var{arg}} command line |
|
95cbd64f5138
Allow specifying the LGPL version number through --lgpl=2 or --lgpl=3.
Bruno Haible <bruno@clisp.org>
parents:
9412
diff
changeset
|
330 argument. |
| 6255 | 331 |
| 332 @item gl_LIBTOOL | |
| 333 The presence of this macro corresponds to the @samp{--libtool} command line | |
| 7077 | 334 argument and to the absence of the @samp{--no-libtool} command line argument. |
| 335 It takes no arguments. | |
| 6255 | 336 |
| 337 @item gl_MACRO_PREFIX | |
| 338 The argument is the prefix to use for macros in the @file{gnulib-comp.m4} | |
| 339 file. Corresponds to the @samp{--macro-prefix} command line argument. | |
| 340 @end table | |
| 341 | |
|
9412
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
342 |
| 6255 | 343 @node Simple update |
| 344 @section Simple update | |
| 345 | |
| 346 When you want to update to a more recent version of Gnulib, without | |
| 347 changing the list of modules or other parameters, a simple call | |
| 348 does it: | |
| 349 | |
| 350 @smallexample | |
| 351 $ gnulib-tool --import | |
| 352 @end smallexample | |
| 353 | |
|
9412
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
354 @noindent |
| 6255 | 355 This will create, update or remove files, as needed. |
| 356 | |
|
9412
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
357 Note: From time to time, changes are made in Gnulib that are not backward |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
358 compatible. When updating to a more recent Gnulib, you should consult |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
359 Gnulib's @file{NEWS} file to check whether the incompatible changes affect |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
360 your project. |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
361 |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
362 |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
363 @node Source changes |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
364 @section Changing your sources for use with Gnulib |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
365 |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
366 Gnulib contains some header file overrides. This means that when building |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
367 on systems with deficient header files in @file{/usr/include/}, it may create |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
368 files named @file{string.h}, @file{stdlib.h}, @file{stdint.h} or similar in |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
369 the build directory. In the other source directories of your package you |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
370 will usually pass @samp{-I} options to the compiler, so that these Gnulib |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
371 substitutes are visible and take precedence over the files in |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
372 @file{/usr/include/}. |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
373 |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
374 These Gnulib substitute header files rely on @file{<config.h>} being |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
375 already included. Furthermore @file{<config.h>} must be the first include |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
376 in every compilation unit. This means that to @emph{all your source files} |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
377 and likely also to @emph{all your tests source files} you need to add an |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
378 @samp{#include <config.h>} at the top. Which source files are affected? |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
379 Exactly those whose compilation includes a @samp{-I} option that refers to |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
380 the Gnulib library directory. |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
381 |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
382 This is annoying, but inevitable: On many systems, @file{<config.h>} is |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
383 used to set system dependent flags (such as @code{_GNU_SOURCE} on GNU systems), |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
384 and these flags have no effect after any system header file has been included. |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
385 |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
386 |
|
9808
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
387 @node gettextize and autopoint |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
388 @section Caveat: @code{gettextize} and @code{autopoint} users |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
389 |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
390 @cindex gettextize, caveat |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
391 @cindex autopoint, caveat |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
392 The programs @code{gettextize} and @code{autopoint}, part of |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
393 GNU @code{gettext}, import or update the internationalization infrastructure. |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
394 Some of this infrastructure, namely ca.@: 20 autoconf macro files and the |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
395 @file{config.rpath} file, is also contained in Gnulib and may be imported |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
396 by @code{gnulib-tool}. The use of @code{gettextize} or @code{autopoint} |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
397 will therefore overwrite some of the files that @code{gnulib-tool} has |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
398 imported, and vice versa. |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
399 |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
400 Avoiding to use @code{gettextize} (manually, as package maintainer) or |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
401 @code{autopoint} (as part of a script like @code{autoreconf} or |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
402 @code{autogen.sh}) is not the solution: These programs also import the |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
403 infrastructure in the @file{po/} and optionally in the @file{intl/} directory. |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
404 |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
405 The copies of the conflicting files in Gnulib are more up-to-date than |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
406 the copies brought in by @code{gettextize} and @code{autopoint}. When a |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
407 new @code{gettext} release is made, the copies of the files in Gnulib will |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
408 be updated immediately. |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
409 |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
410 The solution is therefore: |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
411 |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
412 @enumerate |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
413 @item |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
414 When you run @code{gettextize}, always use the @code{gettextize} from the |
|
9814
4c56b4354002
Tweak the "gettextize and autopoint" section.
Bruno Haible <bruno@clisp.org>
parents:
9808
diff
changeset
|
415 matching GNU gettext release. For the most recent Gnulib checkout, this is |
|
4c56b4354002
Tweak the "gettextize and autopoint" section.
Bruno Haible <bruno@clisp.org>
parents:
9808
diff
changeset
|
416 the newest release found on @url{http://ftp.gnu.org/gnu/gettext/}. For an |
|
4c56b4354002
Tweak the "gettextize and autopoint" section.
Bruno Haible <bruno@clisp.org>
parents:
9808
diff
changeset
|
417 older Gnulib snapshot, it is the release that was the most recent release |
|
4c56b4354002
Tweak the "gettextize and autopoint" section.
Bruno Haible <bruno@clisp.org>
parents:
9808
diff
changeset
|
418 at the time the Gnulib snapshot was taken. Then, after @code{gettextize}, |
|
4c56b4354002
Tweak the "gettextize and autopoint" section.
Bruno Haible <bruno@clisp.org>
parents:
9808
diff
changeset
|
419 invoke @code{gnulib-tool}. |
|
9808
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
420 |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
421 @item |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
422 When a script of yours run @code{autopoint}, invoke @code{gnulib-tool} |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
423 afterwards. |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
424 |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
425 @item |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
426 If you get an error message like |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
427 @code{*** error: gettext infrastructure mismatch: |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
428 using a Makefile.in.in from gettext version ... |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
429 but the autoconf macros are from gettext version ...}, |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
430 it means that a new GNU gettext release was made, and its autoconf macros |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
431 were integrated into Gnulib and now mismatch the @file{po/} infrastructure. |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
432 In this case, fetch and install the new GNU gettext release and run |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
433 @code{gettextize} followed by @code{gnulib-tool}. |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
434 @end enumerate |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
435 |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
436 |
|
9567
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
437 @node Localization |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
438 @section Handling Gnulib's own message translations |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
439 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
440 Gnulib provides some functions that emit translatable messages using GNU |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
441 @code{gettext}. The @samp{gnulib} domain at the |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
442 @url{http://translationproject.org/, Translation Project} collects |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
443 translations of these messages, which you should incorporate into your |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
444 own programs. |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
445 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
446 There are two basic ways to achieve this. The first, and older, method |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
447 is to list all the source files you use from Gnulib in your own |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
448 @file{po/POTFILES.in} file. This will cause all the relevant |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
449 translatable strings to be included in your POT file. When you send |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
450 this POT file to the Translation Project, translators will normally fill |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
451 in the translations of the Gnulib strings from their ``translation |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
452 memory'', and send you back updated PO files. |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
453 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
454 However, this process is error-prone: you might forget to list some |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
455 source files, or the translator might not be using a translation memory |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
456 and provide a different translation than another translator, or the |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
457 translation might not be kept in sync between Gnulib and your package. |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
458 It is also slow and causes substantial extra work, because a human |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
459 translator must be in the loop for each language and you will need to |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
460 incorporate their work on request. |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
461 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
462 For these reasons, a new method was designed and is now recommended. If |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
463 you pass the @code{--po-base=@var{directory}} and @code{--po-domain=@var{domain}} |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
464 options to @code{gnulib-tool}, then @code{gnulib-tool} will create a |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
465 separate directory with its own @file{POTFILES.in}, and fetch current |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
466 translations directly from the Translation Project (using |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
467 @command{rsync} or @command{wget}, whichever is available). |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
468 The POT file in this directory will be called |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
469 @file{@var{domain}-gnulib.pot}, depending on the @var{domain} you gave to the |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
470 @code{--po-domain} option (typically the same as the package name). |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
471 This causes these translations to reside in a separate message domain, |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
472 so that they do not clash either with the translations for the main part |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
473 of your package nor with those of other packages on the system that use |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
474 possibly different versions of Gnulib. |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
475 When you use these options, the functions in Gnulib are built |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
476 in such a way that they will always use this domain regardless of the |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
477 default domain set by @code{textdomain}. |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
478 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
479 In order to use this method, you must -- in each program that might use |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
480 Gnulib code -- add an extra line to the part of the program that |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
481 initializes locale-dependent behavior. Where you would normally write |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
482 something like: |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
483 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
484 @example |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
485 @group |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
486 setlocale (LC_ALL, ""); |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
487 bindtextdomain (PACKAGE, LOCALEDIR); |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
488 textdomain (PACKAGE); |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
489 @end group |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
490 @end example |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
491 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
492 @noindent |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
493 you should add an additional @code{bindtextdomain} call to inform |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
494 gettext of where the MO files for the extra message domain may be found: |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
495 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
496 @example |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
497 @group |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
498 bindtextdomain (PACKAGE "-gnulib", LOCALEDIR); |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
499 @end group |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
500 @end example |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
501 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
502 (This example assumes that the @var{domain} that you specified |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
503 to @code{gnulib-tool} is the same as the value of the @code{PACKAGE} |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
504 preprocessor macro.) |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
505 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
506 Since you do not change the @code{textdomain} call, the default message |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
507 domain for your program remains the same and your own use of @code{gettext} |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
508 functions will not be affected. |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
509 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
510 |
|
9290
c525a3ae0f4c
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
9264
diff
changeset
|
511 @node VCS Issues |
|
c525a3ae0f4c
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
9264
diff
changeset
|
512 @section Issues with Version Control Systems |
|
c525a3ae0f4c
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
9264
diff
changeset
|
513 |
|
c525a3ae0f4c
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
9264
diff
changeset
|
514 If a project stores its source files in a version control system (VCS), |
|
c525a3ae0f4c
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
9264
diff
changeset
|
515 such as CVS, SVN, or Git, one needs to decide which files to commit. |
| 6255 | 516 |
| 517 All files created by @code{gnulib-tool}, except @file{gnulib-cache.m4}, | |
| 518 should be treated like generated source files, like for example a | |
| 519 @file{parser.c} file is generated from @file{parser.y}. | |
| 520 | |
|
8225
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
521 @itemize |
|
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
522 |
|
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
523 @item |
| 6255 | 524 In projects which commit all source files, whether generated or not, into |
|
9290
c525a3ae0f4c
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
9264
diff
changeset
|
525 their VCS, the @code{gnulib-tool} generated files should all be committed. |
|
10251
fe51b4da12d1
Update to match current gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
9814
diff
changeset
|
526 In this case, you also pass the option @samp{--no-vc-files} to |
|
fe51b4da12d1
Update to match current gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
9814
diff
changeset
|
527 @code{gnulib-tool}. |
| 6255 | 528 |
|
8225
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
529 Gnulib also contains files generated by @command{make} (and removed by |
| 9765 | 530 @code{make clean}), using information determined by @command{configure}. |
|
9290
c525a3ae0f4c
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
9264
diff
changeset
|
531 They should not be checked into the VCS, but instead added to |
| 9765 | 532 @file{.gitignore} or @file{.cvsignore}. |
| 533 When you have a Gnulib source file of the form @file{lib/foo.in.h}, the | |
| 534 corresponding @file{lib/foo.h} is such a file. | |
|
8225
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
535 |
|
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
536 @item |
|
9290
c525a3ae0f4c
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
9264
diff
changeset
|
537 In projects which customarily omit from their VCS all files that are generated |
| 6255 | 538 from other source files, all these files and directories would not be |
|
9290
c525a3ae0f4c
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
9264
diff
changeset
|
539 added into the VCS. The only file that must be added to the VCS is |
| 6255 | 540 @file{gnulib-cache.m4} in the M4 macros directory. Also, the script for |
|
9290
c525a3ae0f4c
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
9264
diff
changeset
|
541 restoring files not in the VCS, customarily called @file{autogen.sh} or |
| 6255 | 542 @file{bootstrap.sh}, will typically contain the statement for restoring |
| 543 the omitted files: | |
| 544 | |
| 545 @smallexample | |
| 546 $ gnulib-tool --update | |
| 547 @end smallexample | |
| 548 | |
| 549 The @samp{--update} option operates much like the @samp{--import} option, | |
| 550 but it does not offer the possibility to change the way Gnulib is used. | |
| 551 Also it does not report in the ChangeLogs the files that it had to add | |
| 552 because they were missing. | |
|
8225
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
553 |
|
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
554 @end itemize |
| 10829 | 555 |
| 556 | |
| 557 @node Unit tests | |
| 558 @section Bundling the unit tests of the Gnulib modules | |
| 559 | |
| 560 You can bundle the unit tests of the Gnulib modules together with your | |
| 561 package, through the @samp{--with-tests} option. Together with | |
| 562 @samp{--with-tests}, you also specify the directory for these tests | |
| 563 through the @samp{--tests-base} option. Of course, you need to add this | |
| 564 directory to the @code{SUBDIRS} variable in the @code{Makefile.am} of | |
| 565 the parent directory. | |
| 566 | |
| 567 The advantage of having the unit tests bundled is that when your program | |
| 568 has a problem on a particular platform, running the unit tests may help | |
| 569 determine quickly if the problem is on Gnulib's side or on your package's | |
| 570 side. Also, it helps verifying Gnulib's portability, of course. | |
| 571 | |
| 572 The unit tests will be compiled and run when the user runs @samp{make check}. | |
| 573 When the user runs only @samp{make}, the unit tests will not be compiled. | |
| 574 | |
| 575 In the @code{SUBDIRS} variable, it is useful to put the Gnulib tests directory | |
| 576 after the directory containing the other tests, not before: | |
| 577 | |
| 578 @smallexample | |
| 579 SUBDIRS = gnulib-lib src man tests gnulib-tests | |
| 580 @end smallexample | |
| 581 | |
| 582 @noindent | |
| 583 This will ensure that on platforms where there are test failures in either | |
| 584 directory, users will see and report the failures from the tests of your | |
| 585 program. | |
| 586 | |
| 587 Note: In packages which use more than one invocation of @code{gnulib-tool} | |
| 588 in the scope of the same @code{configure.ac}, you cannot use | |
| 589 @samp{--with-tests}. You will have to use a separate @code{configure.ac} | |
| 590 in this case. |