@node Invoking gnulib-tool
@chapter Invoking gnulib-tool
+@c Copyright (C) 2005, 2006, 2007 Free Software Foundation, Inc.
+
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.2 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+@c Texts. A copy of the license is included in the ``GNU Free
+@c Documentation License'' file as part of this distribution.
+
@pindex gnulib-tool
@cindex invoking @command{gnulib-tool}
-@command{gnulib-tool} is the way to import Gnulib modules. It is also
-possible to borrow Gnulib modules in a package without using
-@command{gnulib-tool}, relying only on the metainformation stored in
-the @file{modules/*} files, but with a growing number of modules this
-becomes tedious. @command{gnulib-tool} simplifies the management of
-source files, @file{Makefile.am}s and @file{configure.ac} in packages
-incorporating Gnulib modules.
+The @command{gnulib-tool} command is the recommended way to import
+Gnulib modules. It is possible to borrow Gnulib modules in a package
+without using @command{gnulib-tool}, relying only on the
+meta-information stored in the @file{modules/*} files, but with a
+growing number of modules this becomes tedious. @command{gnulib-tool}
+simplifies the management of source files, @file{Makefile.am}s and
+@file{configure.ac} in packages incorporating Gnulib modules.
-Run @samp{gnulib-tool --help}. To get familiar with @command{gnulib-tool},
-you can also try some commands with the option @samp{--dry-run}; then
-@code{gnulib-tool} will only report which actions it would perform in a
-real run.
+Run @samp{gnulib-tool --help} for information. To get familiar with
+@command{gnulib-tool} without affecting your sources, you can also try
+some commands with the option @samp{--dry-run}; then
+@code{gnulib-tool} will only report which actions it would perform in
+a real run without changing anything.
@menu
* Initial import:: First import of Gnulib modules.
Our example will be a library that uses Autoconf, Automake and
Libtool. It calls @code{strdup}, and you wish to use gnulib to make
-the package portable to C89 (which doesn't have @code{strdup}).
+the package portable to C89 and C99 (which don't have @code{strdup}).
@example
~/src/libfoo$ gnulib-tool --import strdup
Module list with included dependencies:
+ absolute-header
+ extensions
strdup
+ string
File list:
+ lib/dummy.c
lib/strdup.c
- lib/strdup.h
- m4/onceonly_2_57.m4
+ lib/string_.h
+ m4/absolute-header.m4
+ m4/extensions.m4
+ m4/gnulib-common.m4
m4/strdup.m4
-Copying file m4/gnulib-tool.m4
-Copying file m4/onceonly_2_57.m4
+ m4/string_h.m4
+Creating directory ./lib
+Creating directory ./m4
+Copying file lib/dummy.c
Copying file lib/strdup.c
-Copying file lib/strdup.h
+Copying file lib/string_.h
+Copying file m4/absolute-header.m4
+Copying file m4/extensions.m4
+Copying file m4/gnulib-common.m4
+Copying file m4/gnulib-tool.m4
Copying file m4/strdup.m4
+Copying file m4/string_h.m4
Creating lib/Makefile.am
Creating m4/gnulib-cache.m4
Creating m4/gnulib-comp.m4
Finished.
You may need to add #include directives for the following .h files.
- #include "strdup.h"
+ #include <string.h>
Don't forget to
- add "lib/Makefile" to AC_CONFIG_FILES in ./configure.ac,
neither is specified, the current directory is assumed.
@code{gnulib-tool} can make symbolic links instead of copying the
-source files. Use the @samp{--symbolic} (or @samp{-s} for short) option
-to do this.
+source files. The option to specify for this is @samp{--symlink}, or
+@samp{-s} for short. This can be useful to save a few kilobytes of disk
+space. But it is likely to introduce bugs when @code{gnulib} is updated;
+it is more reliable to use @samp{gnulib-tool --update} (see below)
+to update to newer versions of @code{gnulib}. Furthermore it requires
+extra effort to create self-contained tarballs, and it may disturb some
+mechanism the maintainer applies to the sources. For these reasons,
+this option is generally discouraged.
@code{gnulib-tool} will overwrite any pre-existing files, in
particular @file{Makefile.am}. Unfortunately, separating the
Some Gnulib modules depend on other Gnulib modules. @code{gnulib-tool}
will automatically add the needed modules as well; you need not list
-them explicitly. @code{gnulib-tool} will also memoize which dependent
+them explicitly. @code{gnulib-tool} will also memorize which dependent
modules it has added, so that when someday a dependency is dropped, the
implicitly added module is dropped as well (unless you have explicitly
requested that module).
-If you want to cut a dependency, i.e. not add a module although one of
+If you want to cut a dependency, i.e., not add a module although one of
your requested modules depends on it, you may use the option
@samp{--avoid=@var{module}} to do so. Multiple uses of this option are
possible. Of course, you will then need to implement the same interface
A few manual steps are required to finish the initial import.
@code{gnulib-tool} printed a summary of these steps.
-First, you need to make sure Autoconf can find the macro definitions
-in @file{gnulib-comp.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in your
-top-level @file{Makefile.am} file, as in:
+First, you must ensure Autoconf can find the macro definitions in
+@file{gnulib-comp.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in
+your top-level @file{Makefile.am} file, as in:
@example
ACLOCAL_AMFLAGS = -I m4
The core part of the gnulib checks are done by the macro
@code{gl_INIT}. Place it further down in the file, typically where
-you normally check for header files or functions. For example:
+you normally check for header files or functions. It must come after
+other checks which may affect the compiler invocation, such as
+@code{AC_MINIX}. For example:
@example
...
...
AM_CPPFLAGS = -I$(top_srcdir)/lib -I$(top_builddir)/lib
...
-LIBADD = lib/libgnu.a
+LDADD = lib/libgnu.a
...
@end example
Don't forget to @code{#include} the various header files. In this
-example, you would need to make sure that @samp{#include "strdup.h"}
+example, you would need to make sure that @samp{#include <string.h>}
is evaluated when compiling all source code files, that want to make
use of @code{strdup}.
-When an include file is provided by Gnulib
-you shouldn't try to include the corresponding system header files
-yourself, but let the gnulib header file do it. The ordering
-of the definition for some symbols may be significant; the Gnulib
-header files take care of that.
+In the usual case where Autoconf is creating a @file{config.h} file,
+you should include @file{config.h} first, before any other include
+file. That way, for example, if @file{config.h} defines
+@samp{restrict} to be the empty string on a pre-C99 host, the
+definition is consistent for all include files.
+
+You should include Gnulib-provided headers before system headers,
+so that Gnulib-provided headers can adjust how a system header
+behaves.
+
+A final word of warning: Gnulib currently assumes it will be
+responsible for @emph{all} functions that end up in the Autoconf
+@code{@@LIBOBJS@@} variables (and/or @code{@@LTLIBOBJS@@} if using
+Libtool), e.g., those specified in @code{AC_REPLACE_FUNCS} in your
+@file{configure.ac}. Therefore, if you have any functions which are
+not covered by Gnulib which need that treatment, you have to
+essentially reimplement AC_REPLACE_FUNCS using different names; for an
+example, see the Findutils sources. Perhaps this will be improved in
+the future.
-For example, to use the @code{time_r} gnulib module you should
-use include header file provided by the gnulib, and so
-@samp{#include "time_r.h"}, but you shouldn't explicitly
-@samp{#include <time.h>} as it is already done in @file{time_r.h}
-before the redefinition of some symbols.
@node Modified imports
@section Modified imports
@item gl_LIBTOOL
The presence of this macro corresponds to the @samp{--libtool} command line
-argument. It takes no arguments.
+argument and to the absence of the @samp{--no-libtool} command line argument.
+It takes no arguments.
@item gl_MACRO_PREFIX
The argument is the prefix to use for macros in the @file{gnulib-comp.m4}
projects / gnulib.git / blobdiff