From 896d8e9f1c3e752ef11d3b3ab64f1c709d163edd Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Mon, 19 Sep 2005 15:38:33 +0000 Subject: [PATCH] Major update of the "Invoking gnulib-tool" chapter. --- doc/ChangeLog | 4 + doc/gnulib.texi | 319 ++++++++++++++++++++++++++++-------------------- 2 files changed, 190 insertions(+), 133 deletions(-) diff --git a/doc/ChangeLog b/doc/ChangeLog index 7da05820af..1a35023678 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,7 @@ +2005-09-18 Bruno Haible + + * gnulib.texi (Invoking gnulib-tool): 50% rewritten. + 2005-08-11 Simon Josefsson * gnulib.texi (Initial import, Finishing touches): Mention diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 4ca978e131..8b7988d803 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -1,5 +1,5 @@ \input texinfo @c -*-texinfo-*- -@comment $Id: gnulib.texi,v 1.17 2005-09-13 15:06:24 meyering Exp $ +@comment $Id: gnulib.texi,v 1.18 2005-09-19 15:38:33 haible Exp $ @comment %**start of header @setfilename gnulib.info @settitle GNU Gnulib @@ -7,7 +7,7 @@ @syncodeindex pg cp @comment %**end of header -@set UPDATED $Date: 2005-09-13 15:06:24 $ +@set UPDATED $Date: 2005-09-19 15:38:33 $ @copying This manual is for GNU Gnulib (updated @value{UPDATED}), @@ -364,13 +364,24 @@ generated automatically. @pindex gnulib-tool @cindex invoking @command{gnulib-tool} -Run @samp{gnulib-tool --help}, and use the source. -@command{gnulib-tool} is the way to import Gnulib modules. +@command{gnulib-tool} is the way to import Gnulib modules. It is also +possible to borrow Gnulib modules in a package without using +@command{gnulib-tool}, relying only on the metainformation stored in +the @file{modules/*} files, but with a growing number of modules this +becomes tedious. @command{gnulib-tool} simplifies the management of +source files, @file{Makefile.am}s and @file{configure.ac} in packages +incorporating Gnulib modules. + +Run @samp{gnulib-tool --help}. To get familiar with @command{gnulib-tool}, +you can also try some commands with the option @samp{--dry-run}; then +@code{gnulib-tool} will only report which actions it would perform in a +real run. @menu * Initial import:: First import of Gnulib modules. -* Importing updated files:: Subsequent imports. -* Finishing touches:: Simplifying imports. +* Modified imports:: Changing the import specification. +* Simple update:: Tracking Gnulib development. +* CVS Issues:: Integration with CVS. @end menu @@ -380,8 +391,10 @@ Run @samp{gnulib-tool --help}, and use the source. Gnulib assumes your project uses Autoconf and Automake. Invoking @samp{gnulib-tool --import} will copy source files, create a -@file{Makefile.am} to build them, and generate a @file{gnulib.m4} with -Autoconf M4 macro declarations used by @file{configure.ac}. +@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 +Gnulib is used. Our example will be a library that uses Autoconf, Automake and Libtool. It calls @code{strdup}, and you wish to use gnulib to make @@ -396,36 +409,39 @@ File list: lib/strdup.h m4/onceonly_2_57.m4 m4/strdup.m4 -Creating ./lib/Makefile.am... -Creating ./m4/gnulib.m4... +Copying file m4/gnulib-tool.m4 +Copying file m4/onceonly_2_57.m4 +Copying file lib/strdup.c +Copying file lib/strdup.h +Copying file m4/strdup.m4 +Creating lib/Makefile.am +Creating m4/gnulib-cache.m4 +Creating m4/gnulib-comp.m4 Finished. You may need to add #include directives for the following .h files. #include "strdup.h" -Don't forget to add "lib/Makefile" -to AC_CONFIG_FILES in "./configure.ac" and to mention -"lib" in SUBDIRS in some Makefile.am. +Don't forget to + - add "lib/Makefile" to AC_CONFIG_FILES in ./configure.ac, + - mention "lib" in SUBDIRS in Makefile.am, + - mention "-I m4" in ACLOCAL_AMFLAGS in Makefile.am, + - invoke gl_EARLY in ./configure.ac, right after AC_PROG_CC, + - invoke gl_INIT in ./configure.ac. ~/src/libfoo$ @end example 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}, or by -adding @samp{gl_SOURCE_BASE(DIRECTORY)} and -@samp{gl_M4_BASE(DIRECTORY)} to your @file{configure.ac}. Some +@code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}. Some 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. If a module -is automatically added as a dependency is added, that you wish to -avoid, you may use @code{--avoid=MODULE}, possibly several times. Of -course, you will then need to implement the same interface as the -removed module. +neither is specified, the current directory is assumed. -@code{gnulib-tool} can make symbolic links instead -of copying the source files. Use the @code{--symbolic} -(or @code{-s} for short) option to do this. +@code{gnulib-tool} can make symbolic links instead of copying the +source files. Use the @samp{--symbolic} (or @samp{-s} for short) option +to do this. @code{gnulib-tool} will overwrite any pre-existing files, in particular @file{Makefile.am}. Unfortunately, separating the @@ -434,32 +450,44 @@ 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. -Consequently, it can be a good idea to chose directories that are not +Consequently, it is a good idea to choose directories that are not already used by your projects, to separate gnulib imported files from -your own files. This approach can also be useful if you want to avoid -conflicts between other tools (e.g., @code{getextize} that also copy +your own files. This approach is also useful if you want to avoid +conflicts between other tools (e.g., @code{gettextize} that also copy M4 files into your package. Simon Josefsson successfully uses a source base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several packages. +After the @samp{--import} option on the command line comes the list of +Gnulib modules that you want to incorporate in your package. The names +of the modules coincide with the filenames in Gnulib's @file{modules/} +directory. + +Some Gnulib modules depend on other Gnulib modules. @code{gnulib-tool} +will automatically add the needed modules as well; you need not list +them explicitly. @code{gnulib-tool} will also memoize which dependent +modules it has added, so that when someday a dependency is dropped, the +implicitly added module is dropped as well (unless you have explicitly +requested that module). + +If you want to cut a dependency, i.e. not add a module although one of +your requested modules depends on it, you may use the option +@samp{--avoid=@var{module}} to do so. Multiple uses of this option are +possible. Of course, you will then need to implement the same interface +as the removed module. + A few manual steps are required to finish the initial import. +@code{gnulib-tool} printed a summary of these steps. First, you need to make sure Autoconf can find the macro definitions -in @file{gnulib.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in your +in @file{gnulib-comp.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in your top-level @file{Makefile.am} file, as in: @example ACLOCAL_AMFLAGS = -I m4 @end example -Naturally, replace @file{m4} with the value from @code{--m4-base} or -@code{gl_M4_BASE}. If the M4 base is @file{gl/m4} you would use: - -@example -ACLOCAL_AMFLAGS = -I gl/m4 -@end example - -You are now ready to call the M4 macros in @code{gnulib.m4} from +You are now ready to call the M4 macros in @code{gnulib-comp.m4} from @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon as possible after verifying that the C compiler is working. Typically, this is immediately after @code{AC_PROG_CC}, as in: @@ -473,9 +501,7 @@ gl_EARLY 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. Or in a separate -section with other gnulib statements, such as @code{gl_SOURCE_BASE}. -For example: +you normally check for header files or functions. For example: @example ... @@ -486,8 +512,8 @@ gl_INIT @code{gl_INIT} will in turn call the macros related with the gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA} -or autoconf or automake macro like @code{AC_FUNC_ALLOCA} or -@code{AM_FUNC_GETLINE} so there is no need to call those macros yourself +or autoconf or automake macros like @code{AC_FUNC_ALLOCA} or +@code{AM_FUNC_GETLINE}. So there is no need to call those macros yourself when you use the corresponding gnulib modules. You must also make sure that the gnulib library is built. Add the @@ -498,15 +524,9 @@ You must also make sure that the gnulib library is built. Add the AC_CONFIG_FILES(... lib/Makefile ...) @end example -If your gnulib source base is @file{gl}, you would use: - -@example -AC_CONFIG_FILES(... gl/Makefile ...) -@end example - -You must also make sure that @code{make} work in the gnulib directory. -Add the gnulib source base directory to a @code{SUBDIRS} Makefile.am -statement, as in: +You must also make sure that @code{make} will recurse into the gnulib +directory. To achieve this, add the gnulib source base directory to a +@code{SUBDIRS} Makefile.am statement, as in: @example SUBDIRS = lib @@ -519,12 +539,6 @@ you can add something like: SUBDIRS += lib @end example -If you are using a gnulib source base of @code{gl}, you would use: - -@example -SUBDIRS += gl -@end example - Finally, you have to add compiler and linker flags in the appropriate source directories, so that you can make use of the gnulib library. Since some modules (@samp{getopt}, for example) may copy files into @@ -544,90 +558,129 @@ example, you would need to make sure that @samp{#include "strdup.h"} is evaluated when compiling all source code files, that want to make use of @code{strdup}. -When an include file is provided by the gnulib +When an include file is provided by Gnulib you shouldn't try to include the corresponding system header files -yourself but let the gnulib header file do it as the ordering -of the definition for some symbols may be significant. +yourself, but let the gnulib header file do it. The ordering +of the definition for some symbols may be significant; the Gnulib +header files take care of that. For example, to use the @code{time_r} gnulib module you should use include header file provided by the gnulib, and so -@samp{#include "time_r.h"}, but you shouldn't explicitely +@samp{#include "time_r.h"}, but you shouldn't explicitly @samp{#include } as it is already done in @file{time_r.h} before the redefinition of some symbols. -@node Importing updated files -@section Importing updated files - -From time to time, you may want to invoke @samp{gnulib-tool --import} -to update the files in your package. Once you have set up your -package for gnulib, this step is quite simple. For example: - -@example -~/src/libfoo$ gnulib-tool --import --source-base gl --m4-base gl/m4 strdup -Module list with included dependencies: - strdup -File list: - lib/strdup.c - lib/strdup.h - m4/onceonly_2_57.m4 - m4/strdup.m4 -Creating ./lib/Makefile.am... -Creating ./m4/gnulib.m4... -Finished. - -Don't forget to add "lib/Makefile" -to AC_CONFIG_FILES in "./configure.ac" and to mention -"lib" in SUBDIRS in some Makefile.am. -~/src/libfoo$ -@end example - -If you don't recall how you invoked the tool last time, the commands -used (and the operations it resulted in) are placed in comments within -the generated @file{Makefile.am} and @file{gnulib.m4}, as in: - -@example -... -# Invoked as: gnulib-tool --import strdup -# Reproduce by: gnulib-tool --import --dir=. --lib=libgnu --source-base=lib --m4-base=m4 --libtool strdup -... -@end example - - -@node Finishing touches -@section Finishing touches - -Invoking @samp{gnulib-tool --import} with the proper parameters (e.g., -@samp{--m4-base gl/m4}) and list of modules (e.g., @samp{strdup -snprintf getline minmax}) can be tedious. To simplify this procedure, -you may put the command line parameters in your @file{configure.ac}. -For example: - -@example -... -AC_PROG_CC -gl_EARLY -... -# For gnulib. -gl_SOURCE_BASE(gl) -gl_M4_BASE(gl/m4) -gl_LIB(libgl) -gl_MODULES(xmalloc progname strdup dummy exit error getpass-gnu getaddrinfo) -gl_AVOID(xalloc-die) -gl_INIT -... -@end example - -This illustrate all macros defined in @file{gnulib.m4}. With the -above, importing new files are as simple as running @samp{gnulib-tool ---import} with no additional parameters. - -The macros @code{gl_EARLY}, @code{gl_INIT}, @code{gl_SOURCE_BASE}, and -@code{gl_M4_BASE} have been discussed earlier. The @code{gl_LIB} -macro can be used if you wish to change the library name (by default -@file{libgnu.a} or @file{libgnu.la} if you use libtool). The -@code{gl_MODULES} macro is used to specify which modules to import. -@code{gl_AVOID} macro is used to specify which modules, that are -normally automatically added as a dependency, to avoid. +@node Modified imports +@section Modified imports + +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. + +The standard way is to modify manually the file @file{gnulib-cache.m4} +in the M4 macros directory, then launch @samp{gnulib-tool --import}. + +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. + +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. + +In the @file{gnulib-cache.m4}, the macros have the following meaning: +@table @code +@item gl_MODULES +The argument is a space separated list of the requested modules, not including +dependencies. + +@item gl_AVOID +The argument is a space separated list of modules that should not be used, +even if they occur as dependencies. Corresponds to the @samp{--avoid} +command line argument. + +@item gl_SOURCE_BASE +The argument is the relative pathname of the directory containing the gnulib +source files (mostly *.c and *.h files). Corresponds to the +@samp{--source-base} command line argument. + +@item gl_M4_BASE +The argument is the relative pathname of the directory containing the gnulib +M4 macros (*.m4 files). Corresponds to the @samp{--m4-base} command line +argument. + +@item gl_TESTS_BASE +The argument is the relative pathname of the directory containing the gnulib +unit test files. Corresponds to the @samp{--tests-base} command line argument. + +@item gl_LIB +The argument is the name of the library to be created. Corresponds to the +@samp{--lib} command line argument. + +@item gl_LGPL +The presence of this macro corresponds to the @samp{--lgpl} command line +argument. It takes no arguments. + +@item gl_LIBTOOL +The presence of this macro corresponds to the @samp{--libtool} command line +argument. It takes no arguments. + +@item gl_MACRO_PREFIX +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 + +@node Simple update +@section Simple update + +When you want to update to a more recent version of Gnulib, without +changing the list of modules or other parameters, a simple call +does it: + +@smallexample +$ gnulib-tool --import +@end smallexample + +This will create, update or remove files, as needed. + +@node CVS Issues +@section CVS Issues + +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 projects which commit all source files, whether generated or not, into +CVS, the @code{gnulib-tool} generated files should all be committed. + +In projects which customarily omit from the CVS all files that generated +from other source files, all these files and directories would not be +added into CVS. The only file that must be added to CVS is +@file{gnulib-cache.m4} in the M4 macros directory. Also, the script for +restoring files not in CVS, customarily called @file{autogen.sh} or +@file{bootstrap.sh}, will typically contain the statement for restoring +the omitted files: + +@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. @node Copying This Manual @appendix Copying This Manual -- 2.30.2