1 @node Invoking gnulib-tool
2 @chapter Invoking gnulib-tool
4 @c Copyright (C) 2005, 2006 Free Software Foundation, Inc.
6 @c Permission is granted to copy, distribute and/or modify this document
7 @c under the terms of the GNU Free Documentation License, Version 1.2 or
8 @c any later version published by the Free Software Foundation; with no
9 @c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
10 @c Texts. A copy of the license is included in the ``GNU Free
11 @c Documentation License'' file as part of this distribution.
14 @cindex invoking @command{gnulib-tool}
16 The @command{gnulib-tool} command is the recommended way to import
17 Gnulib modules. It is possible to borrow Gnulib modules in a package
18 without using @command{gnulib-tool}, relying only on the
19 meta-information stored in the @file{modules/*} files, but with a
20 growing number of modules this becomes tedious. @command{gnulib-tool}
21 simplifies the management of source files, @file{Makefile.am}s and
22 @file{configure.ac} in packages incorporating Gnulib modules.
24 Run @samp{gnulib-tool --help} for information. To get familiar with
25 @command{gnulib-tool} without affecting your sources, you can also try
26 some commands with the option @samp{--dry-run}; then
27 @code{gnulib-tool} will only report which actions it would perform in
28 a real run without changing anything.
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.
39 @section Initial import
40 @cindex initial import
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
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
51 the package portable to C89 (which doesn't have @code{strdup}).
54 ~/src/libfoo$ gnulib-tool --import strdup
55 Module list with included dependencies:
62 Copying file m4/gnulib-tool.m4
63 Copying file m4/onceonly_2_57.m4
64 Copying file lib/strdup.c
65 Copying file lib/strdup.h
66 Copying file m4/strdup.m4
67 Creating lib/Makefile.am
68 Creating m4/gnulib-cache.m4
69 Creating m4/gnulib-comp.m4
72 You may need to add #include directives for the following .h files.
76 - add "lib/Makefile" to AC_CONFIG_FILES in ./configure.ac,
77 - mention "lib" in SUBDIRS in Makefile.am,
78 - mention "-I m4" in ACLOCAL_AMFLAGS in Makefile.am,
79 - invoke gl_EARLY in ./configure.ac, right after AC_PROG_CC,
80 - invoke gl_INIT in ./configure.ac.
84 By default, the source code is copied into @file{lib/} and the M4
85 macros in @file{m4/}. You can override these paths by using
86 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}. Some
87 modules also provide other files necessary for building. These files
88 are copied into the directory specified by @samp{AC_CONFIG_AUX_DIR} in
89 @file{configure.ac} or by the @code{--aux-dir=DIRECTORY} option. If
90 neither is specified, the current directory is assumed.
92 @code{gnulib-tool} can make symbolic links instead of copying the
93 source files. Use the @samp{--symbolic} (or @samp{-s} for short) option
96 @code{gnulib-tool} will overwrite any pre-existing files, in
97 particular @file{Makefile.am}. Unfortunately, separating the
98 generated @file{Makefile.am} content (for building the gnulib library)
99 into a separate file, say @file{gnulib.mk}, that could be included
100 by your handwritten @file{Makefile.am} is not possible, due to how
101 variable assignments are handled by Automake.
103 Consequently, it is a good idea to choose directories that are not
104 already used by your projects, to separate gnulib imported files from
105 your own files. This approach is also useful if you want to avoid
106 conflicts between other tools (e.g., @code{gettextize} that also copy
107 M4 files into your package. Simon Josefsson successfully uses a source
108 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
111 After the @samp{--import} option on the command line comes the list of
112 Gnulib modules that you want to incorporate in your package. The names
113 of the modules coincide with the filenames in Gnulib's @file{modules/}
116 Some Gnulib modules depend on other Gnulib modules. @code{gnulib-tool}
117 will automatically add the needed modules as well; you need not list
118 them explicitly. @code{gnulib-tool} will also memorize which dependent
119 modules it has added, so that when someday a dependency is dropped, the
120 implicitly added module is dropped as well (unless you have explicitly
121 requested that module).
123 If you want to cut a dependency, i.e., not add a module although one of
124 your requested modules depends on it, you may use the option
125 @samp{--avoid=@var{module}} to do so. Multiple uses of this option are
126 possible. Of course, you will then need to implement the same interface
127 as the removed module.
129 A few manual steps are required to finish the initial import.
130 @code{gnulib-tool} printed a summary of these steps.
132 First, you must ensure Autoconf can find the macro definitions in
133 @file{gnulib-comp.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in
134 your top-level @file{Makefile.am} file, as in:
137 ACLOCAL_AMFLAGS = -I m4
140 You are now ready to call the M4 macros in @code{gnulib-comp.m4} from
141 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon
142 as possible after verifying that the C compiler is working.
143 Typically, this is immediately after @code{AC_PROG_CC}, as in:
152 The core part of the gnulib checks are done by the macro
153 @code{gl_INIT}. Place it further down in the file, typically where
154 you normally check for header files or functions. It must come after
155 other checks which may affect the compiler invocation, such as
156 @code{AC_MINIX}. For example:
165 @code{gl_INIT} will in turn call the macros related with the
166 gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA}
167 or autoconf or automake macros like @code{AC_FUNC_ALLOCA} or
168 @code{AM_FUNC_GETLINE}. So there is no need to call those macros yourself
169 when you use the corresponding gnulib modules.
171 You must also make sure that the gnulib library is built. Add the
172 @code{Makefile} in the gnulib source base directory to
173 @code{AC_CONFIG_FILES}, as in:
176 AC_CONFIG_FILES(... lib/Makefile ...)
179 You must also make sure that @code{make} will recurse into the gnulib
180 directory. To achieve this, add the gnulib source base directory to a
181 @code{SUBDIRS} Makefile.am statement, as in:
187 or if you, more likely, already have a few entries in @code{SUBDIRS},
188 you can add something like:
194 Finally, you have to add compiler and linker flags in the appropriate
195 source directories, so that you can make use of the gnulib library.
196 Since some modules (@samp{getopt}, for example) may copy files into
197 the build directory, @file{top_builddir/lib} is needed as well
198 as @file{top_srcdir/lib}. For example:
202 AM_CPPFLAGS = -I$(top_srcdir)/lib -I$(top_builddir)/lib
208 Don't forget to @code{#include} the various header files. In this
209 example, you would need to make sure that @samp{#include "strdup.h"}
210 is evaluated when compiling all source code files, that want to make
211 use of @code{strdup}.
213 When an include file is provided by Gnulib
214 you shouldn't try to include the corresponding system header files
215 yourself, but let the gnulib header file do it. The ordering
216 of the definition for some symbols may be significant; the Gnulib
217 header files take care of that.
219 For example, to use the @code{time_r} gnulib module you should
220 use include header file provided by the gnulib, and so
221 @samp{#include "time_r.h"}, but you shouldn't explicitly
222 @samp{#include <time.h>} as it is already done in @file{time_r.h}
223 before the redefinition of some symbols.
225 A final word of warning: Gnulib currently assumes it will be
226 responsible for @emph{all} functions that end up in the Autoconf
227 @code{@@LIBOBJS@@} variables (and/or @code{@@LTLIBOBJS@@} if using
228 Libtool), e.g., those specified in @code{AC_REPLACE_FUNCS} in your
229 @file{configure.ac}. Therefore, if you have any functions which are
230 not covered by Gnulib which need that treatment, you have to
231 essentially reimplement AC_REPLACE_FUNCS using different names; for an
232 example, see the Findutils sources. Perhaps this will be improved in
236 @node Modified imports
237 @section Modified imports
239 You can at any moment decide to use Gnulib differently than the last time.
241 If you only want to use more Gnulib modules, simply invoke
242 @command{gnulib-tool --import @var{new-modules}}. @code{gnulib-tool}
243 remembers which modules were used last time. The list of modules that
244 you pass after @samp{--import} is @emph{added} to the previous list of
247 For most changes, such as added or removed modules, or even different
248 choices of @samp{--lib}, @samp{--source-base} or @samp{--aux-dir}, there
249 are two ways to perform the change.
251 The standard way is to modify manually the file @file{gnulib-cache.m4}
252 in the M4 macros directory, then launch @samp{gnulib-tool --import}.
254 The other way is to call @command{gnulib-tool} again, with the changed
255 command-line options. Note that this doesn't let you remove modules,
256 because as you just learned, the list of modules is always cumulated.
257 Also this way is often impractical, because you don't remember the way
258 you invoked @code{gnulib-tool} last time.
260 The only change for which this doesn't work is a change of the
261 @samp{--m4-base} directory. Because, when you pass a different value of
262 @samp{--m4-base}, @code{gnulib-tool} will not find the previous
263 @file{gnulib-cache.m4} file any more... A possible solution is to manually
264 copy the @file{gnulib-cache.m4} into the new M4 macro directory.
266 In the @file{gnulib-cache.m4}, the macros have the following meaning:
269 The argument is a space separated list of the requested modules, not including
273 The argument is a space separated list of modules that should not be used,
274 even if they occur as dependencies. Corresponds to the @samp{--avoid}
275 command line argument.
278 The argument is the relative file name of the directory containing the gnulib
279 source files (mostly *.c and *.h files). Corresponds to the
280 @samp{--source-base} command line argument.
283 The argument is the relative file name of the directory containing the gnulib
284 M4 macros (*.m4 files). Corresponds to the @samp{--m4-base} command line
288 The argument is the relative file name of the directory containing the gnulib
289 unit test files. Corresponds to the @samp{--tests-base} command line argument.
292 The argument is the name of the library to be created. Corresponds to the
293 @samp{--lib} command line argument.
296 The presence of this macro corresponds to the @samp{--lgpl} command line
297 argument. It takes no arguments.
300 The presence of this macro corresponds to the @samp{--libtool} command line
301 argument and to the absence of the @samp{--no-libtool} command line argument.
302 It takes no arguments.
304 @item gl_MACRO_PREFIX
305 The argument is the prefix to use for macros in the @file{gnulib-comp.m4}
306 file. Corresponds to the @samp{--macro-prefix} command line argument.
310 @section Simple update
312 When you want to update to a more recent version of Gnulib, without
313 changing the list of modules or other parameters, a simple call
317 $ gnulib-tool --import
320 This will create, update or remove files, as needed.
325 All files created by @code{gnulib-tool}, except @file{gnulib-cache.m4},
326 should be treated like generated source files, like for example a
327 @file{parser.c} file is generated from @file{parser.y}.
329 In projects which commit all source files, whether generated or not, into
330 CVS, the @code{gnulib-tool} generated files should all be committed.
332 In projects which customarily omit from the CVS all files that generated
333 from other source files, all these files and directories would not be
334 added into CVS. The only file that must be added to CVS is
335 @file{gnulib-cache.m4} in the M4 macros directory. Also, the script for
336 restoring files not in CVS, customarily called @file{autogen.sh} or
337 @file{bootstrap.sh}, will typically contain the statement for restoring
341 $ gnulib-tool --update
344 The @samp{--update} option operates much like the @samp{--import} option,
345 but it does not offer the possibility to change the way Gnulib is used.
346 Also it does not report in the ChangeLogs the files that it had to add
347 because they were missing.