X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib-tool.texi;h=7581d8179a8c13f8721ad6e8b6cee2917494adc8;hb=29abb5463234236cae0d607db33f16aeae395a39;hp=a8807c1139ebfd6702d6e2f8de3e568eb7e1a1c4;hpb=f283cf4e5364da816fdd6e376110035b04facae9;p=gnulib.git diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi index a8807c113..7581d8179 100644 --- a/doc/gnulib-tool.texi +++ b/doc/gnulib-tool.texi @@ -1,7 +1,7 @@ @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 @@ -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. +* Conditional dependencies:: Avoiding unnecessary checks and compilations. @end menu @@ -287,7 +288,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. -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 @@ -342,10 +343,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 -@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. -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 @@ -483,6 +484,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}. + +@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 @@ -705,3 +714,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. + + +@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.