X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib-tool.texi;h=7432ab1a742caecd96dee407752507d10ece9bbd;hb=9e587fbb7b888126ecdf62a2ed968343215df2d0;hp=39081801c3e8dc6e83c3eae180b0d06e595c2567;hpb=4fc10daa05477586fea99b6b3ca02a87d1102fa1;p=gnulib.git diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi index 39081801c..7432ab1a7 100644 --- a/doc/gnulib-tool.texi +++ b/doc/gnulib-tool.texi @@ -145,7 +145,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. @@ -161,11 +161,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 @@ -302,32 +302,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 @@ -372,6 +390,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 @@ -381,7 +400,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 @@ -545,47 +564,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{.cvsignore}. 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, 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