1 @node Invoking gnulib-tool
2 @chapter Invoking gnulib-tool
5 @cindex invoking @command{gnulib-tool}
7 @command{gnulib-tool} is the way to import Gnulib modules. It is also
8 possible to borrow Gnulib modules in a package without using
9 @command{gnulib-tool}, relying only on the metainformation stored in
10 the @file{modules/*} files, but with a growing number of modules this
11 becomes tedious. @command{gnulib-tool} simplifies the management of
12 source files, @file{Makefile.am}s and @file{configure.ac} in packages
13 incorporating Gnulib modules.
15 Run @samp{gnulib-tool --help}. To get familiar with @command{gnulib-tool},
16 you can also try some commands with the option @samp{--dry-run}; then
17 @code{gnulib-tool} will only report which actions it would perform in a
21 * Initial import:: First import of Gnulib modules.
22 * Modified imports:: Changing the import specification.
23 * Simple update:: Tracking Gnulib development.
24 * CVS Issues:: Integration with CVS.
29 @section Initial import
30 @cindex initial import
32 Gnulib assumes your project uses Autoconf and Automake. Invoking
33 @samp{gnulib-tool --import} will copy source files, create a
34 @file{Makefile.am} to build them, generate a file @file{gnulib-comp.m4} with
35 Autoconf M4 macro declarations used by @file{configure.ac}, and generate
36 a file @file{gnulib-cache.m4} containing the cached specification of how
39 Our example will be a library that uses Autoconf, Automake and
40 Libtool. It calls @code{strdup}, and you wish to use gnulib to make
41 the package portable to C89 (which doesn't have @code{strdup}).
44 ~/src/libfoo$ gnulib-tool --import strdup
45 Module list with included dependencies:
52 Copying file m4/gnulib-tool.m4
53 Copying file m4/onceonly_2_57.m4
54 Copying file lib/strdup.c
55 Copying file lib/strdup.h
56 Copying file m4/strdup.m4
57 Creating lib/Makefile.am
58 Creating m4/gnulib-cache.m4
59 Creating m4/gnulib-comp.m4
62 You may need to add #include directives for the following .h files.
66 - add "lib/Makefile" to AC_CONFIG_FILES in ./configure.ac,
67 - mention "lib" in SUBDIRS in Makefile.am,
68 - mention "-I m4" in ACLOCAL_AMFLAGS in Makefile.am,
69 - invoke gl_EARLY in ./configure.ac, right after AC_PROG_CC,
70 - invoke gl_INIT in ./configure.ac.
74 By default, the source code is copied into @file{lib/} and the M4
75 macros in @file{m4/}. You can override these paths by using
76 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}. Some
77 modules also provide other files necessary for building. These files
78 are copied into the directory specified by @samp{AC_CONFIG_AUX_DIR} in
79 @file{configure.ac} or by the @code{--aux-dir=DIRECTORY} option. If
80 neither is specified, the current directory is assumed.
82 @code{gnulib-tool} can make symbolic links instead of copying the
83 source files. Use the @samp{--symbolic} (or @samp{-s} for short) option
86 @code{gnulib-tool} will overwrite any pre-existing files, in
87 particular @file{Makefile.am}. Unfortunately, separating the
88 generated @file{Makefile.am} content (for building the gnulib library)
89 into a separate file, say @file{gnulib.mk}, that could be included
90 by your handwritten @file{Makefile.am} is not possible, due to how
91 variable assignments are handled by Automake.
93 Consequently, it is a good idea to choose directories that are not
94 already used by your projects, to separate gnulib imported files from
95 your own files. This approach is also useful if you want to avoid
96 conflicts between other tools (e.g., @code{gettextize} that also copy
97 M4 files into your package. Simon Josefsson successfully uses a source
98 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
101 After the @samp{--import} option on the command line comes the list of
102 Gnulib modules that you want to incorporate in your package. The names
103 of the modules coincide with the filenames in Gnulib's @file{modules/}
106 Some Gnulib modules depend on other Gnulib modules. @code{gnulib-tool}
107 will automatically add the needed modules as well; you need not list
108 them explicitly. @code{gnulib-tool} will also memoize which dependent
109 modules it has added, so that when someday a dependency is dropped, the
110 implicitly added module is dropped as well (unless you have explicitly
111 requested that module).
113 If you want to cut a dependency, i.e. not add a module although one of
114 your requested modules depends on it, you may use the option
115 @samp{--avoid=@var{module}} to do so. Multiple uses of this option are
116 possible. Of course, you will then need to implement the same interface
117 as the removed module.
119 A few manual steps are required to finish the initial import.
120 @code{gnulib-tool} printed a summary of these steps.
122 First, you need to make sure Autoconf can find the macro definitions
123 in @file{gnulib-comp.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in your
124 top-level @file{Makefile.am} file, as in:
127 ACLOCAL_AMFLAGS = -I m4
130 You are now ready to call the M4 macros in @code{gnulib-comp.m4} from
131 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon
132 as possible after verifying that the C compiler is working.
133 Typically, this is immediately after @code{AC_PROG_CC}, as in:
142 The core part of the gnulib checks are done by the macro
143 @code{gl_INIT}. Place it further down in the file, typically where
144 you normally check for header files or functions. For example:
153 @code{gl_INIT} will in turn call the macros related with the
154 gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA}
155 or autoconf or automake macros like @code{AC_FUNC_ALLOCA} or
156 @code{AM_FUNC_GETLINE}. So there is no need to call those macros yourself
157 when you use the corresponding gnulib modules.
159 You must also make sure that the gnulib library is built. Add the
160 @code{Makefile} in the gnulib source base directory to
161 @code{AC_CONFIG_FILES}, as in:
164 AC_CONFIG_FILES(... lib/Makefile ...)
167 You must also make sure that @code{make} will recurse into the gnulib
168 directory. To achieve this, add the gnulib source base directory to a
169 @code{SUBDIRS} Makefile.am statement, as in:
175 or if you, more likely, already have a few entries in @code{SUBDIRS},
176 you can add something like:
182 Finally, you have to add compiler and linker flags in the appropriate
183 source directories, so that you can make use of the gnulib library.
184 Since some modules (@samp{getopt}, for example) may copy files into
185 the build directory, @file{top_builddir/lib} is needed as well
186 as @file{top_srcdir/lib}. For example:
190 AM_CPPFLAGS = -I$(top_srcdir)/lib -I$(top_builddir)/lib
192 LIBADD = lib/libgnu.a
196 Don't forget to @code{#include} the various header files. In this
197 example, you would need to make sure that @samp{#include "strdup.h"}
198 is evaluated when compiling all source code files, that want to make
199 use of @code{strdup}.
201 When an include file is provided by Gnulib
202 you shouldn't try to include the corresponding system header files
203 yourself, but let the gnulib header file do it. The ordering
204 of the definition for some symbols may be significant; the Gnulib
205 header files take care of that.
207 For example, to use the @code{time_r} gnulib module you should
208 use include header file provided by the gnulib, and so
209 @samp{#include "time_r.h"}, but you shouldn't explicitly
210 @samp{#include <time.h>} as it is already done in @file{time_r.h}
211 before the redefinition of some symbols.
213 @node Modified imports
214 @section Modified imports
216 You can at any moment decide to use Gnulib differently than the last time.
218 If you only want to use more Gnulib modules, simply invoke
219 @command{gnulib-tool --import @var{new-modules}}. @code{gnulib-tool}
220 remembers which modules were used last time. The list of modules that
221 you pass after @samp{--import} is @emph{added} to the previous list of
224 For most changes, such as added or removed modules, or even different
225 choices of @samp{--lib}, @samp{--source-base} or @samp{--aux-dir}, there
226 are two ways to perform the change.
228 The standard way is to modify manually the file @file{gnulib-cache.m4}
229 in the M4 macros directory, then launch @samp{gnulib-tool --import}.
231 The other way is to call @command{gnulib-tool} again, with the changed
232 command-line options. Note that this doesn't let you remove modules,
233 because as you just learned, the list of modules is always cumulated.
234 Also this way is often impractical, because you don't remember the way
235 you invoked @code{gnulib-tool} last time.
237 The only change for which this doesn't work is a change of the
238 @samp{--m4-base} directory. Because, when you pass a different value of
239 @samp{--m4-base}, @code{gnulib-tool} will not find the previous
240 @file{gnulib-cache.m4} file any more... A possible solution is to manually
241 copy the @file{gnulib-cache.m4} into the new M4 macro directory.
243 In the @file{gnulib-cache.m4}, the macros have the following meaning:
246 The argument is a space separated list of the requested modules, not including
250 The argument is a space separated list of modules that should not be used,
251 even if they occur as dependencies. Corresponds to the @samp{--avoid}
252 command line argument.
255 The argument is the relative pathname of the directory containing the gnulib
256 source files (mostly *.c and *.h files). Corresponds to the
257 @samp{--source-base} command line argument.
260 The argument is the relative pathname of the directory containing the gnulib
261 M4 macros (*.m4 files). Corresponds to the @samp{--m4-base} command line
265 The argument is the relative pathname of the directory containing the gnulib
266 unit test files. Corresponds to the @samp{--tests-base} command line argument.
269 The argument is the name of the library to be created. Corresponds to the
270 @samp{--lib} command line argument.
273 The presence of this macro corresponds to the @samp{--lgpl} command line
274 argument. It takes no arguments.
277 The presence of this macro corresponds to the @samp{--libtool} command line
278 argument. It takes no arguments.
280 @item gl_MACRO_PREFIX
281 The argument is the prefix to use for macros in the @file{gnulib-comp.m4}
282 file. Corresponds to the @samp{--macro-prefix} command line argument.
286 @section Simple update
288 When you want to update to a more recent version of Gnulib, without
289 changing the list of modules or other parameters, a simple call
293 $ gnulib-tool --import
296 This will create, update or remove files, as needed.
301 All files created by @code{gnulib-tool}, except @file{gnulib-cache.m4},
302 should be treated like generated source files, like for example a
303 @file{parser.c} file is generated from @file{parser.y}.
305 In projects which commit all source files, whether generated or not, into
306 CVS, the @code{gnulib-tool} generated files should all be committed.
308 In projects which customarily omit from the CVS all files that generated
309 from other source files, all these files and directories would not be
310 added into CVS. The only file that must be added to CVS is
311 @file{gnulib-cache.m4} in the M4 macros directory. Also, the script for
312 restoring files not in CVS, customarily called @file{autogen.sh} or
313 @file{bootstrap.sh}, will typically contain the statement for restoring
317 $ gnulib-tool --update
320 The @samp{--update} option operates much like the @samp{--import} option,
321 but it does not offer the possibility to change the way Gnulib is used.
322 Also it does not report in the ChangeLogs the files that it had to add
323 because they were missing.