X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib-tool.texi;h=1b021a4a809d853840c3f3d757eb4d6db44b1e2f;hb=1276a2c5f24c0c932426aca9c899fa524d2443f2;hp=0b18ffb0edc650e66fcb4a2022f38b324ceb4150;hpb=02fb71925dfd6ba737b58c756a3bf1ca2518e350;p=gnulib.git diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi index 0b18ffb0e..1b021a4a8 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-2009 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.3 or @@ -39,6 +39,7 @@ 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. @@ -47,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. +* 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 @@ -112,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 -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. @@ -128,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 -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 @@ -183,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 @@ -254,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 @@ -269,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. -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. - -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. +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}. -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 @@ -339,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 +@end itemize @node Simple update @section Simple update @@ -348,7 +412,7 @@ changing the list of modules or other parameters, a simple call does it: @smallexample -$ gnulib-tool --import +$ gnulib-tool --add-import @end smallexample @noindent @@ -407,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 @@ -415,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 @@ -433,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 @@ -476,8 +577,8 @@ 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 +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: @@ -512,47 +613,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), -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 -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{.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 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{.gitignore} or equivalent. @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: +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 +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 @@ -588,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.