[Bug-gnulib] Docs for gnulib-tool --import

[Simon Josefsson]

Hopefully a native speaker can produce something legible based on the
notes below..  Feedback from someone who try to use it would be
useful, as well.

The manual bootstrapping steps could be automated, I guess, perhaps
toggled by an --update parameter.  Something for a rainy ... oh, well,
rainier, day.

2004-09-23  Simon Josefsson  <address@hidden>

        * gnulib.texi (Invoking gnulib-tool): Add.

Index: gnulib.texi
===================================================================
RCS file: /cvsroot/gnulib/gnulib/doc/gnulib.texi,v
retrieving revision 1.1
diff -u -p -u -w -r1.1 gnulib.texi
--- gnulib.texi 19 Sep 2004 13:17:06 -0000      1.1
+++ gnulib.texi 23 Sep 2004 15:50:16 -0000
@@ -186,6 +186,218 @@ fail.
 Run @samp{gnulib-tool --help}, and use the source.
 @command{gnulib-tool} is the way to import Gnulib modules.
 
address@hidden Using @samp{gnulib-tool --import} for the first time
address@hidden import
+
+Gnulib assume your project uses Autoconf and Automake.  Invoking
address@hidden --import} will copy source files, create a
address@hidden to build them, and generate a @file{gnulib.m4} with
+Autoconf M4 macro declarations used by @file{configure.ac}.
+
+Our example will be a library that uses Autoconf, Automake and
+Libtool.  It calls @code{strdup}, and you wish to use gnulib to make
+the package portable C89 (which doesn'tr have @code{strdup}).
+
address@hidden
+~/src/libfoo$ gnulib-tool --import 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$
address@hidden 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
address@hidden and @code{--m4-base=DIRECTORY}, or by
+adding @samp{gl_SOURCE_BASE(DIRECTORY)} and
address@hidden(DIRECTORY)} to your @file{configure.ac}.
+
+Note that @code{gnulib-tool} will overwrite any pre-existing files, in
+particular @file{Makefile.am}.  Unfortunately, separating the
+generated @file{Makefile.am} content (for building the gnulib library)
+into a separate file, e.g., @file{gnulib.mk}, that could be included
+by your hand written @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
+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
+M4 files into your package.  Simon Josefsson successfully use a source
+base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
+packages.
+
+A few manual steps are required to finish the initial import.
+
+First, you need to make sure Autoconf can find the macro definitions
+in @file{gnulib.m4}.  Use the @code{ACLOCAL_AMFLAGS} specifier in your
+top-level @file{Makefile.am} file, as in:
+
address@hidden
+ACLOCAL_AMFLAGS = -I m4
address@hidden example
+
+Naturally, replace @file{m4} with the value from @code{--m4-base} or
address@hidden  If the M4 base is @file{gl/m4} you would use:
+
address@hidden
+ACLOCAL_AMFLAGS = -I gl/m4
address@hidden example
+
+You are now ready to call the M4 macros in @code{gnulib.m4} from
address@hidden  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:
+
address@hidden
+...
+AC_PROG_CC
+gl_EARLY
+...
address@hidden example
+
+The core part of the gnulib checks are done by the macro
address@hidden  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:
+
address@hidden
+...
+# For gnulib.
+gl_INIT
+...
address@hidden example
+
+You must also make sure that the gnulib library is built.  Add the
address@hidden in the gnulib source base directory to
address@hidden, as in:
+
address@hidden
+AC_CONFIG_FILES(... lib/Makefile ...)
address@hidden example
+
+If your gnulib source base is @file{gl}, you would use:
+
address@hidden
+AC_CONFIG_FILES(... gl/Makefile ...)
address@hidden 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:
+
address@hidden
+SUBDIRS = lib
address@hidden example
+
+or if you, more likely, already have a few entries in @code{SUBDIRS},
+you can add something like:
+
address@hidden
+SUBDIRS += lib
address@hidden example
+
+If you are using a gnulib source base of @code{gl}, you would use:
+
address@hidden
+SUBDIRS += gl
address@hidden example
+
+Finally, you have add C flags and LD flags, so that you can make use
+of the gnulib library.  For example:
+
address@hidden
+...
+AM_CPPFLAGS = -I$(top_srcdir)/lib
+...
+LIBADD = lib/libgnu.la
+...
address@hidden example
+
+Don't forget to @code{#include} the various header files.  In this
+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}.
+
address@hidden 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:
+
address@hidden
+~/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$
address@hidden 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:
+
address@hidden
+...
+# Invoked as: gnulib-tool --import strdup
+# Reproduce by: gnulib-tool --import --dir=. --lib=libgnu --source-base=lib 
--m4-base=m4 --libtool strdup
+...
address@hidden example
+
address@hidden Finishing touches
+
+Invoking @samp{gnulib-tool --import} with the proper parameters (e.g.,
address@hidden 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:
+
address@hidden
+...
+AC_PROG_CC
+gl_EARLY
+...
+# For gnulib.
+gl_SOURCE_BASE(gl)
+gl_M4_BASE(gl/m4)
+gl_LIB(libgl)
+gl_MODULES(getopt progname strdup dummy exit error getpass-gnu getaddrinfo)
+gl_INIT
+...
address@hidden 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
address@hidden have been discussed earlier.  The @code{gl_LIB}
+macro can be used if you wish to change the library name (by default
address@hidden or @file{libgnu.la} if you use libtool).  The
address@hidden macro is used to specify which modules to import.
 
 @node Copying This Manual
 @appendix Copying This Manual