Autoconf Support
================

Autoconf, a part of the GNU build system, makes it easy for users to build your package.  This section documents Guile's Autoconf support.

Autoconf Background
-------------------

As explained in the GNU Autoconf Manual, any package needs configuration at build-time (see Introduction (The GNU Autoconf Manual)).  If your package uses Guile (or uses a package that in turn uses Guile), you probably need to know what specific Guile features are available and details about them.

The way to do this is to write feature tests and arrange for their execution by the configure script, typically by adding the tests to configure.ac, and running autoconf to create configure. Users of your package then run configure in the normal way.

Macros are a way to make common feature tests easy to express. Autoconf provides a wide range of macros (see Existing Tests (The GNU Autoconf Manual)), and Guile installation provides Guile-specific tests in the areas of: program detection, compilation flags reporting, and Scheme module checks.

Autoconf Macros
---------------

As mentioned earlier in this chapter, Guile supports parallel installation, and uses pkg-config to let the user choose which version of Guile they are interested in.  pkg-config has its own set of Autoconf macros that are probably installed on most every development system.  The most useful of these macros is PKG_CHECK_MODULES.

     PKG_CHECK_MODULES([GUILE], [guile-EFFECTIVE-VERSION])

This example looks for Guile and sets the GUILE_CFLAGS and GUILE_LIBS variables accordingly, or prints an error and exits if Guile was not found.

Guile comes with additional Autoconf macros providing more information, installed as PREFIX/share/aclocal/guile.m4.  Their names all begin with GUILE_.

     [file autoconf-macros.texi not included]

Using Autoconf Macros
---------------------

Using the autoconf macros is straightforward: Add the macro "calls" (actually instantiations) to configure.ac, run aclocal, and finally, run autoconf.  If your system doesn't have guile.m4 installed, place the desired macro definitions (AC_DEFUN forms) in acinclude.m4, and aclocal will do the right thing.

Some of the macros can be used inside normal shell constructs: if foo ; then GUILE_BAZ ; fi, but this is not guaranteed.  It's probably a good idea to instantiate macros at top-level.

We now include two examples, one simple and one complicated.

The first example is for a package that uses libguile, and thus needs to know how to compile and link against it.  So we use PKG_CHECK_MODULES to set the vars GUILE_CFLAGS and GUILE_LIBS, which are automatically substituted in the Makefile.

     In configure.ac:

       PKG_CHECK_MODULES([GUILE], [guile-EFFECTIVE-VERSION])

     In Makefile.in:

       GUILE_CFLAGS  = @GUILE_CFLAGS@
       GUILE_LIBS = @GUILE_LIBS@

       myprog.o: myprog.c
               $(CC) -o $ $(GUILE_CFLAGS) $<
       myprog: myprog.o
               $(CC) -o $ $< $(GUILE_LIBS)

The second example is for a package of Guile Scheme modules that uses an external program and other Guile Scheme modules (some might call this a "pure scheme" package).  So we use the GUILE_SITE_DIR macro, a regular AC_PATH_PROG macro, and the GUILE_MODULE_AVAILABLE macro.

     In configure.ac:

       GUILE_SITE_DIR

       probably_wont_work=""

       # pgtype pgtable
       GUILE_MODULE_AVAILABLE(have_guile_pg, (database postgres))
       test $have_guile_pg = no &&
           probably_wont_work="(my pgtype) (my pgtable) $probably_wont_work"

       # gpgutils
       AC_PATH_PROG(GNUPG,gpg)
       test x"$GNUPG" = x &&
           probably_wont_work="(my gpgutils) $probably_wont_work"

       if test ! "$probably_wont_work" = "" ; then
           p="         ***"
           echo
           echo "$p"
           echo "$p NOTE:"
           echo "$p The following modules probably won't work:"
           echo "$p   $probably_wont_work"
           echo "$p They can be installed anyway, and will work if their"
           echo "$p dependencies are installed later.  Please see README."
           echo "$p"
           echo
       fi

     In Makefile.in:

       instdir = @GUILE_SITE@/my

       install:
             $(INSTALL) my/*.scm $(instdir)