Mercurial > hg > octave-lojdl > gnulib-hg
annotate doc/gnulib-tool.texi @ 14776:a3bd209aea02
test-perror: rewrite to use init script
Make the test simpler, and also check for correct exit status.
* modules/perror-tests (Files): Add init.sh.
* tests/test-perror.sh: Use temporary directory.
Signed-off-by: Eric Blake <eblake@redhat.com>
| author | Eric Blake <eblake@redhat.com> |
|---|---|
| date | Fri, 20 May 2011 08:57:54 -0600 |
| parents | ed6716f98fb1 |
| children | 76127af7039f |
| rev | line source |
|---|---|
| 6255 | 1 @node Invoking gnulib-tool |
| 2 @chapter Invoking gnulib-tool | |
| 3 | |
|
14079
97fc9a21a8fb
maint: update almost all copyright ranges to include 2011
Jim Meyering <meyering@redhat.com>
parents:
13643
diff
changeset
|
4 @c Copyright (C) 2005-2011 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 | |
|
12876
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
42 * Which modules?:: Determining the needed set of Gnulib modules |
| 6255 | 43 * Initial import:: First import of Gnulib modules. |
| 44 * Modified imports:: Changing the import specification. | |
| 45 * 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
|
46 * 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
|
47 * gettextize and autopoint:: Caveat: @code{gettextize} and @code{autopoint} users! |
|
9567
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
48 * 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
|
49 * VCS Issues:: Integration with Version Control Systems. |
| 10829 | 50 * Unit tests:: Bundling the unit tests of the Gnulib modules. |
| 6255 | 51 @end menu |
| 52 | |
| 53 | |
|
12876
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
54 @node Which modules? |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
55 @section Finding modules |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
56 @cindex Finding modules |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
57 |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
58 There are three ways of finding the names of Gnulib modules that you can use |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
59 in your package: |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
60 |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
61 @itemize |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
62 @item |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
63 You have the complete module list, sorted according to categories, in |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
64 @url{http://www.gnu.org/software/gnulib/MODULES.html}. |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
65 |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
66 @item |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
67 If you are looking for a particular POSIX header or function replacement, |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
68 look in the chapters @ref{Header File Substitutes} and |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
69 @ref{Function Substitutes}. For headers and functions that are provided by |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
70 Glibc but not standardized by POSIX, look in the chapters |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
71 @ref{Glibc Header File Substitutes} and @ref{Glibc Function Substitutes}. |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
72 |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
73 @item |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
74 If you have already found the source file in Gnulib and are looking for the |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
75 module that contains this source file, you can use the command |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
76 @samp{gnulib-tool --find @var{filename}}. |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
77 @end itemize |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
78 |
|
030a6f5cbffd
Make it easier to find modules. New gnulib-tool option '--find'.
Bruno Haible <bruno@clisp.org>
parents:
12559
diff
changeset
|
79 |
| 6255 | 80 @node Initial import |
| 81 @section Initial import | |
| 82 @cindex initial import | |
| 83 | |
| 12904 | 84 Gnulib assumes that your project uses Autoconf. When using Gnulib, you |
| 85 will need to have Autoconf and Automake among your build tools. Note that | |
| 86 while the use of Automake in your project's top level directory is an | |
| 87 easy way to fulfil the Makefile conventions of the GNU coding standards, | |
| 88 Gnulib does not require it. But when you use Gnulib, Automake will be | |
| 89 used at least in a subdirectory of your project. | |
| 90 | |
| 91 Invoking @samp{gnulib-tool --import} will copy source files, create a | |
| 6255 | 92 @file{Makefile.am} to build them, generate a file @file{gnulib-comp.m4} with |
| 93 Autoconf M4 macro declarations used by @file{configure.ac}, and generate | |
| 94 a file @file{gnulib-cache.m4} containing the cached specification of how | |
| 95 Gnulib is used. | |
| 96 | |
| 97 Our example will be a library that uses Autoconf, Automake and | |
| 98 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
|
99 the package portable to C89 and C99 (which don't have @code{strdup}). |
| 6255 | 100 |
| 101 @example | |
| 102 ~/src/libfoo$ gnulib-tool --import strdup | |
| 103 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
|
104 absolute-header |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
105 extensions |
| 6255 | 106 strdup |
|
7944
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
107 string |
| 6255 | 108 File list: |
|
7944
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
109 lib/dummy.c |
| 6255 | 110 lib/strdup.c |
|
9264
a1355710e330
Rename string_.h to string.in.h.
Bruno Haible <bruno@clisp.org>
parents:
8817
diff
changeset
|
111 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
|
112 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
|
113 m4/extensions.m4 |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
114 m4/gnulib-common.m4 |
| 6255 | 115 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
|
116 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
|
117 Creating directory ./lib |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
118 Creating directory ./m4 |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
119 Copying file lib/dummy.c |
| 6255 | 120 Copying file lib/strdup.c |
|
9264
a1355710e330
Rename string_.h to string.in.h.
Bruno Haible <bruno@clisp.org>
parents:
8817
diff
changeset
|
121 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
|
122 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
|
123 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
|
124 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
|
125 Copying file m4/gnulib-tool.m4 |
| 6255 | 126 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
|
127 Copying file m4/string_h.m4 |
| 6255 | 128 Creating lib/Makefile.am |
| 129 Creating m4/gnulib-cache.m4 | |
| 130 Creating m4/gnulib-comp.m4 | |
| 131 Finished. | |
| 132 | |
| 133 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
|
134 #include <string.h> |
| 6255 | 135 |
| 136 Don't forget to | |
| 137 - add "lib/Makefile" to AC_CONFIG_FILES in ./configure.ac, | |
| 138 - mention "lib" in SUBDIRS in Makefile.am, | |
| 139 - mention "-I m4" in ACLOCAL_AMFLAGS in Makefile.am, | |
| 140 - invoke gl_EARLY in ./configure.ac, right after AC_PROG_CC, | |
| 141 - invoke gl_INIT in ./configure.ac. | |
| 142 ~/src/libfoo$ | |
| 143 @end example | |
| 144 | |
| 145 By default, the source code is copied into @file{lib/} and the M4 | |
| 146 macros in @file{m4/}. You can override these paths by using | |
| 147 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}. Some | |
| 13637 | 148 modules also provide other files necessary for building. These files |
| 6255 | 149 are copied into the directory specified by @samp{AC_CONFIG_AUX_DIR} in |
| 150 @file{configure.ac} or by the @code{--aux-dir=DIRECTORY} option. If | |
| 151 neither is specified, the current directory is assumed. | |
| 152 | |
| 153 @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
|
154 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
|
155 @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
|
156 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
|
157 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
|
158 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
|
159 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
|
160 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
|
161 this option is generally discouraged. |
| 6255 | 162 |
| 163 @code{gnulib-tool} will overwrite any pre-existing files, in | |
| 13637 | 164 particular @file{Makefile.am}. It is also possible to separate the |
| 6255 | 165 generated @file{Makefile.am} content (for building the gnulib library) |
| 13637 | 166 into a separate file, say @file{gnulib.mk}, that can be included by your |
| 167 handwritten @file{Makefile.am}, but this is a more advanced use of | |
| 168 @code{gnulib-tool}. | |
| 6255 | 169 |
| 170 Consequently, it is a good idea to choose directories that are not | |
| 171 already used by your projects, to separate gnulib imported files from | |
| 172 your own files. This approach is also useful if you want to avoid | |
| 173 conflicts between other tools (e.g., @code{gettextize} that also copy | |
| 174 M4 files into your package. Simon Josefsson successfully uses a source | |
| 175 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several | |
| 176 packages. | |
| 177 | |
| 178 After the @samp{--import} option on the command line comes the list of | |
| 179 Gnulib modules that you want to incorporate in your package. The names | |
| 180 of the modules coincide with the filenames in Gnulib's @file{modules/} | |
| 181 directory. | |
| 182 | |
| 183 Some Gnulib modules depend on other Gnulib modules. @code{gnulib-tool} | |
| 184 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
|
185 them explicitly. @code{gnulib-tool} will also memorize which dependent |
| 6255 | 186 modules it has added, so that when someday a dependency is dropped, the |
| 187 implicitly added module is dropped as well (unless you have explicitly | |
| 188 requested that module). | |
| 189 | |
|
6945
aa195d9ecb02
* functions.texi, gnulib-tool.texi, gnulib.texi: Fix some typos.
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
6842
diff
changeset
|
190 If you want to cut a dependency, i.e., not add a module although one of |
| 6255 | 191 your requested modules depends on it, you may use the option |
| 192 @samp{--avoid=@var{module}} to do so. Multiple uses of this option are | |
| 193 possible. Of course, you will then need to implement the same interface | |
| 194 as the removed module. | |
| 195 | |
| 196 A few manual steps are required to finish the initial import. | |
| 197 @code{gnulib-tool} printed a summary of these steps. | |
| 198 | |
|
6842
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
199 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
|
200 @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
|
201 your top-level @file{Makefile.am} file, as in: |
| 6255 | 202 |
| 203 @example | |
| 204 ACLOCAL_AMFLAGS = -I m4 | |
| 205 @end example | |
| 206 | |
| 207 You are now ready to call the M4 macros in @code{gnulib-comp.m4} from | |
| 208 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon | |
| 209 as possible after verifying that the C compiler is working. | |
| 210 Typically, this is immediately after @code{AC_PROG_CC}, as in: | |
| 211 | |
| 212 @example | |
| 213 ... | |
| 214 AC_PROG_CC | |
| 215 gl_EARLY | |
| 216 ... | |
| 217 @end example | |
| 218 | |
| 219 The core part of the gnulib checks are done by the macro | |
| 220 @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
|
221 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
|
222 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
|
223 @code{AC_MINIX}. For example: |
| 6255 | 224 |
| 225 @example | |
| 226 ... | |
| 227 # For gnulib. | |
| 228 gl_INIT | |
| 229 ... | |
| 230 @end example | |
| 231 | |
| 232 @code{gl_INIT} will in turn call the macros related with the | |
| 233 gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA} | |
| 234 or autoconf or automake macros like @code{AC_FUNC_ALLOCA} or | |
| 235 @code{AM_FUNC_GETLINE}. So there is no need to call those macros yourself | |
| 236 when you use the corresponding gnulib modules. | |
| 237 | |
| 238 You must also make sure that the gnulib library is built. Add the | |
| 239 @code{Makefile} in the gnulib source base directory to | |
| 240 @code{AC_CONFIG_FILES}, as in: | |
| 241 | |
| 242 @example | |
| 243 AC_CONFIG_FILES(... lib/Makefile ...) | |
| 244 @end example | |
| 245 | |
| 246 You must also make sure that @code{make} will recurse into the gnulib | |
| 247 directory. To achieve this, add the gnulib source base directory to a | |
| 248 @code{SUBDIRS} Makefile.am statement, as in: | |
| 249 | |
| 250 @example | |
| 251 SUBDIRS = lib | |
| 252 @end example | |
| 253 | |
| 254 or if you, more likely, already have a few entries in @code{SUBDIRS}, | |
| 255 you can add something like: | |
| 256 | |
| 257 @example | |
| 258 SUBDIRS += lib | |
| 259 @end example | |
| 260 | |
| 261 Finally, you have to add compiler and linker flags in the appropriate | |
| 262 source directories, so that you can make use of the gnulib library. | |
| 263 Since some modules (@samp{getopt}, for example) may copy files into | |
| 264 the build directory, @file{top_builddir/lib} is needed as well | |
| 265 as @file{top_srcdir/lib}. For example: | |
| 266 | |
| 267 @example | |
| 268 ... | |
|
9345
233439805e0a
Replace paragraph that was explaining old way of handling LIBOBJS.
Bruno Haible <bruno@clisp.org>
parents:
9290
diff
changeset
|
269 AM_CPPFLAGS = -I$(top_builddir)/lib -I$(top_srcdir)/lib |
| 6255 | 270 ... |
|
6842
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
271 LDADD = lib/libgnu.a |
| 6255 | 272 ... |
| 273 @end example | |
| 274 | |
| 275 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
|
276 example, you would need to make sure that @samp{#include <string.h>} |
| 6255 | 277 is evaluated when compiling all source code files, that want to make |
| 278 use of @code{strdup}. | |
| 279 | |
|
8146
b31580167c2b
New module 'time', so that apps can include <time.h> as per
Paul Eggert <eggert@cs.ucla.edu>
parents:
7944
diff
changeset
|
280 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
|
281 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
|
282 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
|
283 @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
|
284 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
|
285 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
|
286 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
|
287 @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
|
288 effect, if defined after the first system header file is included. |
| 6255 | 289 |
|
14561
ed6716f98fb1
maint: change "can not" to "cannot"
Jim Meyering <meyering@redhat.com>
parents:
14408
diff
changeset
|
290 Finally, note that you cannot use @code{AC_LIBOBJ} or |
|
9345
233439805e0a
Replace paragraph that was explaining old way of handling LIBOBJS.
Bruno Haible <bruno@clisp.org>
parents:
9290
diff
changeset
|
291 @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
|
292 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
|
293 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
|
294 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
|
295 @code{@@LTLIBOBJS@@} if using Libtool), whereas @file{lib/libgnu.a} |
| 9346 | 296 is built from the contents of a different variable, usually |
| 297 @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
|
298 |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
299 |
| 6255 | 300 @node Modified imports |
| 301 @section Modified imports | |
| 302 | |
| 303 You can at any moment decide to use Gnulib differently than the last time. | |
| 304 | |
|
13638
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
305 There are two ways to change how Gnulib is used. Which one you'll use, |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
306 depends on where you keep track of options and module names that you pass |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
307 to @code{gnulib-tool}. |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
308 |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
309 @itemize @bullet |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
310 @item |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
311 If you store the options and module names in a file under your own |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
312 control, such as @file{autogen.sh}, @file{bootstrap}, |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
313 @file{bootstrap.conf}, or similar, simply invoke @command{gnulib-tool} |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
314 again, with modified options and more or fewer module names. |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
315 |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
316 @item |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
317 @code{gnulib-tool} remembers which modules were used last time. If you |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
318 want to rely on @code{gnulib-tool}'s own memory of the last used |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
319 options and module names, you can use the commands |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
320 @command{gnulib-tool --add-import} and |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
321 @command{gnulib-tool --remove-import}. |
| 6255 | 322 |
|
13638
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
323 So, if you only want to use more Gnulib modules, simply invoke |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
324 @command{gnulib-tool --add-import @var{new-modules}}. The list of |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
325 modules that you pass after @samp{--add-import} is @emph{added} to the |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
326 previous list of modules. |
| 6255 | 327 |
|
13638
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
328 Similarly, if you want to use fewer Gnulib modules, simply invoke |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
329 @command{gnulib-tool --remove-import @var{unneeded-modules}}. The list |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
330 of modules that you pass after @samp{--remove-import} is @emph{removed} |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
331 from the previous list of modules. Note that if a module is then still |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
332 needed as dependency of other modules, it will be used nevertheless. |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
333 If you want to @emph{really} not use a module any more, regardless of |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
334 whether other modules may need it, you need to use the @samp{--avoid} |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
335 option. |
| 6255 | 336 |
|
13638
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
337 For other changes, such as different choices of @samp{--lib}, |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
338 @samp{--source-base} or @samp{--aux-dir}, the normal way is to |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
339 modify manually the file @file{gnulib-cache.m4} in the M4 macros |
|
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
340 directory, then launch @samp{gnulib-tool --add-import}. |
| 6255 | 341 |
| 342 The only change for which this doesn't work is a change of the | |
| 343 @samp{--m4-base} directory. Because, when you pass a different value of | |
| 344 @samp{--m4-base}, @code{gnulib-tool} will not find the previous | |
| 13643 | 345 @file{gnulib-cache.m4} file any more. A possible solution is to |
|
13638
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
346 manually copy the @file{gnulib-cache.m4} into the new M4 macro directory. |
| 6255 | 347 |
| 13643 | 348 In the @file{gnulib-cache.m4} file, the macros have the following meaning: |
| 6255 | 349 @table @code |
| 350 @item gl_MODULES | |
| 351 The argument is a space separated list of the requested modules, not including | |
| 352 dependencies. | |
| 353 | |
| 354 @item gl_AVOID | |
| 355 The argument is a space separated list of modules that should not be used, | |
| 356 even if they occur as dependencies. Corresponds to the @samp{--avoid} | |
| 357 command line argument. | |
| 358 | |
| 359 @item gl_SOURCE_BASE | |
|
6724
68cc9b819542
* gnulib-tool.texi (Modified imports): pathname -> file name.
Paul Eggert <eggert@cs.ucla.edu>
parents:
6255
diff
changeset
|
360 The argument is the relative file name of the directory containing the gnulib |
| 6255 | 361 source files (mostly *.c and *.h files). Corresponds to the |
| 362 @samp{--source-base} command line argument. | |
| 363 | |
| 364 @item gl_M4_BASE | |
|
6724
68cc9b819542
* gnulib-tool.texi (Modified imports): pathname -> file name.
Paul Eggert <eggert@cs.ucla.edu>
parents:
6255
diff
changeset
|
365 The argument is the relative file name of the directory containing the gnulib |
| 6255 | 366 M4 macros (*.m4 files). Corresponds to the @samp{--m4-base} command line |
| 367 argument. | |
| 368 | |
| 369 @item gl_TESTS_BASE | |
|
6724
68cc9b819542
* gnulib-tool.texi (Modified imports): pathname -> file name.
Paul Eggert <eggert@cs.ucla.edu>
parents:
6255
diff
changeset
|
370 The argument is the relative file name of the directory containing the gnulib |
| 6255 | 371 unit test files. Corresponds to the @samp{--tests-base} command line argument. |
| 372 | |
| 373 @item gl_LIB | |
| 374 The argument is the name of the library to be created. Corresponds to the | |
| 375 @samp{--lib} command line argument. | |
| 376 | |
| 377 @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
|
378 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
|
379 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
|
380 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
|
381 argument. |
| 6255 | 382 |
| 383 @item gl_LIBTOOL | |
| 384 The presence of this macro corresponds to the @samp{--libtool} command line | |
| 7077 | 385 argument and to the absence of the @samp{--no-libtool} command line argument. |
| 386 It takes no arguments. | |
| 6255 | 387 |
| 388 @item gl_MACRO_PREFIX | |
| 389 The argument is the prefix to use for macros in the @file{gnulib-comp.m4} | |
| 390 file. Corresponds to the @samp{--macro-prefix} command line argument. | |
| 391 @end table | |
| 392 | |
|
13638
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
393 @end itemize |
|
9412
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
394 |
| 6255 | 395 @node Simple update |
| 396 @section Simple update | |
| 397 | |
| 398 When you want to update to a more recent version of Gnulib, without | |
| 399 changing the list of modules or other parameters, a simple call | |
| 400 does it: | |
| 401 | |
| 402 @smallexample | |
|
13638
8ae47cf4002f
gnulib-tool: Change --import. New options --add/remove-import.
Bruno Haible <bruno@clisp.org>
parents:
13637
diff
changeset
|
403 $ gnulib-tool --add-import |
| 6255 | 404 @end smallexample |
| 405 | |
|
9412
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
406 @noindent |
| 6255 | 407 This will create, update or remove files, as needed. |
| 408 | |
|
9412
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
409 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
|
410 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
|
411 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
|
412 your project. |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
413 |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
414 |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
415 @node Source changes |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
416 @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
|
417 |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
418 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
|
419 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
|
420 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
|
421 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
|
422 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
|
423 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
|
424 @file{/usr/include/}. |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
425 |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
426 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
|
427 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
|
428 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
|
429 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
|
430 @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
|
431 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
|
432 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
|
433 |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
434 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
|
435 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
|
436 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
|
437 |
|
f5d73cf73b89
Document some more things the gnulib user must be aware of.
Bruno Haible <bruno@clisp.org>
parents:
9346
diff
changeset
|
438 |
|
9808
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
439 @node gettextize and autopoint |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
440 @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
|
441 |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
442 @cindex gettextize, caveat |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
443 @cindex autopoint, caveat |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
444 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
|
445 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
|
446 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
|
447 @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
|
448 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
|
449 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
|
450 imported, and vice versa. |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
451 |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
452 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
|
453 @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
|
454 @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
|
455 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
|
456 |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
457 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
|
458 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
|
459 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
|
460 be updated immediately. |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
461 |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
462 The solution is therefore: |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
463 |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
464 @enumerate |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
465 @item |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
466 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
|
467 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
|
468 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
|
469 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
|
470 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
|
471 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
|
472 |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
473 @item |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
474 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
|
475 afterwards. |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
476 |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
477 @item |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
478 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
|
479 @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
|
480 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
|
481 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
|
482 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
|
483 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
|
484 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
|
485 @code{gettextize} followed by @code{gnulib-tool}. |
|
14408
3d18c39304e4
doc: Improve doc regarding autopoint vs. gnulib.
Bruno Haible <bruno@clisp.org>
parents:
14079
diff
changeset
|
486 |
|
3d18c39304e4
doc: Improve doc regarding autopoint vs. gnulib.
Bruno Haible <bruno@clisp.org>
parents:
14079
diff
changeset
|
487 @item |
|
3d18c39304e4
doc: Improve doc regarding autopoint vs. gnulib.
Bruno Haible <bruno@clisp.org>
parents:
14079
diff
changeset
|
488 When you invoke @code{autoreconf} after @code{gnulib-tool}, make sure to |
|
3d18c39304e4
doc: Improve doc regarding autopoint vs. gnulib.
Bruno Haible <bruno@clisp.org>
parents:
14079
diff
changeset
|
489 not invoke @code{autopoint} a second time, by setting the @code{AUTOPOINT} |
|
3d18c39304e4
doc: Improve doc regarding autopoint vs. gnulib.
Bruno Haible <bruno@clisp.org>
parents:
14079
diff
changeset
|
490 environment variable, like this: |
|
3d18c39304e4
doc: Improve doc regarding autopoint vs. gnulib.
Bruno Haible <bruno@clisp.org>
parents:
14079
diff
changeset
|
491 @smallexample |
|
3d18c39304e4
doc: Improve doc regarding autopoint vs. gnulib.
Bruno Haible <bruno@clisp.org>
parents:
14079
diff
changeset
|
492 $ env AUTOPOINT=true autoreconf --install |
|
3d18c39304e4
doc: Improve doc regarding autopoint vs. gnulib.
Bruno Haible <bruno@clisp.org>
parents:
14079
diff
changeset
|
493 @end smallexample |
|
9808
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
494 @end enumerate |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
495 |
|
b5b092e3f5c7
Document how to resolve the conflicts between gnulib and gettext.
Bruno Haible <bruno@clisp.org>
parents:
9765
diff
changeset
|
496 |
|
9567
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
497 @node Localization |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
498 @section Handling Gnulib's own message translations |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
499 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
500 Gnulib provides some functions that emit translatable messages using GNU |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
501 @code{gettext}. The @samp{gnulib} domain at the |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
502 @url{http://translationproject.org/, Translation Project} collects |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
503 translations of these messages, which you should incorporate into your |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
504 own programs. |
|
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 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
|
507 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
|
508 @file{po/POTFILES.in} file. This will cause all the relevant |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
509 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
|
510 this POT file to the Translation Project, translators will normally fill |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
511 in the translations of the Gnulib strings from their ``translation |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
512 memory'', and send you back updated PO files. |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
513 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
514 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
|
515 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
|
516 and provide a different translation than another translator, or the |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
517 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
|
518 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
|
519 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
|
520 incorporate their work on request. |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
521 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
522 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
|
523 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
|
524 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
|
525 separate directory with its own @file{POTFILES.in}, and fetch current |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
526 translations directly from the Translation Project (using |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
527 @command{rsync} or @command{wget}, whichever is available). |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
528 The POT file in this directory will be called |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
529 @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
|
530 @code{--po-domain} option (typically the same as the package name). |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
531 This causes these translations to reside in a separate message domain, |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
532 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
|
533 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
|
534 possibly different versions of Gnulib. |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
535 When you use these options, the functions in Gnulib are built |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
536 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
|
537 default domain set by @code{textdomain}. |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
538 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
539 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
|
540 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
|
541 initializes locale-dependent behavior. Where you would normally write |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
542 something like: |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
543 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
544 @example |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
545 @group |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
546 setlocale (LC_ALL, ""); |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
547 bindtextdomain (PACKAGE, LOCALEDIR); |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
548 textdomain (PACKAGE); |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
549 @end group |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
550 @end example |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
551 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
552 @noindent |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
553 you should add an additional @code{bindtextdomain} call to inform |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
554 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
|
555 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
556 @example |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
557 @group |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
558 bindtextdomain (PACKAGE "-gnulib", LOCALEDIR); |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
559 @end group |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
560 @end example |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
561 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
562 (This example assumes that the @var{domain} that you specified |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
563 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
|
564 preprocessor macro.) |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
565 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
566 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
|
567 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
|
568 functions will not be affected. |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
569 |
|
17eb10d3ae34
New section 'Localization'.
Bruno Haible <bruno@clisp.org>
parents:
9417
diff
changeset
|
570 |
|
9290
c525a3ae0f4c
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
9264
diff
changeset
|
571 @node VCS Issues |
|
c525a3ae0f4c
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
9264
diff
changeset
|
572 @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
|
573 |
|
c525a3ae0f4c
Talk about git instead or in addition to cvs.
Bruno Haible <bruno@clisp.org>
parents:
9264
diff
changeset
|
574 If a project stores its source files in a version control system (VCS), |
|
12976
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
575 such as CVS, Subversion, or Git, one needs to decide which files to commit. |
| 6255 | 576 |
|
12976
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
577 In principle, all files created by @code{gnulib-tool}, except |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
578 @file{gnulib-cache.m4}, can be treated like generated source files, |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
579 like for example a @file{parser.c} file generated from |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
580 @file{parser.y}. Alternatively, they can be considered source files |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
581 and updated manually. |
| 6255 | 582 |
|
12976
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
583 Here are the three different approaches in common use. Each has its |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
584 place, and you should use whichever best suits your particular project |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
585 and development methods. |
|
8225
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
586 |
|
12976
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
587 @enumerate |
|
8225
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
588 @item |
|
12976
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
589 In projects which commit all source files, whether generated or not, |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
590 into their VCS, the @code{gnulib-tool} generated files should all be |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
591 committed. In this case, you should pass the option |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
592 @samp{--no-vc-files} to @code{gnulib-tool}, which avoids alteration of |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
593 VCS-related files such as @file{.cvsignore}. |
| 6255 | 594 |
|
8225
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
595 Gnulib also contains files generated by @command{make} (and removed by |
|
12976
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
596 @code{make clean}), using information determined by |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
597 @command{configure}. For a Gnulib source file of the form |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
598 @file{lib/foo.in.h}, the corresponding @file{lib/foo.h} is such a |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
599 @command{make}-generated file. These should @emph{not} be checked |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
600 into the VCS, but instead added to @file{.cvsignore} or equivalent. |
|
8225
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
601 |
|
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
602 @item |
|
12976
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
603 In projects which customarily omit from their VCS all files that are |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
604 generated from other source files, none of these files and directories |
|
13639
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
605 are added into the VCS. As described in @ref{Modified imports}, there |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
606 are two ways to keep track of options and module names that are passed |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
607 to @code{gnulib-tool}. The command for restoring the omitted files |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
608 depends on it: |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
609 |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
610 @itemize @bullet |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
611 @item |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
612 If they are stored in a file other than @code{gnulib-cache.m4}, such as |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
613 @file{autogen.sh}, @file{bootstrap}, @file{bootstrap.conf}, or similar, |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
614 the restoration command is the entire @code{gnulib-tool ... --import ...} |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
615 invocation with all options and module names. |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
616 |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
617 @item |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
618 If the project relies on @code{gnulib-tool}'s memory of the last used |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
619 options and module names, then the file @file{gnulib-cache.m4} in the M4 |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
620 macros directory must be added to the VCS, and the restoration command |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
621 is: |
| 6255 | 622 |
| 623 @smallexample | |
| 624 $ gnulib-tool --update | |
| 625 @end smallexample | |
| 626 | |
|
13639
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
627 The @samp{--update} option operates much like the @samp{--add-import} |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
628 option, but it does not offer the possibility to change the way Gnulib is |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
629 used. Also it does not report in the ChangeLogs the files that it had to |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
630 add because they were missing. |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
631 |
|
b68fa3d66e47
Update doc about gnulib-tool.
Bruno Haible <bruno@clisp.org>
parents:
13638
diff
changeset
|
632 @end itemize |
|
8225
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
633 |
|
12977
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
634 Gnulib includes the file @file{build-aux/bootstrap} to aid a developer |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
635 in using this setup. Furthermore, in projects that use git for |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
636 version control, it is possible to use a git submodule containing the |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
637 precise commit of the gnulib repository, so that each developer |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
638 running @file{bootstrap} will get the same version of all |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
639 gnulib-provided files. The location of the submodule can be chosen to |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
640 fit the package's needs; here's how to initially create the submodule |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
641 in the directory @file{.gnulib}: |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
642 |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
643 @smallexample |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
644 $ dir=.gnulib |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
645 $ git submodule add -- git://git.sv.gnu.org/gnulib.git $dir |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
646 $ git config alias.syncsub "submodule foreach git pull origin master" |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
647 @end smallexample |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
648 |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
649 @noindent |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
650 Thereafter, @file{bootstrap} can run this command to update the |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
651 submodule to the recorded checkout level: |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
652 |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
653 @smallexample |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
654 git submodule update --init $dir |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
655 @end smallexample |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
656 |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
657 @noindent |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
658 and a developer can use this sequence to update to a newer version of |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
659 gnulib: |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
660 |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
661 @smallexample |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
662 $ git syncsub |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
663 $ git add $dir |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
664 $ ./bootstrap |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
665 @end smallexample |
|
a8f8215a262d
gnulib-tool.texi: mention possibility of git submodule
Eric Blake <eblake@redhat.com>
parents:
12976
diff
changeset
|
666 |
|
12976
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
667 @item |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
668 Some projects take a ``middle road'': they do commit Gnulib source |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
669 files as in the first approach, but they do not commit other derived |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
670 files, such as a @code{Makefile.in} generated by Automake. This |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
671 increases the size and complexity of the repository, but can help |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
672 occasional contributors by not requiring them to have a full Gnulib |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
673 checkout to do a build, and all developers by ensuring that all |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
674 developers are working with the same version of Gnulib in the |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
675 repository. It also supports multiple Gnulib instances within a |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
676 project. It remains important not to commit the |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
677 @command{make}-generated files, as described above. |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
678 |
|
85ed9679cfa7
describe third option of committing gnulib files while skipping others
Karl Berry <karl@freefriends.org>
parents:
12904
diff
changeset
|
679 @end enumerate |
| 10829 | 680 |
| 681 | |
| 682 @node Unit tests | |
| 683 @section Bundling the unit tests of the Gnulib modules | |
| 684 | |
| 685 You can bundle the unit tests of the Gnulib modules together with your | |
| 686 package, through the @samp{--with-tests} option. Together with | |
| 687 @samp{--with-tests}, you also specify the directory for these tests | |
| 688 through the @samp{--tests-base} option. Of course, you need to add this | |
| 689 directory to the @code{SUBDIRS} variable in the @code{Makefile.am} of | |
| 690 the parent directory. | |
| 691 | |
| 692 The advantage of having the unit tests bundled is that when your program | |
| 693 has a problem on a particular platform, running the unit tests may help | |
| 694 determine quickly if the problem is on Gnulib's side or on your package's | |
| 695 side. Also, it helps verifying Gnulib's portability, of course. | |
| 696 | |
| 697 The unit tests will be compiled and run when the user runs @samp{make check}. | |
| 698 When the user runs only @samp{make}, the unit tests will not be compiled. | |
| 699 | |
| 700 In the @code{SUBDIRS} variable, it is useful to put the Gnulib tests directory | |
| 701 after the directory containing the other tests, not before: | |
| 702 | |
| 703 @smallexample | |
| 704 SUBDIRS = gnulib-lib src man tests gnulib-tests | |
| 705 @end smallexample | |
| 706 | |
| 707 @noindent | |
| 708 This will ensure that on platforms where there are test failures in either | |
| 709 directory, users will see and report the failures from the tests of your | |
| 710 program. | |
| 711 | |
| 712 Note: In packages which use more than one invocation of @code{gnulib-tool} | |
| 713 in the scope of the same @code{configure.ac}, you cannot use | |
| 714 @samp{--with-tests}. You will have to use a separate @code{configure.ac} | |
| 715 in this case. |