-@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.
projects / pspp / commitdiff