X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib-tool.texi;h=39081801c3e8dc6e83c3eae180b0d06e595c2567;hb=fbe6ced5d2fdadeeea4194725d05a52cf3b5ebd7;hp=f473261c58c02a1b8aaef8b8fc741e9a14a3eb0b;hpb=8ac36b1754b7c215526e0ccba0b992438b79097d;p=gnulib.git diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi index f473261c5..39081801c 100644 --- a/doc/gnulib-tool.texi +++ b/doc/gnulib-tool.texi @@ -1,10 +1,10 @@ @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.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 @@ -21,6 +21,17 @@ 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. +@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 @@ -28,21 +39,56 @@ 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. * 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 +@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 @@ -371,6 +417,56 @@ used to set system dependent flags (such as @code{_GNU_SOURCE} on GNU systems), 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 @@ -460,6 +556,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}. @@ -487,3 +585,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.