doc/ref/libguile-autoconf.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Guile Reference Manual.
   3 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2011
   4 @c   Free Software Foundation, Inc.
   5 @c See the file guile.texi for copying conditions.
   6
   7 @page
   8 @node Autoconf Support
   9 @section Autoconf Support
  10
  11 Autoconf, a part of the GNU build system, makes it easy for users to
  12 build your package.  This section documents Guile's Autoconf support.
  13
  14 @menu
  15 * Autoconf Background::         Why use autoconf?
  16 * Autoconf Macros::             The GUILE_* macros.
  17 * Using Autoconf Macros::       How to use them, plus examples.
  18 @end menu
  19
  20
  21 @node Autoconf Background
  22 @subsection Autoconf Background
  23
  24 As explained in the @cite{GNU Autoconf Manual}, any package needs
  25 configuration at build-time (@pxref{Top, ,Introduction,autoconf,The GNU
  26 Autoconf Manual}).  If your package uses Guile (or uses a package that
  27 in turn uses Guile), you probably need to know what specific Guile
  28 features are available and details about them.
  29
  30 The way to do this is to write feature tests and arrange for their execution
  31 by the @file{configure} script, typically by adding the tests to
  32 @file{configure.ac}, and running @code{autoconf} to create @file{configure}.
  33 Users of your package then run @file{configure} in the normal way.
  34
  35 Macros are a way to make common feature tests easy to express.
  36 Autoconf provides a wide range of macros
  37 (@pxref{Existing Tests,,,autoconf,The GNU Autoconf Manual}),
  38 and Guile installation provides Guile-specific tests in the areas of:
  39 program detection, compilation flags reporting, and Scheme module
  40 checks.
  41
  42
  43 @node Autoconf Macros
  44 @subsection Autoconf Macros
  45
  46 As mentioned earlier in this chapter, Guile supports parallel
  47 installation, and uses @code{pkg-config} to let the user choose which
  48 version of Guile they are interested in.  @code{pkg-config} has its own
  49 set of Autoconf macros that are probably installed on most every
  50 development system.  The most useful of these macros is
  51 @code{PKG_CHECK_MODULES}.
  52
  53 @findex PKG_CHECK_MODULES
  54
  55 @example
  56 PKG_CHECK_MODULES([GUILE], [guile-@value{EFFECTIVE-VERSION}])
  57 @end example
  58
  59 This example looks for Guile and sets the @code{GUILE_CFLAGS} and
  60 @code{GUILE_LIBS} variables accordingly, or prints an error and exits if
  61 Guile was not found.
  62
  63 Guile comes with additional Autoconf macros providing more information,
  64 installed as @file{@var{prefix}/share/aclocal/guile.m4}.  Their names
  65 all begin with @code{GUILE_}.
  66
  67 @c see Makefile.am
  68 @include autoconf-macros.texi
  69
  70
  71 @node Using Autoconf Macros
  72 @subsection Using Autoconf Macros
  73
  74 Using the autoconf macros is straightforward: Add the macro "calls" (actually
  75 instantiations) to @file{configure.ac}, run @code{aclocal}, and finally,
  76 run @code{autoconf}.  If your system doesn't have guile.m4 installed, place
  77 the desired macro definitions (@code{AC_DEFUN} forms) in @file{acinclude.m4},
  78 and @code{aclocal} will do the right thing.
  79
  80 Some of the macros can be used inside normal shell constructs: @code{if foo ;
  81 then GUILE_BAZ ; fi}, but this is not guaranteed.  It's probably a good idea
  82 to instantiate macros at top-level.
  83
  84 We now include two examples, one simple and one complicated.
  85
  86 The first example is for a package that uses libguile, and thus needs to
  87 know how to compile and link against it.  So we use
  88 @code{PKG_CHECK_MODULES} to set the vars @code{GUILE_CFLAGS} and
  89 @code{GUILE_LIBS}, which are automatically substituted in the Makefile.
  90
  91 @example
  92 In configure.ac:
  93
  94   PKG_CHECK_MODULES([GUILE], [guile-@value{EFFECTIVE-VERSION}])
  95
  96 In Makefile.in:
  97
  98   GUILE_CFLAGS  = @@GUILE_CFLAGS@@
  99   GUILE_LIBS = @@GUILE_LIBS@@
 100
 101   myprog.o: myprog.c
 102           $(CC) -o $@ $(GUILE_CFLAGS) $<
 103   myprog: myprog.o
 104           $(CC) -o $@ $< $(GUILE_LIBS)
 105 @end example
 106
 107 The second example is for a package of Guile Scheme modules that uses an
 108 external program and other Guile Scheme modules (some might call this a "pure
 109 scheme" package).  So we use the @code{GUILE_SITE_DIR} macro, a regular
 110 @code{AC_PATH_PROG} macro, and the @code{GUILE_MODULE_AVAILABLE} macro.
 111
 112 @example
 113 In configure.ac:
 114
 115   GUILE_SITE_DIR
 116
 117   probably_wont_work=""
 118
 119   # pgtype pgtable
 120   GUILE_MODULE_AVAILABLE(have_guile_pg, (database postgres))
 121   test $have_guile_pg = no &&
 122       probably_wont_work="(my pgtype) (my pgtable) $probably_wont_work"
 123
 124   # gpgutils
 125   AC_PATH_PROG(GNUPG,gpg)
 126   test x"$GNUPG" = x &&
 127       probably_wont_work="(my gpgutils) $probably_wont_work"
 128
 129   if test ! "$probably_wont_work" = "" ; then
 130       p="         ***"
 131       echo
 132       echo "$p"
 133       echo "$p NOTE:"
 134       echo "$p The following modules probably won't work:"
 135       echo "$p   $probably_wont_work"
 136       echo "$p They can be installed anyway, and will work if their"
 137       echo "$p dependencies are installed later.  Please see README."
 138       echo "$p"
 139       echo
 140   fi
 141
 142 In Makefile.in:
 143
 144   instdir = @@GUILE_SITE@@/my
 145
 146   install:
 147         $(INSTALL) my/*.scm $(instdir)
 148 @end example
 149
 150
 151 @c autoconf.texi ends here