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 * 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 and C99 (which don't have @code{strdup}).
54 ~/src/libfoo$ gnulib-tool --import strdup
55 Module list with included dependencies:
69 Creating directory ./lib
70 Creating directory ./m4
71 Copying file lib/dummy.c
72 Copying file lib/strdup.c
73 Copying file lib/string_.h
74 Copying file m4/absolute-header.m4
75 Copying file m4/extensions.m4
76 Copying file m4/gnulib-common.m4
77 Copying file m4/gnulib-tool.m4
78 Copying file m4/strdup.m4
79 Copying file m4/string_h.m4
80 Creating lib/Makefile.am
81 Creating m4/gnulib-cache.m4
82 Creating m4/gnulib-comp.m4
85 You may need to add #include directives for the following .h files.
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.
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.
105 @code{gnulib-tool} can make symbolic links instead of copying the
106 source files. The option to specify for this is @samp{--symlink}, or
107 @samp{-s} for short. This can be useful to save a few kilobytes of disk
108 space. But it is likely to introduce bugs when @code{gnulib} is updated;
109 it is more reliable to use @samp{gnulib-tool --update} (see below)
110 to update to newer versions of @code{gnulib}. Furthermore it requires
111 extra effort to create self-contained tarballs, and it may disturb some
112 mechanism the maintainer applies to the sources. For these reasons,
113 this option is generally discouraged.
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.
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
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/}
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
137 them explicitly. @code{gnulib-tool} will also memorize which dependent
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).
142 If you want to cut a dependency, i.e., not add a module although one of
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.
148 A few manual steps are required to finish the initial import.
149 @code{gnulib-tool} printed a summary of these steps.
151 First, you must ensure Autoconf can find the macro definitions in
152 @file{gnulib-comp.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in
153 your top-level @file{Makefile.am} file, as in:
156 ACLOCAL_AMFLAGS = -I m4
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:
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
173 you normally check for header files or functions. It must come after
174 other checks which may affect the compiler invocation, such as
175 @code{AC_MINIX}. For example:
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.
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:
195 AC_CONFIG_FILES(... lib/Makefile ...)
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:
206 or if you, more likely, already have a few entries in @code{SUBDIRS},
207 you can add something like:
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:
221 AM_CPPFLAGS = -I$(top_srcdir)/lib -I$(top_builddir)/lib
227 Don't forget to @code{#include} the various header files. In this
228 example, you would need to make sure that @samp{#include <string.h>}
229 is evaluated when compiling all source code files, that want to make
230 use of @code{strdup}.
232 In the usual case where Autoconf is creating a @file{config.h} file,
233 you should include @file{config.h} first, before any other include
234 file. That way, for example, if @file{config.h} defines
235 @samp{restrict} to be the empty string on a pre-C99 host, or a macro
236 like @samp{_FILE_OFFSET_BITS} that affects the layout of data
237 structures, the definition is consistent for all include files.
239 You should include Gnulib-provided headers before system headers,
240 so that Gnulib-provided headers can adjust how a system header
243 A final word of warning: Gnulib currently assumes it will be
244 responsible for @emph{all} functions that end up in the Autoconf
245 @code{@@LIBOBJS@@} variables (and/or @code{@@LTLIBOBJS@@} if using
246 Libtool), e.g., those specified in @code{AC_REPLACE_FUNCS} in your
247 @file{configure.ac}. Therefore, if you have any functions which are
248 not covered by Gnulib which need that treatment, you have to
249 essentially reimplement AC_REPLACE_FUNCS using different names; for an
250 example, see the Findutils sources. Perhaps this will be improved in
254 @node Modified imports
255 @section Modified imports
257 You can at any moment decide to use Gnulib differently than the last time.
259 If you only want to use more Gnulib modules, simply invoke
260 @command{gnulib-tool --import @var{new-modules}}. @code{gnulib-tool}
261 remembers which modules were used last time. The list of modules that
262 you pass after @samp{--import} is @emph{added} to the previous list of
265 For most changes, such as added or removed modules, or even different
266 choices of @samp{--lib}, @samp{--source-base} or @samp{--aux-dir}, there
267 are two ways to perform the change.
269 The standard way is to modify manually the file @file{gnulib-cache.m4}
270 in the M4 macros directory, then launch @samp{gnulib-tool --import}.
272 The other way is to call @command{gnulib-tool} again, with the changed
273 command-line options. Note that this doesn't let you remove modules,
274 because as you just learned, the list of modules is always cumulated.
275 Also this way is often impractical, because you don't remember the way
276 you invoked @code{gnulib-tool} last time.
278 The only change for which this doesn't work is a change of the
279 @samp{--m4-base} directory. Because, when you pass a different value of
280 @samp{--m4-base}, @code{gnulib-tool} will not find the previous
281 @file{gnulib-cache.m4} file any more... A possible solution is to manually
282 copy the @file{gnulib-cache.m4} into the new M4 macro directory.
284 In the @file{gnulib-cache.m4}, the macros have the following meaning:
287 The argument is a space separated list of the requested modules, not including
291 The argument is a space separated list of modules that should not be used,
292 even if they occur as dependencies. Corresponds to the @samp{--avoid}
293 command line argument.
296 The argument is the relative file name of the directory containing the gnulib
297 source files (mostly *.c and *.h files). Corresponds to the
298 @samp{--source-base} command line argument.
301 The argument is the relative file name of the directory containing the gnulib
302 M4 macros (*.m4 files). Corresponds to the @samp{--m4-base} command line
306 The argument is the relative file name of the directory containing the gnulib
307 unit test files. Corresponds to the @samp{--tests-base} command line argument.
310 The argument is the name of the library to be created. Corresponds to the
311 @samp{--lib} command line argument.
314 The presence of this macro corresponds to the @samp{--lgpl} command line
315 argument. It takes no arguments.
318 The presence of this macro corresponds to the @samp{--libtool} command line
319 argument and to the absence of the @samp{--no-libtool} command line argument.
320 It takes no arguments.
322 @item gl_MACRO_PREFIX
323 The argument is the prefix to use for macros in the @file{gnulib-comp.m4}
324 file. Corresponds to the @samp{--macro-prefix} command line argument.
328 @section Simple update
330 When you want to update to a more recent version of Gnulib, without
331 changing the list of modules or other parameters, a simple call
335 $ gnulib-tool --import
338 This will create, update or remove files, as needed.
343 All files created by @code{gnulib-tool}, except @file{gnulib-cache.m4},
344 should be treated like generated source files, like for example a
345 @file{parser.c} file is generated from @file{parser.y}.
350 In projects which commit all source files, whether generated or not, into
351 CVS, the @code{gnulib-tool} generated files should all be committed.
353 Gnulib also contains files generated by @command{make} (and removed by
354 @code{make clean}, using information determined by @command{configure}
355 They should not be checked into CVS, but instead added to
356 @file{.cvsignore}. When you have a Gnulib source file of the form
357 @file{lib/foo_.h}, the corresponding @file{lib/foo.h} is such a file.
361 In projects which customarily omit from the CVS all files that generated
362 from other source files, all these files and directories would not be
363 added into CVS. The only file that must be added to CVS is
364 @file{gnulib-cache.m4} in the M4 macros directory. Also, the script for
365 restoring files not in CVS, customarily called @file{autogen.sh} or
366 @file{bootstrap.sh}, will typically contain the statement for restoring
370 $ gnulib-tool --update
373 The @samp{--update} option operates much like the @samp{--import} option,
374 but it does not offer the possibility to change the way Gnulib is used.
375 Also it does not report in the ChangeLogs the files that it had to add
376 because they were missing.