Merge branch 'stable'

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

diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index 5531b9a..adeb229 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-2008 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
 
 @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


@@ -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.
 
 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
 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,6 +39,7 @@ some commands with the option @samp{--dry-run}; then
 a real run without changing anything.
 
 @menu
 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.
 * Initial import::              First import of Gnulib modules.
 * Modified imports::            Changing the import specification.
 * Simple update::               Tracking Gnulib development.


@@ -36,15 +48,48 @@ 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
 
 

+@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
 
 @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{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


@@ -101,7 +146,7 @@ Don't forget to
 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
 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.
 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.


@@ -117,11 +162,11 @@ mechanism the maintainer applies to the sources.  For these reasons,
 this option is generally discouraged.
 
 @code{gnulib-tool} will overwrite any pre-existing files, in
 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)
 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
 
 Consequently, it is a good idea to choose directories that are not
 already used by your projects, to separate gnulib imported files from


@@ -172,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


@@ -243,7 +299,7 @@ Also, on some platforms macros like @samp{_FILE_OFFSET_BITS} and
 @samp{_GNU_SOURCE} may be ineffective, or may have only a limited
 effect, if defined after the first system header file is included.
 
 @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
 @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


@@ -258,32 +314,50 @@ is built from the contents of a different variable, usually
 
 You can at any moment decide to use Gnulib differently than the last time.
 
 
 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
 
 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
 @table @code
 @item gl_MODULES
 The argument is a space separated list of the requested modules, not including


@@ -328,6 +402,7 @@ The argument is the prefix to use for macros in the @file{gnulib-comp.m4}
 file.  Corresponds to the @samp{--macro-prefix} command line argument.
 @end table
 
 file.  Corresponds to the @samp{--macro-prefix} command line argument.
 @end table
 

+@end itemize

 
 @node Simple update
 @section Simple update
 
 @node Simple update
 @section Simple update


@@ -337,7 +412,7 @@ changing the list of modules or other parameters, a simple call
 does it:
 
 @smallexample
 does it:
 
 @smallexample

-$ gnulib-tool --import
+$ gnulib-tool --add-import

 @end smallexample
 
 @noindent
 @end smallexample
 
 @noindent


@@ -420,6 +495,14 @@ 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}.

+
+@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
 
 
 @end enumerate
 
 


@@ -501,47 +584,112 @@ functions will not be affected.
 @section Issues with Version Control Systems
 
 If a project stores its source files in a version control system (VCS),
 @section Issues with Version Control Systems
 
 If a project stores its source files in a version control system (VCS),

-such as CVS, SVN, or Git, one needs to decide which files to commit.
+such as CVS, Subversion, or Git, one needs to decide which files to commit.

 
 

-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}.
+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.

 
 

-@itemize
+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
 @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}.
+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{.cvsignore}.

 
 Gnulib also contains files generated by @command{make} (and removed by
 
 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 the VCS, but instead added to
-@file{.gitignore} or @file{.cvsignore}.
-When you have a Gnulib source file of the form @file{lib/foo.in.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{.cvsignore} or equivalent.
+
+@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.  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
 
 @item

-In projects which customarily omit from their VCS all files that are generated
-from other source files, all these files and directories would not be
-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.sh}, will typically contain the statement for restoring
-the omitted files:
+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
 
 
 @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
 
 
 @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
+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
 
 @node Unit tests
 @section Bundling the unit tests of the Gnulib modules


@@ -577,3 +725,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.