@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, or a macro
+like @samp{_FILE_OFFSET_BITS} that affects the layout of data
+structures, the definition is consistent for all include files.
+Also, on some platforms macros like @samp{_FILE_OFFSET_BITS} and
+@samp{_GNU_SOURCE} may be ineffective, or may have only a limited
+effect, if defined after the first system header file is included.
+
+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
command line argument.
@item gl_SOURCE_BASE
-The argument is the relative pathname of the directory containing the gnulib
+The argument is the relative file name of the directory containing the gnulib
source files (mostly *.c and *.h files). Corresponds to the
@samp{--source-base} command line argument.
@item gl_M4_BASE
-The argument is the relative pathname of the directory containing the gnulib
+The argument is the relative file name of the directory containing the gnulib
M4 macros (*.m4 files). Corresponds to the @samp{--m4-base} command line
argument.
@item gl_TESTS_BASE
-The argument is the relative pathname of the directory containing the gnulib
+The argument is the relative file name of the directory containing the gnulib
unit test files. Corresponds to the @samp{--tests-base} command line argument.
@item gl_LIB
@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}
should be treated like generated source files, like for example a
@file{parser.c} file is generated from @file{parser.y}.
+@itemize
+
+@item
In projects which commit all source files, whether generated or not, into
CVS, the @code{gnulib-tool} generated files should all be committed.
+Gnulib also contains files generated by @command{make} (and removed by
+@code{make clean}, using information determined by @command{configure}
+They should not be checked into CVS, but instead added to
+@file{.cvsignore}. When you have a Gnulib source file of the form
+@file{lib/foo_.h}, the corresponding @file{lib/foo.h} is such a file.
+
+@item
In projects which customarily omit from the CVS all files that generated
from other source files, all these files and directories would not be
added into CVS. The only file that must be added to CVS is
but it does not offer the possibility to change the way Gnulib is used.
Also it does not report in the ChangeLogs the files that it had to add
because they were missing.
+
+@end itemize
+
+The same holds for other version control systems than CVS, such as @samp{git}
+or @samp{svn}.
projects / gnulib.git / blobdiff