@node Invoking gnulib-tool
@chapter Invoking gnulib-tool
-@c Copyright (C) 2005, 2006, 2007 Free Software Foundation, Inc.
+@c Copyright (C) 2005-2009 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
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
* Modified imports:: Changing the import specification.
* Simple update:: Tracking Gnulib development.
* Source changes:: Impact of Gnulib on your source files.
+* 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
and these flags have no effect after any system header file has been included.
+@node gettextize and autopoint
+@section Caveat: @code{gettextize} and @code{autopoint} users
+
+@cindex gettextize, caveat
+@cindex autopoint, caveat
+The programs @code{gettextize} and @code{autopoint}, part of
+GNU @code{gettext}, import or update the internationalization infrastructure.
+Some of this infrastructure, namely ca.@: 20 autoconf macro files and the
+@file{config.rpath} file, is also contained in Gnulib and may be imported
+by @code{gnulib-tool}. The use of @code{gettextize} or @code{autopoint}
+will therefore overwrite some of the files that @code{gnulib-tool} has
+imported, and vice versa.
+
+Avoiding to use @code{gettextize} (manually, as package maintainer) or
+@code{autopoint} (as part of a script like @code{autoreconf} or
+@code{autogen.sh}) is not the solution: These programs also import the
+infrastructure in the @file{po/} and optionally in the @file{intl/} directory.
+
+The copies of the conflicting files in Gnulib are more up-to-date than
+the copies brought in by @code{gettextize} and @code{autopoint}. When a
+new @code{gettext} release is made, the copies of the files in Gnulib will
+be updated immediately.
+
+The solution is therefore:
+
+@enumerate
+@item
+When you run @code{gettextize}, always use the @code{gettextize} from the
+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}
+afterwards.
+
+@item
+If you get an error message like
+@code{*** error: gettext infrastructure mismatch:
+using a Makefile.in.in from gettext version ...
+but the autoconf macros are from gettext version ...},
+it means that a new GNU gettext release was made, and its autoconf macros
+were integrated into Gnulib and now mismatch the @file{po/} infrastructure.
+In this case, fetch and install the new GNU gettext release and run
+@code{gettextize} followed by @code{gnulib-tool}.
+@end enumerate
+
+
+@node Localization
+@section Handling Gnulib's own message translations
+
+Gnulib provides some functions that emit translatable messages using GNU
+@code{gettext}. The @samp{gnulib} domain at the
+@url{http://translationproject.org/, Translation Project} collects
+translations of these messages, which you should incorporate into your
+own programs.
+
+There are two basic ways to achieve this. The first, and older, method
+is to list all the source files you use from Gnulib in your own
+@file{po/POTFILES.in} file. This will cause all the relevant
+translatable strings to be included in your POT file. When you send
+this POT file to the Translation Project, translators will normally fill
+in the translations of the Gnulib strings from their ``translation
+memory'', and send you back updated PO files.
+
+However, this process is error-prone: you might forget to list some
+source files, or the translator might not be using a translation memory
+and provide a different translation than another translator, or the
+translation might not be kept in sync between Gnulib and your package.
+It is also slow and causes substantial extra work, because a human
+translator must be in the loop for each language and you will need to
+incorporate their work on request.
+
+For these reasons, a new method was designed and is now recommended. If
+you pass the @code{--po-base=@var{directory}} and @code{--po-domain=@var{domain}}
+options to @code{gnulib-tool}, then @code{gnulib-tool} will create a
+separate directory with its own @file{POTFILES.in}, and fetch current
+translations directly from the Translation Project (using
+@command{rsync} or @command{wget}, whichever is available).
+The POT file in this directory will be called
+@file{@var{domain}-gnulib.pot}, depending on the @var{domain} you gave to the
+@code{--po-domain} option (typically the same as the package name).
+This causes these translations to reside in a separate message domain,
+so that they do not clash either with the translations for the main part
+of your package nor with those of other packages on the system that use
+possibly different versions of Gnulib.
+When you use these options, the functions in Gnulib are built
+in such a way that they will always use this domain regardless of the
+default domain set by @code{textdomain}.
+
+In order to use this method, you must -- in each program that might use
+Gnulib code -- add an extra line to the part of the program that
+initializes locale-dependent behavior. Where you would normally write
+something like:
+
+@example
+@group
+ setlocale (LC_ALL, "");
+ bindtextdomain (PACKAGE, LOCALEDIR);
+ textdomain (PACKAGE);
+@end group
+@end example
+
+@noindent
+you should add an additional @code{bindtextdomain} call to inform
+gettext of where the MO files for the extra message domain may be found:
+
+@example
+@group
+ bindtextdomain (PACKAGE "-gnulib", LOCALEDIR);
+@end group
+@end example
+
+(This example assumes that the @var{domain} that you specified
+to @code{gnulib-tool} is the same as the value of the @code{PACKAGE}
+preprocessor macro.)
+
+Since you do not change the @code{textdomain} call, the default message
+domain for your program remains the same and your own use of @code{gettext}
+functions will not be affected.
+
+
@node VCS Issues
@section Issues with Version Control Systems
@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}
+@code{make clean}), using information determined by @command{configure}.
They should not be checked into the VCS, 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.
+@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.
@item
In projects which customarily omit from their VCS all files that are generated
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.