Mercurial > hg > octave-lojdl > gnulib-hg
annotate doc/gnulib-tool.texi @ 8817:65a118c5879d
2007-05-16 Thien-Thi Nguyen <ttn@gnuvola.org> (tiny change)
* doc/gnulib-tool.texi (CVS Issues): Fix typo.
| author | Bruno Haible <bruno@clisp.org> |
|---|---|
| date | Wed, 16 May 2007 10:07:20 +0000 |
| parents | c1709670004e |
| children | a1355710e330 |
| rev | line source |
|---|---|
| 6255 | 1 @node Invoking gnulib-tool |
| 2 @chapter Invoking gnulib-tool | |
| 3 | |
|
7944
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
4 @c Copyright (C) 2005, 2006, 2007 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 |
|
adb21c293305
Add copyright notices to long-enough files that lack them, since
Paul Eggert <eggert@cs.ucla.edu>
parents:
7077
diff
changeset
|
7 @c under the terms of the GNU Free Documentation License, Version 1.2 or |
|
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 |
|
6842
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
24 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
|
25 @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
|
26 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
|
27 @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
|
28 a real run without changing anything. |
| 6255 | 29 |
| 30 @menu | |
| 31 * Initial import:: First import of Gnulib modules. | |
| 32 * Modified imports:: Changing the import specification. | |
| 33 * Simple update:: Tracking Gnulib development. | |
| 34 * CVS Issues:: Integration with CVS. | |
| 35 @end menu | |
| 36 | |
| 37 | |
| 38 @node Initial import | |
| 39 @section Initial import | |
| 40 @cindex initial import | |
| 41 | |
| 42 Gnulib assumes your project uses Autoconf and Automake. Invoking | |
| 43 @samp{gnulib-tool --import} will copy source files, create a | |
| 44 @file{Makefile.am} to build them, generate a file @file{gnulib-comp.m4} with | |
| 45 Autoconf M4 macro declarations used by @file{configure.ac}, and generate | |
| 46 a file @file{gnulib-cache.m4} containing the cached specification of how | |
| 47 Gnulib is used. | |
| 48 | |
| 49 Our example will be a library that uses Autoconf, Automake and | |
| 50 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
|
51 the package portable to C89 and C99 (which don't have @code{strdup}). |
| 6255 | 52 |
| 53 @example | |
| 54 ~/src/libfoo$ gnulib-tool --import strdup | |
| 55 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
|
56 absolute-header |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
57 extensions |
| 6255 | 58 strdup |
|
7944
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
59 string |
| 6255 | 60 File list: |
|
7944
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
61 lib/dummy.c |
| 6255 | 62 lib/strdup.c |
|
7944
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
63 lib/string_.h |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
64 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
|
65 m4/extensions.m4 |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
66 m4/gnulib-common.m4 |
| 6255 | 67 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
|
68 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
|
69 Creating directory ./lib |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
70 Creating directory ./m4 |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
71 Copying file lib/dummy.c |
| 6255 | 72 Copying file lib/strdup.c |
|
7944
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
73 Copying file lib/string_.h |
|
a1d177cd9523
* doc/gnulib-tool.texi (Initial import): Update to match current
Paul Eggert <eggert@cs.ucla.edu>
parents:
7460
diff
changeset
|
74 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
|
75 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
|
76 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
|
77 Copying file m4/gnulib-tool.m4 |
| 6255 | 78 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
|
79 Copying file m4/string_h.m4 |
| 6255 | 80 Creating lib/Makefile.am |
| 81 Creating m4/gnulib-cache.m4 | |
| 82 Creating m4/gnulib-comp.m4 | |
| 83 Finished. | |
| 84 | |
| 85 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
|
86 #include <string.h> |
| 6255 | 87 |
| 88 Don't forget to | |
| 89 - add "lib/Makefile" to AC_CONFIG_FILES in ./configure.ac, | |
| 90 - mention "lib" in SUBDIRS in Makefile.am, | |
| 91 - mention "-I m4" in ACLOCAL_AMFLAGS in Makefile.am, | |
| 92 - invoke gl_EARLY in ./configure.ac, right after AC_PROG_CC, | |
| 93 - invoke gl_INIT in ./configure.ac. | |
| 94 ~/src/libfoo$ | |
| 95 @end example | |
| 96 | |
| 97 By default, the source code is copied into @file{lib/} and the M4 | |
| 98 macros in @file{m4/}. You can override these paths by using | |
| 99 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}. Some | |
| 100 modules also provide other files necessary for building. These files | |
| 101 are copied into the directory specified by @samp{AC_CONFIG_AUX_DIR} in | |
| 102 @file{configure.ac} or by the @code{--aux-dir=DIRECTORY} option. If | |
| 103 neither is specified, the current directory is assumed. | |
| 104 | |
| 105 @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
|
106 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
|
107 @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
|
108 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
|
109 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
|
110 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
|
111 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
|
112 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
|
113 this option is generally discouraged. |
| 6255 | 114 |
| 115 @code{gnulib-tool} will overwrite any pre-existing files, in | |
| 116 particular @file{Makefile.am}. Unfortunately, separating the | |
| 117 generated @file{Makefile.am} content (for building the gnulib library) | |
| 118 into a separate file, say @file{gnulib.mk}, that could be included | |
| 119 by your handwritten @file{Makefile.am} is not possible, due to how | |
| 120 variable assignments are handled by Automake. | |
| 121 | |
| 122 Consequently, it is a good idea to choose directories that are not | |
| 123 already used by your projects, to separate gnulib imported files from | |
| 124 your own files. This approach is also useful if you want to avoid | |
| 125 conflicts between other tools (e.g., @code{gettextize} that also copy | |
| 126 M4 files into your package. Simon Josefsson successfully uses a source | |
| 127 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several | |
| 128 packages. | |
| 129 | |
| 130 After the @samp{--import} option on the command line comes the list of | |
| 131 Gnulib modules that you want to incorporate in your package. The names | |
| 132 of the modules coincide with the filenames in Gnulib's @file{modules/} | |
| 133 directory. | |
| 134 | |
| 135 Some Gnulib modules depend on other Gnulib modules. @code{gnulib-tool} | |
| 136 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
|
137 them explicitly. @code{gnulib-tool} will also memorize which dependent |
| 6255 | 138 modules it has added, so that when someday a dependency is dropped, the |
| 139 implicitly added module is dropped as well (unless you have explicitly | |
| 140 requested that module). | |
| 141 | |
|
6945
aa195d9ecb02
* functions.texi, gnulib-tool.texi, gnulib.texi: Fix some typos.
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
6842
diff
changeset
|
142 If you want to cut a dependency, i.e., not add a module although one of |
| 6255 | 143 your requested modules depends on it, you may use the option |
| 144 @samp{--avoid=@var{module}} to do so. Multiple uses of this option are | |
| 145 possible. Of course, you will then need to implement the same interface | |
| 146 as the removed module. | |
| 147 | |
| 148 A few manual steps are required to finish the initial import. | |
| 149 @code{gnulib-tool} printed a summary of these steps. | |
| 150 | |
|
6842
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
151 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
|
152 @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
|
153 your top-level @file{Makefile.am} file, as in: |
| 6255 | 154 |
| 155 @example | |
| 156 ACLOCAL_AMFLAGS = -I m4 | |
| 157 @end example | |
| 158 | |
| 159 You are now ready to call the M4 macros in @code{gnulib-comp.m4} from | |
| 160 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon | |
| 161 as possible after verifying that the C compiler is working. | |
| 162 Typically, this is immediately after @code{AC_PROG_CC}, as in: | |
| 163 | |
| 164 @example | |
| 165 ... | |
| 166 AC_PROG_CC | |
| 167 gl_EARLY | |
| 168 ... | |
| 169 @end example | |
| 170 | |
| 171 The core part of the gnulib checks are done by the macro | |
| 172 @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
|
173 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
|
174 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
|
175 @code{AC_MINIX}. For example: |
| 6255 | 176 |
| 177 @example | |
| 178 ... | |
| 179 # For gnulib. | |
| 180 gl_INIT | |
| 181 ... | |
| 182 @end example | |
| 183 | |
| 184 @code{gl_INIT} will in turn call the macros related with the | |
| 185 gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA} | |
| 186 or autoconf or automake macros like @code{AC_FUNC_ALLOCA} or | |
| 187 @code{AM_FUNC_GETLINE}. So there is no need to call those macros yourself | |
| 188 when you use the corresponding gnulib modules. | |
| 189 | |
| 190 You must also make sure that the gnulib library is built. Add the | |
| 191 @code{Makefile} in the gnulib source base directory to | |
| 192 @code{AC_CONFIG_FILES}, as in: | |
| 193 | |
| 194 @example | |
| 195 AC_CONFIG_FILES(... lib/Makefile ...) | |
| 196 @end example | |
| 197 | |
| 198 You must also make sure that @code{make} will recurse into the gnulib | |
| 199 directory. To achieve this, add the gnulib source base directory to a | |
| 200 @code{SUBDIRS} Makefile.am statement, as in: | |
| 201 | |
| 202 @example | |
| 203 SUBDIRS = lib | |
| 204 @end example | |
| 205 | |
| 206 or if you, more likely, already have a few entries in @code{SUBDIRS}, | |
| 207 you can add something like: | |
| 208 | |
| 209 @example | |
| 210 SUBDIRS += lib | |
| 211 @end example | |
| 212 | |
| 213 Finally, you have to add compiler and linker flags in the appropriate | |
| 214 source directories, so that you can make use of the gnulib library. | |
| 215 Since some modules (@samp{getopt}, for example) may copy files into | |
| 216 the build directory, @file{top_builddir/lib} is needed as well | |
| 217 as @file{top_srcdir/lib}. For example: | |
| 218 | |
| 219 @example | |
| 220 ... | |
| 221 AM_CPPFLAGS = -I$(top_srcdir)/lib -I$(top_builddir)/lib | |
| 222 ... | |
|
6842
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
223 LDADD = lib/libgnu.a |
| 6255 | 224 ... |
| 225 @end example | |
| 226 | |
| 227 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
|
228 example, you would need to make sure that @samp{#include <string.h>} |
| 6255 | 229 is evaluated when compiling all source code files, that want to make |
| 230 use of @code{strdup}. | |
| 231 | |
|
8146
b31580167c2b
New module 'time', so that apps can include <time.h> as per
Paul Eggert <eggert@cs.ucla.edu>
parents:
7944
diff
changeset
|
232 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
|
233 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
|
234 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
|
235 @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
|
236 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
|
237 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
|
238 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
|
239 @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
|
240 effect, if defined after the first system header file is included. |
| 6255 | 241 |
|
6842
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
242 A final word of warning: Gnulib currently assumes it will be |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
243 responsible for @emph{all} functions that end up in the Autoconf |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
244 @code{@@LIBOBJS@@} variables (and/or @code{@@LTLIBOBJS@@} if using |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
245 Libtool), e.g., those specified in @code{AC_REPLACE_FUNCS} in your |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
246 @file{configure.ac}. Therefore, if you have any functions which are |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
247 not covered by Gnulib which need that treatment, you have to |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
248 essentially reimplement AC_REPLACE_FUNCS using different names; for an |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
249 example, see the Findutils sources. Perhaps this will be improved in |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
250 the future. |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
251 |
|
1b6de7675435
mention that Gnulib takes over LIBOBJS
Karl Berry <karl@freefriends.org>
parents:
6724
diff
changeset
|
252 |
| 6255 | 253 @node Modified imports |
| 254 @section Modified imports | |
| 255 | |
| 256 You can at any moment decide to use Gnulib differently than the last time. | |
| 257 | |
| 258 If you only want to use more Gnulib modules, simply invoke | |
| 259 @command{gnulib-tool --import @var{new-modules}}. @code{gnulib-tool} | |
| 260 remembers which modules were used last time. The list of modules that | |
| 261 you pass after @samp{--import} is @emph{added} to the previous list of | |
| 262 modules. | |
| 263 | |
| 264 For most changes, such as added or removed modules, or even different | |
| 265 choices of @samp{--lib}, @samp{--source-base} or @samp{--aux-dir}, there | |
| 266 are two ways to perform the change. | |
| 267 | |
| 268 The standard way is to modify manually the file @file{gnulib-cache.m4} | |
| 269 in the M4 macros directory, then launch @samp{gnulib-tool --import}. | |
| 270 | |
| 271 The other way is to call @command{gnulib-tool} again, with the changed | |
| 272 command-line options. Note that this doesn't let you remove modules, | |
| 273 because as you just learned, the list of modules is always cumulated. | |
| 274 Also this way is often impractical, because you don't remember the way | |
| 275 you invoked @code{gnulib-tool} last time. | |
| 276 | |
| 277 The only change for which this doesn't work is a change of the | |
| 278 @samp{--m4-base} directory. Because, when you pass a different value of | |
| 279 @samp{--m4-base}, @code{gnulib-tool} will not find the previous | |
| 280 @file{gnulib-cache.m4} file any more... A possible solution is to manually | |
| 281 copy the @file{gnulib-cache.m4} into the new M4 macro directory. | |
| 282 | |
| 283 In the @file{gnulib-cache.m4}, the macros have the following meaning: | |
| 284 @table @code | |
| 285 @item gl_MODULES | |
| 286 The argument is a space separated list of the requested modules, not including | |
| 287 dependencies. | |
| 288 | |
| 289 @item gl_AVOID | |
| 290 The argument is a space separated list of modules that should not be used, | |
| 291 even if they occur as dependencies. Corresponds to the @samp{--avoid} | |
| 292 command line argument. | |
| 293 | |
| 294 @item gl_SOURCE_BASE | |
|
6724
68cc9b819542
* gnulib-tool.texi (Modified imports): pathname -> file name.
Paul Eggert <eggert@cs.ucla.edu>
parents:
6255
diff
changeset
|
295 The argument is the relative file name of the directory containing the gnulib |
| 6255 | 296 source files (mostly *.c and *.h files). Corresponds to the |
| 297 @samp{--source-base} command line argument. | |
| 298 | |
| 299 @item gl_M4_BASE | |
|
6724
68cc9b819542
* gnulib-tool.texi (Modified imports): pathname -> file name.
Paul Eggert <eggert@cs.ucla.edu>
parents:
6255
diff
changeset
|
300 The argument is the relative file name of the directory containing the gnulib |
| 6255 | 301 M4 macros (*.m4 files). Corresponds to the @samp{--m4-base} command line |
| 302 argument. | |
| 303 | |
| 304 @item gl_TESTS_BASE | |
|
6724
68cc9b819542
* gnulib-tool.texi (Modified imports): pathname -> file name.
Paul Eggert <eggert@cs.ucla.edu>
parents:
6255
diff
changeset
|
305 The argument is the relative file name of the directory containing the gnulib |
| 6255 | 306 unit test files. Corresponds to the @samp{--tests-base} command line argument. |
| 307 | |
| 308 @item gl_LIB | |
| 309 The argument is the name of the library to be created. Corresponds to the | |
| 310 @samp{--lib} command line argument. | |
| 311 | |
| 312 @item gl_LGPL | |
| 313 The presence of this macro corresponds to the @samp{--lgpl} command line | |
| 314 argument. It takes no arguments. | |
| 315 | |
| 316 @item gl_LIBTOOL | |
| 317 The presence of this macro corresponds to the @samp{--libtool} command line | |
| 7077 | 318 argument and to the absence of the @samp{--no-libtool} command line argument. |
| 319 It takes no arguments. | |
| 6255 | 320 |
| 321 @item gl_MACRO_PREFIX | |
| 322 The argument is the prefix to use for macros in the @file{gnulib-comp.m4} | |
| 323 file. Corresponds to the @samp{--macro-prefix} command line argument. | |
| 324 @end table | |
| 325 | |
| 326 @node Simple update | |
| 327 @section Simple update | |
| 328 | |
| 329 When you want to update to a more recent version of Gnulib, without | |
| 330 changing the list of modules or other parameters, a simple call | |
| 331 does it: | |
| 332 | |
| 333 @smallexample | |
| 334 $ gnulib-tool --import | |
| 335 @end smallexample | |
| 336 | |
| 337 This will create, update or remove files, as needed. | |
| 338 | |
| 339 @node CVS Issues | |
| 340 @section CVS Issues | |
| 341 | |
| 342 All files created by @code{gnulib-tool}, except @file{gnulib-cache.m4}, | |
| 343 should be treated like generated source files, like for example a | |
| 344 @file{parser.c} file is generated from @file{parser.y}. | |
| 345 | |
|
8225
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
346 @itemize |
|
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
347 |
|
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
348 @item |
| 6255 | 349 In projects which commit all source files, whether generated or not, into |
| 350 CVS, the @code{gnulib-tool} generated files should all be committed. | |
| 351 | |
|
8225
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
352 Gnulib also contains files generated by @command{make} (and removed by |
|
8817
65a118c5879d
2007-05-16 Thien-Thi Nguyen <ttn@gnuvola.org> (tiny change)
Bruno Haible <bruno@clisp.org>
parents:
8597
diff
changeset
|
353 @code{make clean}), using information determined by @command{configure} |
|
8225
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
354 They should not be checked into CVS, but instead added to |
|
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
355 @file{.cvsignore}. When you have a Gnulib source file of the form |
|
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
356 @file{lib/foo_.h}, the corresponding @file{lib/foo.h} is such a file. |
|
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
357 |
|
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
358 @item |
| 6255 | 359 In projects which customarily omit from the CVS all files that generated |
| 360 from other source files, all these files and directories would not be | |
| 361 added into CVS. The only file that must be added to CVS is | |
| 362 @file{gnulib-cache.m4} in the M4 macros directory. Also, the script for | |
| 363 restoring files not in CVS, customarily called @file{autogen.sh} or | |
| 364 @file{bootstrap.sh}, will typically contain the statement for restoring | |
| 365 the omitted files: | |
| 366 | |
| 367 @smallexample | |
| 368 $ gnulib-tool --update | |
| 369 @end smallexample | |
| 370 | |
| 371 The @samp{--update} option operates much like the @samp{--import} option, | |
| 372 but it does not offer the possibility to change the way Gnulib is used. | |
| 373 Also it does not report in the ChangeLogs the files that it had to add | |
| 374 because they were missing. | |
|
8225
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
375 |
|
a9c102ecab15
if have foo_.h, cvs-ignore foo.h
Karl Berry <karl@freefriends.org>
parents:
8146
diff
changeset
|
376 @end itemize |
|
8597
c1709670004e
Talk primarily about git, not CVS.
Bruno Haible <bruno@clisp.org>
parents:
8283
diff
changeset
|
377 |
|
c1709670004e
Talk primarily about git, not CVS.
Bruno Haible <bruno@clisp.org>
parents:
8283
diff
changeset
|
378 The same holds for other version control systems than CVS, such as @samp{git} |
|
c1709670004e
Talk primarily about git, not CVS.
Bruno Haible <bruno@clisp.org>
parents:
8283
diff
changeset
|
379 or @samp{svn}. |