[prev in list] [next in list] [prev in thread] [next in thread] 

List:       gnulib-bug
Subject:    [Bug-gnulib] Docs for gnulib-tool --import
From:       Simon Josefsson <jas () extundo ! com>
Date:       2004-09-23 15:56:31
Message-ID: ilu8yb1m11s.fsf () latte ! josefsson ! org
[Download RAW message or body]

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  <jas@extundo.com>

	* 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.
 
+@section Using @samp{gnulib-tool --import} for the first time
+@cindex import
+
+Gnulib assume 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}.
+
+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}).
+
+@example
+~/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$
+@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}.
+
+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:
+
+@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
+@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:
+
+@example
+...
+AC_PROG_CC
+gl_EARLY
+...
+@end example
+
+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:
+
+@example
+...
+# For gnulib.
+gl_INIT
+...
+@end example
+
+You must also make sure that the gnulib library is built.  Add the
+@code{Makefile} in the gnulib source base directory to
+@code{AC_CONFIG_FILES}, as in:
+
+@example
+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:
+
+@example
+SUBDIRS = lib
+@end example
+
+or if you, more likely, already have a few entries in @code{SUBDIRS},
+you can add something like:
+
+@example
+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 add C flags and LD flags, so that you can make use
+of the gnulib library.  For example:
+
+@example
+...
+AM_CPPFLAGS = -I$(top_srcdir)/lib
+...
+LIBADD = lib/libgnu.la
+...
+@end 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}.
+
+@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
+
+@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(getopt progname strdup dummy exit error getpass-gnu getaddrinfo)
+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.
 
 @node Copying This Manual
 @appendix Copying This Manual


[prev in list] [next in list] [prev in thread] [next in thread]