Add missing module dependencies.

[gnulib.git] / doc / gnulib-tool.texi

diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index f9ee261..5531b9a 100644 (file)
--- a/doc/gnulib-tool.texi
+++ b/doc/gnulib-tool.texi
@@ -4,7 +4,7 @@
 @c Copyright (C) 2005-2008 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 under the terms of the GNU Free Documentation License, Version 1.3 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
@@ -35,6 +35,7 @@ a real run without changing anything.
 * gettextize and autopoint::    Caveat: @code{gettextize} and @code{autopoint} users!
 * Localization::                Handling Gnulib's own message translations.
 * VCS Issues::                  Integration with Version Control Systems.
+* Unit tests::                  Bundling the unit tests of the Gnulib modules.
 @end menu
 
 
@@ -400,8 +401,11 @@ The solution is therefore:
 @enumerate
 @item
 When you run @code{gettextize}, always use the @code{gettextize} from the
-newest GNU gettext release found on @url{http://ftp.gnu.org/gnu/gettext/},
-and invoke @code{gnulib-tool} afterwards.
+matching GNU gettext release.  For the most recent Gnulib checkout, this is
+the newest release found on @url{http://ftp.gnu.org/gnu/gettext/}.  For an
+older Gnulib snapshot, it is the release that was the most recent release
+at the time the Gnulib snapshot was taken.  Then, after @code{gettextize},
+invoke @code{gnulib-tool}.
 
 @item
 When a script of yours run @code{autopoint}, invoke @code{gnulib-tool}
@@ -508,6 +512,8 @@ should be treated like generated source files, like for example a
 @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}.
 
 Gnulib also contains files generated by @command{make} (and removed by
 @code{make clean}), using information determined by @command{configure}.
@@ -535,3 +541,39 @@ Also it does not report in the ChangeLogs the files that it had to add
 because they were missing.
 
 @end itemize
+
+
+@node Unit tests
+@section Bundling the unit tests of the Gnulib modules
+
+You can bundle the unit tests of the Gnulib modules together with your
+package, through the @samp{--with-tests} option.  Together with
+@samp{--with-tests}, you also specify the directory for these tests
+through the @samp{--tests-base} option.  Of course, you need to add this
+directory to the @code{SUBDIRS} variable in the @code{Makefile.am} of
+the parent directory.
+
+The advantage of having the unit tests bundled is that when your program
+has a problem on a particular platform, running the unit tests may help
+determine quickly if the problem is on Gnulib's side or on your package's
+side.  Also, it helps verifying Gnulib's portability, of course.
+
+The unit tests will be compiled and run when the user runs @samp{make check}.
+When the user runs only @samp{make}, the unit tests will not be compiled.
+
+In the @code{SUBDIRS} variable, it is useful to put the Gnulib tests directory
+after the directory containing the other tests, not before:
+
+@smallexample
+SUBDIRS = gnulib-lib src man tests gnulib-tests
+@end smallexample
+
+@noindent
+This will ensure that on platforms where there are test failures in either
+directory, users will see and report the failures from the tests of your
+program.
+
+Note: In packages which use more than one invocation of @code{gnulib-tool}
+in the scope of the same @code{configure.ac}, you cannot use
+@samp{--with-tests}.  You will have to use a separate @code{configure.ac}
+in this case.