modechange: add notations +40, 00440, etc.

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

diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index e4908e8..1b025c0 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-2010 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


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


@@ -342,10 +354,10 @@ 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
+@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.
 
 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


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


@@ -594,20 +614,34 @@ 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
 @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
 
 
 @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
 
 Gnulib includes the file @file{build-aux/bootstrap} to aid a developer
 in using this setup.  Furthermore, in projects that use git for


@@ -691,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.