@node Invoking gnulib-tool
@chapter Invoking gnulib-tool
-@c Copyright (C) 2005, 2006, 2007 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.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
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.
-* CVS Issues:: Integration with CVS.
+* 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.
+* Conditional dependencies:: Avoiding unnecessary checks and compilations.
@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
File list:
lib/dummy.c
lib/strdup.c
- lib/string_.h
+ lib/string.in.h
m4/absolute-header.m4
m4/extensions.m4
m4/gnulib-common.m4
Creating directory ./m4
Copying file lib/dummy.c
Copying file lib/strdup.c
-Copying file lib/string_.h
+Copying file lib/string.in.h
Copying file m4/absolute-header.m4
Copying file m4/extensions.m4
Copying file m4/gnulib-common.m4
By default, the source code is copied into @file{lib/} and the M4
macros in @file{m4/}. You can override these paths by using
@code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}. Some
-modules also provide other files necessary for building. These files
+modules also provide other files necessary for building. These files
are copied into the directory specified by @samp{AC_CONFIG_AUX_DIR} in
@file{configure.ac} or by the @code{--aux-dir=DIRECTORY} option. If
neither is specified, the current directory is assumed.
this option is generally discouraged.
@code{gnulib-tool} will overwrite any pre-existing files, in
-particular @file{Makefile.am}. Unfortunately, separating the
+particular @file{Makefile.am}. It is also possible to separate the
generated @file{Makefile.am} content (for building the gnulib library)
-into a separate file, say @file{gnulib.mk}, that could be included
-by your handwritten @file{Makefile.am} is not possible, due to how
-variable assignments are handled by Automake.
+into a separate file, say @file{gnulib.mk}, that can be included by your
+handwritten @file{Makefile.am}, but this is a more advanced use of
+@code{gnulib-tool}.
Consequently, it is a good idea to choose directories that are not
already used by your projects, to separate gnulib imported files from
...
@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
@example
...
-AM_CPPFLAGS = -I$(top_srcdir)/lib -I$(top_builddir)/lib
+AM_CPPFLAGS = -I$(top_builddir)/lib -I$(top_srcdir)/lib
...
LDADD = lib/libgnu.a
...
@samp{_GNU_SOURCE} may be ineffective, or may have only a limited
effect, if defined after the first system header file is included.
-A final word of warning: Gnulib currently assumes it will be
-responsible for @emph{all} functions that end up in the Autoconf
-@code{@@LIBOBJS@@} variables (and/or @code{@@LTLIBOBJS@@} if using
-Libtool), e.g., those specified in @code{AC_REPLACE_FUNCS} in your
-@file{configure.ac}. Therefore, if you have any functions which are
-not covered by Gnulib which need that treatment, you have to
-essentially reimplement AC_REPLACE_FUNCS using different names; for an
-example, see the Findutils sources. Perhaps this will be improved in
-the future.
+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
+from @file{configure.ac} augment a variable @code{@@LIBOBJS@@} (and/or
+@code{@@LTLIBOBJS@@} if using Libtool), whereas @file{lib/libgnu.a}
+is built from the contents of a different variable, usually
+@code{@@gl_LIBOBJS@@} (or @code{@@gl_LTLIBOBJS@@} if using Libtool).
@node Modified imports
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
@samp{--lib} command line argument.
@item gl_LGPL
-The presence of this macro corresponds to the @samp{--lgpl} command line
-argument. It takes no arguments.
+The presence of this macro without arguments corresponds to the @samp{--lgpl}
+command line argument. The presence of this macro with an argument (whose
+value must be 2 or 3) corresponds to the @samp{--lgpl=@var{arg}} command line
+argument.
@item gl_LIBTOOL
The presence of this macro corresponds to the @samp{--libtool} command line
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
This will create, update or remove files, as needed.
-@node CVS Issues
-@section CVS Issues
+Note: From time to time, changes are made in Gnulib that are not backward
+compatible. When updating to a more recent Gnulib, you should consult
+Gnulib's @file{NEWS} file to check whether the incompatible changes affect
+your project.
+
+
+@node Source changes
+@section Changing your sources for use with Gnulib
+
+Gnulib contains some header file overrides. This means that when building
+on systems with deficient header files in @file{/usr/include/}, it may create
+files named @file{string.h}, @file{stdlib.h}, @file{stdint.h} or similar in
+the build directory. In the other source directories of your package you
+will usually pass @samp{-I} options to the compiler, so that these Gnulib
+substitutes are visible and take precedence over the files in
+@file{/usr/include/}.
+
+These Gnulib substitute header files rely on @file{<config.h>} being
+already included. Furthermore @file{<config.h>} must be the first include
+in every compilation unit. This means that to @emph{all your source files}
+and likely also to @emph{all your tests source files} you need to add an
+@samp{#include <config.h>} at the top. Which source files are affected?
+Exactly those whose compilation includes a @samp{-I} option that refers to
+the Gnulib library directory.
+
+This is annoying, but inevitable: On many systems, @file{<config.h>} is
+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 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
+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.
-All files created by @code{gnulib-tool}, except @file{gnulib-cache.m4},
-should be treated like generated source files, like for example a
-@file{parser.c} file is generated from @file{parser.y}.
+@item
+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).
-@itemize
+@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
+
+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
+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
+
+
+@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
+
+If a project stores its source files in a version control system (VCS),
+such as CVS, Subversion, or Git, one needs to decide which files to commit.
+
+In principle, all files created by @code{gnulib-tool}, except
+@file{gnulib-cache.m4}, can be treated like generated source files,
+like for example a @file{parser.c} file generated from
+@file{parser.y}. Alternatively, they can be considered source files
+and updated manually.
+
+Here are the three different approaches in common use. Each has its
+place, and you should use whichever best suits your particular project
+and development methods.
+@enumerate
@item
-In projects which commit all source files, whether generated or not, into
-CVS, the @code{gnulib-tool} generated files should all be committed.
+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 should pass the option
+@samp{--no-vc-files} to @code{gnulib-tool}, which avoids alteration of
+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}
-They should not be checked into CVS, 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.
+@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{.gitignore} or equivalent.
@item
-In projects which customarily omit from the CVS all files that generated
-from other source files, all these files and directories would not be
-added into CVS. The only file that must be added to CVS is
-@file{gnulib-cache.m4} in the M4 macros directory. Also, the script for
-restoring files not in CVS, customarily called @file{autogen.sh} or
-@file{bootstrap.sh}, will typically contain the statement for restoring
-the omitted files:
+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. 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
-The same holds for other version control systems than CVS, such as @samp{git}
-or @samp{svn}.
+Gnulib includes the file @file{build-aux/bootstrap} to aid a developer
+in using this setup. Furthermore, in projects that use git for
+version control, it is possible to use a git submodule containing the
+precise commit of the gnulib repository, so that each developer
+running @file{bootstrap} will get the same version of all
+gnulib-provided files. The location of the submodule can be chosen to
+fit the package's needs; here's how to initially create the submodule
+in the directory @file{.gnulib}:
+
+@smallexample
+$ dir=.gnulib
+$ git submodule add -- git://git.sv.gnu.org/gnulib.git $dir
+$ git config alias.syncsub "submodule foreach git pull origin master"
+@end smallexample
+
+@noindent
+Thereafter, @file{bootstrap} can run this command to update the
+submodule to the recorded checkout level:
+
+@smallexample
+git submodule update --init $dir
+@end smallexample
+
+@noindent
+and a developer can use this sequence to update to a newer version of
+gnulib:
+
+@smallexample
+$ git syncsub
+$ git add $dir
+$ ./bootstrap
+@end smallexample
+
+@item
+Some projects take a ``middle road'': they do commit Gnulib source
+files as in the first approach, but they do not commit other derived
+files, such as a @code{Makefile.in} generated by Automake. This
+increases the size and complexity of the repository, but can help
+occasional contributors by not requiring them to have a full Gnulib
+checkout to do a build, and all developers by ensuring that all
+developers are working with the same version of Gnulib in the
+repository. It also supports multiple Gnulib instances within a
+project. It remains important not to commit the
+@command{make}-generated files, as described above.
+
+@end enumerate
+
+
+@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.
+
+
+@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