2.1 Initial import

Gnulib assumes your project uses Autoconf and Automake. Invoking `gnulib-tool --import' will copy source files, create a Makefile.am to build them, and generate a gnulib.m4 with Autoconf M4 macro declarations used by configure.ac.

Our example will be a library that uses Autoconf, Automake and Libtool. It calls strdup, and you wish to use gnulib to make the package portable to C89 (which doesn't have strdup).

     ~/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$

By default, the source code is copied into lib/ and the M4 macros in m4/. You can override these paths by using --source-base=DIRECTORY and --m4-base=DIRECTORY, or by adding `gl_SOURCE_BASE(DIRECTORY)' and `gl_M4_BASE(DIRECTORY)' to your configure.ac.

gnulib-tool will overwrite any pre-existing files, in particular Makefile.am. Unfortunately, separating the generated Makefile.am content (for building the gnulib library) into a separate file, say gnulib.mk, that could be included by your handwritten 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., getextize that also copy M4 files into your package. Simon Josefsson successfully uses a source base of gl/, and a M4 base of 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 gnulib.m4. Use the ACLOCAL_AMFLAGS specifier in your top-level Makefile.am file, as in:

     ACLOCAL_AMFLAGS = -I m4

Naturally, replace m4 with the value from --m4-base or gl_M4_BASE. If the M4 base is gl/m4 you would use:

     ACLOCAL_AMFLAGS = -I gl/m4

You are now ready to call the M4 macros in gnulib.m4 from configure.ac. The macro gl_EARLY must be called as soon as possible after verifying that the C compiler is working. Typically, this is immediately after AC_PROG_CC, as in:

     ...
     AC_PROG_CC
     gl_EARLY
     ...

The core part of the gnulib checks are done by the macro 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 gl_SOURCE_BASE. For example:

     ...
     # For gnulib.
     gl_INIT
     ...

You must also make sure that the gnulib library is built. Add the Makefile in the gnulib source base directory to AC_CONFIG_FILES, as in:

     AC_CONFIG_FILES(... lib/Makefile ...)

If your gnulib source base is gl, you would use:

     AC_CONFIG_FILES(... gl/Makefile ...)

You must also make sure that make work in the gnulib directory. Add the gnulib source base directory to a SUBDIRS Makefile.am statement, as in:

     SUBDIRS = lib

or if you, more likely, already have a few entries in SUBDIRS, you can add something like:

     SUBDIRS += lib

If you are using a gnulib source base of gl, you would use:

     SUBDIRS += gl

Finally, you have add C flags and LD flags, so that you can make use of the gnulib library. For example:

     ...
     AM_CPPFLAGS = -I$(top_srcdir)/lib
     ...
     LIBADD = lib/libgnu.la
     ...

Don't forget to #include the various header files. In this example, you would need to make sure that `#include <strdup.h>' is evaluated when compiling all source code files, that want to make use of strdup.