changeset 6251:9acbfeda43d3

Major update of the "Invoking gnulib-tool" chapter.
author Bruno Haible <bruno@clisp.org>
date Mon, 19 Sep 2005 15:38:33 +0000
parents 2c772fe1e1d0
children 038c6bc7d60a
files doc/ChangeLog doc/gnulib.texi
diffstat 2 files changed, 179 insertions(+), 122 deletions(-) [+]
line wrap: on
line diff
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2005-09-18  Bruno Haible  <bruno@clisp.org>
+
+	* gnulib.texi (Invoking gnulib-tool): 50% rewritten.
+
 2005-08-11  Simon Josefsson  <jas@extundo.com>
 
 	* gnulib.texi (Initial import, Finishing touches): Mention
--- 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 @@
 @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 @@
 
 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 @@
   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 @@
 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 @@
 
 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 @@
 
 @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 @@
 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 @@
 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 @@
 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 <time.h>} as it is already done in @file{time_r.h}
 before the redefinition of some symbols.
 
-@node Importing updated files
-@section Importing updated files
+@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.
 
-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:
+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.
 
-@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.
+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.
 
-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
+@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.
 
-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:
+@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.
 
-@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
+@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.
 
-@node Finishing touches
-@section Finishing touches
+@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.
 
-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:
+@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
 
-@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 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.
 
-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.
+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:
 
-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.
+@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