-@node Invoking gnulib-tool
-@chapter Invoking gnulib-tool
-
-@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.
-
-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.
-
-@menu
-* Initial import:: First import of Gnulib modules.
-* Modified imports:: Changing the import specification.
-* Simple update:: Tracking Gnulib development.
-* CVS Issues:: Integration with CVS.
-@end menu
-
-
-@node Initial import
-@section Initial import
-@cindex initial import
-
-Gnulib assumes your project uses Autoconf and Automake. Invoking
-@samp{gnulib-tool --import} will copy source files, create a
-@file{Makefile.am} to build them, generate a file @file{gnulib-comp.m4} with
-Autoconf M4 macro declarations used by @file{configure.ac}, and generate
-a file @file{gnulib-cache.m4} containing the cached specification of how
-Gnulib is used.
-
-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}).
-
-@example
-~/src/libfoo$ gnulib-tool --import strdup
-Module list with included dependencies:
- strdup
-File list:
- lib/strdup.c
- lib/strdup.h
- m4/onceonly_2_57.m4
- m4/strdup.m4
-Copying file m4/gnulib-tool.m4
-Copying file m4/onceonly_2_57.m4
-Copying file lib/strdup.c
-Copying file lib/strdup.h
-Copying file m4/strdup.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"
-
-Don't forget to
- - add "lib/Makefile" to AC_CONFIG_FILES in ./configure.ac,
- - mention "lib" in SUBDIRS in Makefile.am,
- - mention "-I m4" in ACLOCAL_AMFLAGS in Makefile.am,
- - invoke gl_EARLY in ./configure.ac, right after AC_PROG_CC,
- - invoke gl_INIT in ./configure.ac.
-~/src/libfoo$
-@end example
-
-By default, the source code is copied into @file{lib/} and the M4
-macros in @file{m4/}. You can override these paths by using
-@code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}. Some
-modules also provide other files necessary for building. These files
-are copied into the directory specified by @samp{AC_CONFIG_AUX_DIR} in
-@file{configure.ac} or by the @code{--aux-dir=DIRECTORY} option. If
-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.
-
-@code{gnulib-tool} will overwrite any pre-existing files, in
-particular @file{Makefile.am}. Unfortunately, separating the
-generated @file{Makefile.am} content (for building the gnulib library)
-into a separate file, say @file{gnulib.mk}, that could be included
-by your handwritten @file{Makefile.am} is not possible, due to how
-variable assignments are handled by Automake.
-
-Consequently, it is a good idea to choose directories that are not
-already used by your projects, to separate gnulib imported files from
-your own files. This approach is also useful if you want to avoid
-conflicts between other tools (e.g., @code{gettextize} that also copy
-M4 files into your package. Simon Josefsson successfully uses a source
-base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
-packages.
-
-After the @samp{--import} option on the command line comes the list of
-Gnulib modules that you want to incorporate in your package. The names
-of the modules coincide with the filenames in Gnulib's @file{modules/}
-directory.
-
-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
-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
-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
-as the removed module.
-
-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:
-
-@example
-ACLOCAL_AMFLAGS = -I m4
-@end example
-
-You are now ready to call the M4 macros in @code{gnulib-comp.m4} from
-@file{configure.ac}. The macro @code{gl_EARLY} must be called as soon
-as possible after verifying that the C compiler is working.
-Typically, this is immediately after @code{AC_PROG_CC}, as in:
-
-@example
-...
-AC_PROG_CC
-gl_EARLY
-...
-@end example
-
-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:
-
-@example
-...
-# For gnulib.
-gl_INIT
-...
-@end example
-
-@code{gl_INIT} will in turn call the macros related with the
-gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA}
-or autoconf or automake macros like @code{AC_FUNC_ALLOCA} or
-@code{AM_FUNC_GETLINE}. So there is no need to call those macros yourself
-when you use the corresponding gnulib modules.
-
-You must also make sure that the gnulib library is built. Add the
-@code{Makefile} in the gnulib source base directory to
-@code{AC_CONFIG_FILES}, as in:
-
-@example
-AC_CONFIG_FILES(... lib/Makefile ...)
-@end example
-
-You must also make sure that @code{make} will recurse into the gnulib
-directory. To achieve this, add the gnulib source base directory to a
-@code{SUBDIRS} Makefile.am statement, as in:
-
-@example
-SUBDIRS = lib
-@end example
-
-or if you, more likely, already have a few entries in @code{SUBDIRS},
-you can add something like:
-
-@example
-SUBDIRS += lib
-@end example
-
-Finally, you have to add compiler and linker flags in the appropriate
-source directories, so that you can make use of the gnulib library.
-Since some modules (@samp{getopt}, for example) may copy files into
-the build directory, @file{top_builddir/lib} is needed as well
-as @file{top_srcdir/lib}. For example:
-
-@example
-...
-AM_CPPFLAGS = -I$(top_srcdir)/lib -I$(top_builddir)/lib
-...
-LIBADD = lib/libgnu.a
-...
-@end example