1 @node Invoking gnulib-tool
2 @chapter Invoking gnulib-tool
4 @c Copyright (C) 2005, 2006, 2007 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 * Source changes:: Impact of Gnulib on your source files.
35 * VCS Issues:: Integration with Version Control Systems.
40 @section Initial import
41 @cindex initial import
43 Gnulib assumes your project uses Autoconf and Automake. Invoking
44 @samp{gnulib-tool --import} will copy source files, create a
45 @file{Makefile.am} to build them, generate a file @file{gnulib-comp.m4} with
46 Autoconf M4 macro declarations used by @file{configure.ac}, and generate
47 a file @file{gnulib-cache.m4} containing the cached specification of how
50 Our example will be a library that uses Autoconf, Automake and
51 Libtool. It calls @code{strdup}, and you wish to use gnulib to make
52 the package portable to C89 and C99 (which don't have @code{strdup}).
55 ~/src/libfoo$ gnulib-tool --import strdup
56 Module list with included dependencies:
70 Creating directory ./lib
71 Creating directory ./m4
72 Copying file lib/dummy.c
73 Copying file lib/strdup.c
74 Copying file lib/string.in.h
75 Copying file m4/absolute-header.m4
76 Copying file m4/extensions.m4
77 Copying file m4/gnulib-common.m4
78 Copying file m4/gnulib-tool.m4
79 Copying file m4/strdup.m4
80 Copying file m4/string_h.m4
81 Creating lib/Makefile.am
82 Creating m4/gnulib-cache.m4
83 Creating m4/gnulib-comp.m4
86 You may need to add #include directives for the following .h files.
90 - add "lib/Makefile" to AC_CONFIG_FILES in ./configure.ac,
91 - mention "lib" in SUBDIRS in Makefile.am,
92 - mention "-I m4" in ACLOCAL_AMFLAGS in Makefile.am,
93 - invoke gl_EARLY in ./configure.ac, right after AC_PROG_CC,
94 - invoke gl_INIT in ./configure.ac.
98 By default, the source code is copied into @file{lib/} and the M4
99 macros in @file{m4/}. You can override these paths by using
100 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}. Some
101 modules also provide other files necessary for building. These files
102 are copied into the directory specified by @samp{AC_CONFIG_AUX_DIR} in
103 @file{configure.ac} or by the @code{--aux-dir=DIRECTORY} option. If
104 neither is specified, the current directory is assumed.
106 @code{gnulib-tool} can make symbolic links instead of copying the
107 source files. The option to specify for this is @samp{--symlink}, or
108 @samp{-s} for short. This can be useful to save a few kilobytes of disk
109 space. But it is likely to introduce bugs when @code{gnulib} is updated;
110 it is more reliable to use @samp{gnulib-tool --update} (see below)
111 to update to newer versions of @code{gnulib}. Furthermore it requires
112 extra effort to create self-contained tarballs, and it may disturb some
113 mechanism the maintainer applies to the sources. For these reasons,
114 this option is generally discouraged.
116 @code{gnulib-tool} will overwrite any pre-existing files, in
117 particular @file{Makefile.am}. Unfortunately, separating the
118 generated @file{Makefile.am} content (for building the gnulib library)
119 into a separate file, say @file{gnulib.mk}, that could be included
120 by your handwritten @file{Makefile.am} is not possible, due to how
121 variable assignments are handled by Automake.
123 Consequently, it is a good idea to choose directories that are not
124 already used by your projects, to separate gnulib imported files from
125 your own files. This approach is also useful if you want to avoid
126 conflicts between other tools (e.g., @code{gettextize} that also copy
127 M4 files into your package. Simon Josefsson successfully uses a source
128 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
131 After the @samp{--import} option on the command line comes the list of
132 Gnulib modules that you want to incorporate in your package. The names
133 of the modules coincide with the filenames in Gnulib's @file{modules/}
136 Some Gnulib modules depend on other Gnulib modules. @code{gnulib-tool}
137 will automatically add the needed modules as well; you need not list
138 them explicitly. @code{gnulib-tool} will also memorize which dependent
139 modules it has added, so that when someday a dependency is dropped, the
140 implicitly added module is dropped as well (unless you have explicitly
141 requested that module).
143 If you want to cut a dependency, i.e., not add a module although one of
144 your requested modules depends on it, you may use the option
145 @samp{--avoid=@var{module}} to do so. Multiple uses of this option are
146 possible. Of course, you will then need to implement the same interface
147 as the removed module.
149 A few manual steps are required to finish the initial import.
150 @code{gnulib-tool} printed a summary of these steps.
152 First, you must ensure Autoconf can find the macro definitions in
153 @file{gnulib-comp.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in
154 your top-level @file{Makefile.am} file, as in:
157 ACLOCAL_AMFLAGS = -I m4
160 You are now ready to call the M4 macros in @code{gnulib-comp.m4} from
161 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon
162 as possible after verifying that the C compiler is working.
163 Typically, this is immediately after @code{AC_PROG_CC}, as in:
172 The core part of the gnulib checks are done by the macro
173 @code{gl_INIT}. Place it further down in the file, typically where
174 you normally check for header files or functions. It must come after
175 other checks which may affect the compiler invocation, such as
176 @code{AC_MINIX}. For example:
185 @code{gl_INIT} will in turn call the macros related with the
186 gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA}
187 or autoconf or automake macros like @code{AC_FUNC_ALLOCA} or
188 @code{AM_FUNC_GETLINE}. So there is no need to call those macros yourself
189 when you use the corresponding gnulib modules.
191 You must also make sure that the gnulib library is built. Add the
192 @code{Makefile} in the gnulib source base directory to
193 @code{AC_CONFIG_FILES}, as in:
196 AC_CONFIG_FILES(... lib/Makefile ...)
199 You must also make sure that @code{make} will recurse into the gnulib
200 directory. To achieve this, add the gnulib source base directory to a
201 @code{SUBDIRS} Makefile.am statement, as in:
207 or if you, more likely, already have a few entries in @code{SUBDIRS},
208 you can add something like:
214 Finally, you have to add compiler and linker flags in the appropriate
215 source directories, so that you can make use of the gnulib library.
216 Since some modules (@samp{getopt}, for example) may copy files into
217 the build directory, @file{top_builddir/lib} is needed as well
218 as @file{top_srcdir/lib}. For example:
222 AM_CPPFLAGS = -I$(top_builddir)/lib -I$(top_srcdir)/lib
228 Don't forget to @code{#include} the various header files. In this
229 example, you would need to make sure that @samp{#include <string.h>}
230 is evaluated when compiling all source code files, that want to make
231 use of @code{strdup}.
233 In the usual case where Autoconf is creating a @file{config.h} file,
234 you should include @file{config.h} first, before any other include
235 file. That way, for example, if @file{config.h} defines
236 @samp{restrict} to be the empty string on a pre-C99 host, or a macro
237 like @samp{_FILE_OFFSET_BITS} that affects the layout of data
238 structures, the definition is consistent for all include files.
239 Also, on some platforms macros like @samp{_FILE_OFFSET_BITS} and
240 @samp{_GNU_SOURCE} may be ineffective, or may have only a limited
241 effect, if defined after the first system header file is included.
243 Finally, note that you can not use @code{AC_LIBOBJ} or
244 @code{AC_REPLACE_FUNCS} in your @file{configure.ac} and expect the
245 resulting object files to be automatically added to @file{lib/libgnu.a}.
246 This is because your @code{AC_LIBOBJ} and @code{AC_REPLACE_FUNCS} invocations
247 from @file{configure.ac} augment a variable @code{@@LIBOBJS@@} (and/or
248 @code{@@LTLIBOBJS@@} if using Libtool), whereas @file{lib/libgnu.a}
249 is built from the contents of a different variable, usually
250 @code{@@gl_LIBOBJS@@} (or @code{@@gl_LTLIBOBJS@@} if using Libtool).
253 @node Modified imports
254 @section Modified imports
256 You can at any moment decide to use Gnulib differently than the last time.
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
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.
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}.
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.
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.
283 In the @file{gnulib-cache.m4}, the macros have the following meaning:
286 The argument is a space separated list of the requested modules, not including
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.
295 The argument is the relative file name of the directory containing the gnulib
296 source files (mostly *.c and *.h files). Corresponds to the
297 @samp{--source-base} command line argument.
300 The argument is the relative file name of the directory containing the gnulib
301 M4 macros (*.m4 files). Corresponds to the @samp{--m4-base} command line
305 The argument is the relative file name of the directory containing the gnulib
306 unit test files. Corresponds to the @samp{--tests-base} command line argument.
309 The argument is the name of the library to be created. Corresponds to the
310 @samp{--lib} command line argument.
313 The presence of this macro without arguments corresponds to the @samp{--lgpl}
314 command line argument. The presence of this macro with an argument (whose
315 value must be 2 or 3) corresponds to the @samp{--lgpl=@var{arg}} command line
319 The presence of this macro corresponds to the @samp{--libtool} command line
320 argument and to the absence of the @samp{--no-libtool} command line argument.
321 It takes no arguments.
323 @item gl_MACRO_PREFIX
324 The argument is the prefix to use for macros in the @file{gnulib-comp.m4}
325 file. Corresponds to the @samp{--macro-prefix} command line argument.
330 @section Simple update
332 When you want to update to a more recent version of Gnulib, without
333 changing the list of modules or other parameters, a simple call
337 $ gnulib-tool --import
341 This will create, update or remove files, as needed.
343 Note: From time to time, changes are made in Gnulib that are not backward
344 compatible. When updating to a more recent Gnulib, you should consult
345 Gnulib's @file{NEWS} file to check whether the incompatible changes affect
350 @section Changing your sources for use with Gnulib
352 Gnulib contains some header file overrides. This means that when building
353 on systems with deficient header files in @file{/usr/include/}, it may create
354 files named @file{string.h}, @file{stdlib.h}, @file{stdint.h} or similar in
355 the build directory. In the other source directories of your package you
356 will usually pass @samp{-I} options to the compiler, so that these Gnulib
357 substitutes are visible and take precedence over the files in
358 @file{/usr/include/}.
360 These Gnulib substitute header files rely on @file{<config.h>} being
361 already included. Furthermore @file{<config.h>} must be the first include
362 in every compilation unit. This means that to @emph{all your source files}
363 and likely also to @emph{all your tests source files} you need to add an
364 @samp{#include <config.h>} at the top. Which source files are affected?
365 Exactly those whose compilation includes a @samp{-I} option that refers to
366 the Gnulib library directory.
368 This is annoying, but inevitable: On many systems, @file{<config.h>} is
369 used to set system dependent flags (such as @code{_GNU_SOURCE} on GNU systems),
370 and these flags have no effect after any system header file has been included.
374 @section Issues with Version Control Systems
376 If a project stores its source files in a version control system (VCS),
377 such as CVS, SVN, or Git, one needs to decide which files to commit.
379 All files created by @code{gnulib-tool}, except @file{gnulib-cache.m4},
380 should be treated like generated source files, like for example a
381 @file{parser.c} file is generated from @file{parser.y}.
386 In projects which commit all source files, whether generated or not, into
387 their VCS, the @code{gnulib-tool} generated files should all be committed.
389 Gnulib also contains files generated by @command{make} (and removed by
390 @code{make clean}), using information determined by @command{configure}
391 They should not be checked into the VCS, but instead added to
392 @file{.cvsignore}. When you have a Gnulib source file of the form
393 @file{lib/foo_.h}, the corresponding @file{lib/foo.h} is such a file.
396 In projects which customarily omit from their VCS all files that are generated
397 from other source files, all these files and directories would not be
398 added into the VCS. The only file that must be added to the VCS is
399 @file{gnulib-cache.m4} in the M4 macros directory. Also, the script for
400 restoring files not in the VCS, customarily called @file{autogen.sh} or
401 @file{bootstrap.sh}, will typically contain the statement for restoring
405 $ gnulib-tool --update
408 The @samp{--update} option operates much like the @samp{--import} option,
409 but it does not offer the possibility to change the way Gnulib is used.
410 Also it does not report in the ChangeLogs the files that it had to add
411 because they were missing.