X-Git-Url: https://erislabs.net/gitweb/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fgnulib-tool.texi;h=8d0e6835ba8e3f616ad3c39d4c08c4e04da83f1e;hb=adae0138d43ccc0e5a302ca10fa1676359e92be8;hp=a8807c1139ebfd6702d6e2f8de3e568eb7e1a1c4;hpb=f283cf4e5364da816fdd6e376110035b04facae9;p=gnulib.git diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi index a8807c113..8d0e6835b 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-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 @@ -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 @@ -216,6 +217,17 @@ gl_EARLY ... @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 @@ -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. -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 +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 -@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 @@ -459,7 +471,9 @@ 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 solution is therefore: +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 @@ -467,12 +481,13 @@ 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. Then, after @code{gettextize}, -invoke @code{gnulib-tool}. +at the time the Gnulib snapshot was taken. @item -When a script of yours run @code{autopoint}, invoke @code{gnulib-tool} -afterwards. +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). @item If you get an error message like @@ -485,6 +500,40 @@ 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 @@ -705,3 +754,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.