@node Invoking gnulib-tool
@chapter Invoking gnulib-tool
-@c Copyright (C) 2005-2008 Free Software Foundation, Inc.
+@c Copyright (C) 2005-2010 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.3 or
simplifies the management of source files, @file{Makefile.am}s and
@file{configure.ac} in packages incorporating Gnulib modules.
+@file{gnulib-tool} is not installed in a standard directory that is
+contained in the @code{PATH} variable. It needs to be run directly in
+the directory that contains the Gnulib source code. You can do this
+either by specifying the absolute filename of @file{gnulib-tool}, or
+you can also use a symbolic link from a place inside your @code{PATH}
+to the @file{gnulib-tool} file of your preferred and most up-to-date
+Gnulib checkout, like this:
+@smallexample
+$ ln -s $HOME/gnu/src/gnulib.git/gnulib-tool $HOME/bin/gnulib-tool
+@end smallexample
+
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
a real run without changing anything.
@menu
+* Which modules?:: Determining the needed set of Gnulib modules
* Initial import:: First import of Gnulib modules.
* Modified imports:: Changing the import specification.
* Simple update:: Tracking Gnulib development.
@end menu
+@node Which modules?
+@section Finding modules
+@cindex Finding modules
+
+There are three ways of finding the names of Gnulib modules that you can use
+in your package:
+
+@itemize
+@item
+You have the complete module list, sorted according to categories, in
+@url{http://www.gnu.org/software/gnulib/MODULES.html}.
+
+@item
+If you are looking for a particular POSIX header or function replacement,
+look in the chapters @ref{Header File Substitutes} and
+@ref{Function Substitutes}. For headers and functions that are provided by
+Glibc but not standardized by POSIX, look in the chapters
+@ref{Glibc Header File Substitutes} and @ref{Glibc Function Substitutes}.
+
+@item
+If you have already found the source file in Gnulib and are looking for the
+module that contains this source file, you can use the command
+@samp{gnulib-tool --find @var{filename}}.
+@end itemize
+
+
@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
+Gnulib assumes that your project uses Autoconf. When using Gnulib, you
+will need to have Autoconf and Automake among your build tools. Note that
+while the use of Automake in your project's top level directory is an
+easy way to fulfil the Makefile conventions of the GNU coding standards,
+Gnulib does not require it. But when you use Gnulib, Automake will be
+used at least in a subdirectory of your project.
+
+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
@section Issues with Version Control Systems
If a project stores its source files in a version control system (VCS),
-such as CVS, SVN, or Git, one needs to decide which files to commit.
+such as CVS, Subversion, or Git, one needs to decide which files to commit.
-All files created by @code{gnulib-tool}, except @file{gnulib-cache.m4},
-should be treated like generated source files, like for example a
-@file{parser.c} file is generated from @file{parser.y}.
+In principle, all files created by @code{gnulib-tool}, except
+@file{gnulib-cache.m4}, can be treated like generated source files,
+like for example a @file{parser.c} file generated from
+@file{parser.y}. Alternatively, they can be considered source files
+and updated manually.
-@itemize
+Here are the three different approaches in common use. Each has its
+place, and you should use whichever best suits your particular project
+and development methods.
+@enumerate
@item
-In projects which commit all source files, whether generated or not, into
-their VCS, the @code{gnulib-tool} generated files should all be committed.
-In this case, you also pass the option @samp{--no-vc-files} to
-@code{gnulib-tool}.
+In projects which commit all source files, whether generated or not,
+into their VCS, the @code{gnulib-tool} generated files should all be
+committed. In this case, you should pass the option
+@samp{--no-vc-files} to @code{gnulib-tool}, which avoids alteration of
+VCS-related files such as @file{.cvsignore}.
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 the VCS, but instead added to
-@file{.gitignore} or @file{.cvsignore}.
-When you have a Gnulib source file of the form @file{lib/foo.in.h}, the
-corresponding @file{lib/foo.h} is such a file.
+@code{make clean}), using information determined by
+@command{configure}. For a Gnulib source file of the form
+@file{lib/foo.in.h}, the corresponding @file{lib/foo.h} is such a
+@command{make}-generated file. These should @emph{not} be checked
+into the VCS, but instead added to @file{.cvsignore} or equivalent.
@item
-In projects which customarily omit from their VCS all files that are generated
-from other source files, all these files and directories would not be
-added into the VCS. The only file that must be added to the VCS is
-@file{gnulib-cache.m4} in the M4 macros directory. Also, the script for
-restoring files not in the VCS, customarily called @file{autogen.sh} or
-@file{bootstrap.sh}, will typically contain the statement for restoring
-the omitted files:
+In projects which customarily omit from their VCS all files that are
+generated from other source files, none of these files and directories
+are added into the VCS. The only file that must be added to the VCS
+is @file{gnulib-cache.m4} in the M4 macros directory. Also, the
+script for restoring files not in the VCS, customarily called
+@file{autogen.sh} or @file{bootstrap}, will typically contain the
+statement for restoring the omitted files:
@smallexample
$ gnulib-tool --update
Also it does not report in the ChangeLogs the files that it had to add
because they were missing.
-@end itemize
+Gnulib includes the file @file{build-aux/bootstrap} to aid a developer
+in using this setup. Furthermore, in projects that use git for
+version control, it is possible to use a git submodule containing the
+precise commit of the gnulib repository, so that each developer
+running @file{bootstrap} will get the same version of all
+gnulib-provided files. The location of the submodule can be chosen to
+fit the package's needs; here's how to initially create the submodule
+in the directory @file{.gnulib}:
+
+@smallexample
+$ dir=.gnulib
+$ git submodule add -- git://git.sv.gnu.org/gnulib.git $dir
+$ git config alias.syncsub "submodule foreach git pull origin master"
+@end smallexample
+
+@noindent
+Thereafter, @file{bootstrap} can run this command to update the
+submodule to the recorded checkout level:
+
+@smallexample
+git submodule update --init $dir
+@end smallexample
+
+@noindent
+and a developer can use this sequence to update to a newer version of
+gnulib:
+
+@smallexample
+$ git syncsub
+$ git add $dir
+$ ./bootstrap
+@end smallexample
+
+@item
+Some projects take a ``middle road'': they do commit Gnulib source
+files as in the first approach, but they do not commit other derived
+files, such as a @code{Makefile.in} generated by Automake. This
+increases the size and complexity of the repository, but can help
+occasional contributors by not requiring them to have a full Gnulib
+checkout to do a build, and all developers by ensuring that all
+developers are working with the same version of Gnulib in the
+repository. It also supports multiple Gnulib instances within a
+project. It remains important not to commit the
+@command{make}-generated files, as described above.
+
+@end enumerate
@node Unit tests