@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}
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
-metainformation stored in the @file{modules/*} files, but with a
+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.
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
@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.
-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.
+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
@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