doc: recommendations on gettext version

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

diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index 443cbc2..8d0e683 100644 (file)
--- a/doc/gnulib-tool.texi
+++ b/doc/gnulib-tool.texi
@@ -1,7 +1,7 @@
 @node Invoking gnulib-tool
 @chapter Invoking gnulib-tool
 
 @node Invoking gnulib-tool
 @chapter Invoking gnulib-tool
 

-@c Copyright (C) 2005-2011 Free Software Foundation, Inc.
+@c Copyright (C) 2005-2012 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
 
 @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


@@ -48,6 +48,7 @@ a real run without changing anything.
 * Localization::                Handling Gnulib's own message translations.
 * VCS Issues::                  Integration with Version Control Systems.
 * Unit tests::                  Bundling the unit tests of the Gnulib modules.
 * Localization::                Handling Gnulib's own message translations.
 * VCS Issues::                  Integration with Version Control Systems.
 * Unit tests::                  Bundling the unit tests of the Gnulib modules.

+* Conditional dependencies::    Avoiding unnecessary checks and compilations.

 @end menu
 
 
 @end menu
 
 


@@ -216,6 +217,17 @@ gl_EARLY
 ...
 @end example
 
 ...
 @end example
 

+If you are using @code{AC_PROG_CC_STDC}, the macro @code{gl_EARLY} must
+be called after it, like this:
+
+@example
+...
+AC_PROG_CC
+AC_PROG_CC_STDC
+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.  It must come after
 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.  It must come after


@@ -459,7 +471,9 @@ 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.
 
 new @code{gettext} release is made, the copies of the files in Gnulib will
 be updated immediately.
 

-The solution is therefore:
+The choice of which version of gettext to require depends on the needs
+of your package.  For a package that wants to comply to GNU Coding
+Standards, the steps are:

 
 @enumerate
 @item
 
 @enumerate
 @item


@@ -467,12 +481,13 @@ 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
 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}.
+at the time the Gnulib snapshot was taken.

 
 @item
 
 @item

-When a script of yours run @code{autopoint}, invoke @code{gnulib-tool}
-afterwards.
+After running @code{gettextize}, invoke @code{gnulib-tool} and import
+the @code{gettext} module.  Also, copy the latest version of gnulib's
+@file{build-aux/po/Makefile.in.in} to your @file{po/} directory (this
+is done for you if you use gnulib's @file{bootstrap} script).

 
 @item
 If you get an error message like
 
 @item
 If you get an error message like


@@ -483,6 +498,32 @@ 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}.
 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
+
+On the other hand, if your package is not as concerned with compliance
+to the latest standards, but instead favors development on stable
+environments, the steps are:
+
+@enumerate
+@item
+Determine the oldest version of @code{gettext} that you intend to
+support during development (at this time, gnulib recommends going no
+older than version 0.17).  Run @code{autopoint} (not
+@code{gettextize}) to copy infrastructure into place (newer versions
+of gettext will install the older infrastructure that you requested).
+
+@item
+Invoke @code{gnulib-tool}, and import the @code{gettext-h} module.
+@end enumerate
+
+Regardless of which approach you used to get the infrastructure in
+place, the following steps must then be used to preserve that
+infrastructure (gnulib's @file{bootstrap} script follows these rules):
+
+@enumerate
+@item
+When a script of yours run @code{autopoint}, invoke @code{gnulib-tool}
+afterwards.

 
 @item
 When you invoke @code{autoreconf} after @code{gnulib-tool}, make sure to
 
 @item
 When you invoke @code{autoreconf} after @code{gnulib-tool}, make sure to


@@ -713,3 +754,54 @@ 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.
 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.

+
+
+@node Conditional dependencies
+@section Avoiding unnecessary checks and compilations
+
+@cindex conditional dependencies
+In some cases, a module is needed by another module only on specific
+platforms.  But when a module is present, its autoconf checks are always
+executed, and its @code{Makefile.am} additions are always enabled.  So
+it can happen that some autoconf checks are executed and some source files
+are compiled, although no other module needs them on this particular
+platform, just @emph{in case} some other module would need them.
+
+The option @samp{--conditional-dependencies} enables an optimization of
+configure checks and @code{Makefile.am} snippets that avoids this.  With
+this option, whether a module is considered ``present'' is no longer decided
+when @code{gnulib-tool} is invoked, but later, when @code{configure} is run.
+This applies to modules that were added as dependencies while
+@code{gnulib-tool} was run; modules that were passed on the command line
+explicitly are always ``present''.
+
+For example, the @code{timegm} module needs, on platforms
+where the system's @code{timegm} function is missing or buggy, a replacement
+that is based on a function @code{mktime_internal}.  The module
+@code{mktime-internal} that provides this function provides it on all
+platforms.  So, by default, the file @file{mktime-internal.c} will be
+compiled on all platforms --- even on glibc and BSD systems which have a
+working @code{timegm} function.  When the option
+@samp{--conditional-dependencies} is given, on the other hand, and if
+@code{mktime-internal} was not explicitly required on the command line,
+the file @file{mktime-internal.c} will only be compiled on the platforms
+where the @code{timegm} needs them.
+
+Conditional dependencies are specified in the module description by putting
+the condition on the same line as the dependent module, enclosed in brackets.
+The condition is a boolean shell expression that can assume that the
+@code{configure.ac} snippet from the module description has already been
+executed.  In the example above, the dependency from @code{timegm} to
+@code{mktime-internal} is written like this:
+
+@smallexample
+Depends-on:
+...
+mktime-internal [test $HAVE_TIMEGM = 0 || test $REPLACE_TIMEGM = 1]
+...
+@end smallexample
+
+Note: The option @samp{--conditional-dependencies} cannot be used together
+with the option @samp{--with-tests}.  It also cannot be used when a package
+uses @code{gnulib-tool} for several subdirectories, with different values
+of @samp{--source-base}, in the scope of a single @code{configure.ac} file.