@node Invoking gnulib-tool
@chapter Invoking gnulib-tool
-@c Copyright (C) 2005-2011 Free Software Foundation, Inc.
+@c Copyright (C) 2005-2014 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
* 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 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
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
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
-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
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
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
+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:
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}.
+VCS-related files such as @file{.gitignore}.
Gnulib also contains files generated by @command{make} (and removed by
@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.
+into the VCS, but instead added to @file{.gitignore} or equivalent.
@item
In projects which customarily omit from their VCS all files that are
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.
projects / gnulib.git / blobdiff