@node Invoking gnulib-tool
@chapter Invoking gnulib-tool
-@c Copyright (C) 2005-2010 Free Software Foundation, Inc.
+@c Copyright (C) 2005-2011 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
@samp{_GNU_SOURCE} may be ineffective, or may have only a limited
effect, if defined after the first system header file is included.
-Finally, note that you can not use @code{AC_LIBOBJ} or
+Finally, note that you cannot use @code{AC_LIBOBJ} or
@code{AC_REPLACE_FUNCS} in your @file{configure.ac} and expect the
resulting object files to be automatically added to @file{lib/libgnu.a}.
This is because your @code{AC_LIBOBJ} and @code{AC_REPLACE_FUNCS} invocations
You can at any moment decide to use Gnulib differently than the last time.
-If you only want to use more Gnulib modules, simply invoke
-@command{gnulib-tool --import @var{new-modules}}. @code{gnulib-tool}
-remembers which modules were used last time. The list of modules that
-you pass after @samp{--import} is @emph{added} to the previous list of
-modules.
+There are two ways to change how Gnulib is used. Which one you'll use,
+depends on where you keep track of options and module names that you pass
+to @code{gnulib-tool}.
-For most changes, such as added or removed modules, or even different
-choices of @samp{--lib}, @samp{--source-base} or @samp{--aux-dir}, there
-are two ways to perform the change.
-
-The standard way is to modify manually the file @file{gnulib-cache.m4}
-in the M4 macros directory, then launch @samp{gnulib-tool --import}.
+@itemize @bullet
+@item
+If you store the options and module names in a file under your own
+control, such as @file{autogen.sh}, @file{bootstrap},
+@file{bootstrap.conf}, or similar, simply invoke @command{gnulib-tool}
+again, with modified options and more or fewer module names.
-The other way is to call @command{gnulib-tool} again, with the changed
-command-line options. Note that this doesn't let you remove modules,
-because as you just learned, the list of modules is always cumulated.
-Also this way is often impractical, because you don't remember the way
-you invoked @code{gnulib-tool} last time.
+@item
+@code{gnulib-tool} remembers which modules were used last time. If you
+want to rely on @code{gnulib-tool}'s own memory of the last used
+options and module names, you can use the commands
+@command{gnulib-tool --add-import} and
+@command{gnulib-tool --remove-import}.
+
+So, if you only want to use more Gnulib modules, simply invoke
+@command{gnulib-tool --add-import @var{new-modules}}. The list of
+modules that you pass after @samp{--add-import} is @emph{added} to the
+previous list of modules.
+
+Similarly, if you want to use fewer Gnulib modules, simply invoke
+@command{gnulib-tool --remove-import @var{unneeded-modules}}. The list
+of modules that you pass after @samp{--remove-import} is @emph{removed}
+from the previous list of modules. Note that if a module is then still
+needed as dependency of other modules, it will be used nevertheless.
+If you want to @emph{really} not use a module any more, regardless of
+whether other modules may need it, you need to use the @samp{--avoid}
+option.
+
+For other changes, such as different choices of @samp{--lib},
+@samp{--source-base} or @samp{--aux-dir}, the normal way is to
+modify manually the file @file{gnulib-cache.m4} in the M4 macros
+directory, then launch @samp{gnulib-tool --add-import}.
The only change for which this doesn't work is a change of the
@samp{--m4-base} directory. Because, when you pass a different value of
@samp{--m4-base}, @code{gnulib-tool} will not find the previous
-@file{gnulib-cache.m4} file any more... A possible solution is to manually
-copy the @file{gnulib-cache.m4} into the new M4 macro directory.
+@file{gnulib-cache.m4} file any more. A possible solution is to
+manually copy the @file{gnulib-cache.m4} into the new M4 macro directory.
-In the @file{gnulib-cache.m4}, the macros have the following meaning:
+In the @file{gnulib-cache.m4} file, the macros have the following meaning:
@table @code
@item gl_MODULES
The argument is a space separated list of the requested modules, not including
file. Corresponds to the @samp{--macro-prefix} command line argument.
@end table
+@end itemize
@node Simple update
@section Simple update
does it:
@smallexample
-$ gnulib-tool --import
+$ gnulib-tool --add-import
@end smallexample
@noindent
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}.
+
+@item
+When you invoke @code{autoreconf} after @code{gnulib-tool}, make sure to
+not invoke @code{autopoint} a second time, by setting the @code{AUTOPOINT}
+environment variable, like this:
+@smallexample
+$ env AUTOPOINT=true autoreconf --install
+@end smallexample
@end enumerate
@item
In projects which customarily omit from their VCS all files that are
generated from other source files, none of these files and directories
-are added into the VCS. The only file that must be added to the VCS
-is @file{gnulib-cache.m4} in the M4 macros directory. Also, the
-script for restoring files not in the VCS, customarily called
-@file{autogen.sh} or @file{bootstrap}, will typically contain the
-statement for restoring the omitted files:
+are added into the VCS. As described in @ref{Modified imports}, there
+are two ways to keep track of options and module names that are passed
+to @code{gnulib-tool}. The command for restoring the omitted files
+depends on it:
+
+@itemize @bullet
+@item
+If they are stored in a file other than @code{gnulib-cache.m4}, such as
+@file{autogen.sh}, @file{bootstrap}, @file{bootstrap.conf}, or similar,
+the restoration command is the entire @code{gnulib-tool ... --import ...}
+invocation with all options and module names.
+
+@item
+If the project relies on @code{gnulib-tool}'s memory of the last used
+options and module names, then the file @file{gnulib-cache.m4} in the M4
+macros directory must be added to the VCS, and the restoration command
+is:
@smallexample
$ gnulib-tool --update
@end smallexample
-The @samp{--update} option operates much like the @samp{--import} option,
-but it does not offer the possibility to change the way Gnulib is used.
-Also it does not report in the ChangeLogs the files that it had to add
-because they were missing.
+The @samp{--update} option operates much like the @samp{--add-import}
+option, but it does not offer the possibility to change the way Gnulib is
+used. Also it does not report in the ChangeLogs the files that it had to
+add because they were missing.
+
+@end itemize
Gnulib includes the file @file{build-aux/bootstrap} to aid a developer
in using this setup. Furthermore, in projects that use git for
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.