doc/ref/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
   4 @c   Free Software Foundation, Inc.
   5 @c See the file guile.texi for copying conditions.
   6
   7 @page
   8 @node Autoconf Support
   9 @chapter Autoconf Support
  10
  11 When Guile is installed, a pkg-config description file and a set of
  12 Autoconf macros is installed.  This chapter documents pkg-config and
  13 Autoconf support, as well as the high-level guile-tool Autofrisk.
  14 @xref{Top,The GNU Autoconf Manual,,autoconf}, for more info.
  15
  16 @menu
  17 * Autoconf Background::         Why use autoconf?
  18 * Autoconf Macros::             The GUILE_* macros.
  19 * Using Autoconf Macros::       How to use them, plus examples.
  20 * Autofrisk::                   AUTOFRISK_CHECKS and AUTOFRISK_SUMMARY.
  21 * Using Autofrisk::             Example modules.af files.
  22 @end menu
  23
  24
  25 @node Autoconf Background
  26 @section Autoconf Background
  27
  28 As explained elsewhere (@pxref{Top,The GNU Autoconf Manual,,autoconf}), any
  29 package needs configuration at build-time.  If your package uses Guile (or
  30 uses a package that in turn uses Guile), you probably need to know what
  31 specific Guile features are available and details about them.
  32
  33 The way to do this is to write feature tests and arrange for their execution
  34 by the @file{configure} script, typically by adding the tests to
  35 @file{configure.ac}, and running @code{autoconf} to create @file{configure}.
  36 Users of your package then run @file{configure} in the normal way.
  37
  38 Macros are a way to make common feature tests easy to express.  Autoconf
  39 provides a wide range of macros (@pxref{Existing Tests,,,autoconf}), and
  40 Guile installation provides Guile-specific tests in the areas of:
  41 program detection, compilation flags reporting, and Scheme module
  42 checks.
  43
  44
  45 @node Autoconf Macros
  46 @section Autoconf Macros
  47
  48 @cindex pkg-config
  49 @cindex autoconf
  50
  51 GNU Guile provides a @dfn{pkg-config} description file, installed as
  52 @file{@var{prefix}/lib/pkgconfig/guile-2.0.pc}, which contains all the
  53 information necessary to compile and link C applications that use Guile.
  54 The @code{pkg-config} program is able to read this file and provide this
  55 information to application programmers; it can be obtained at
  56 @url{http://pkg-config.freedesktop.org/}.
  57
  58 The following command lines give respectively the C compilation and link
  59 flags needed to build Guile-using programs:
  60
  61 @example
  62 pkg-config guile-2.0 --cflags
  63 pkg-config guile-2.0 --libs
  64 @end example
  65
  66 To ease use of pkg-config with Autoconf, pkg-config comes with a
  67 convenient Autoconf macro.  The following example looks for Guile and
  68 sets the @code{GUILE_CFLAGS} and @code{GUILE_LIBS} variables
  69 accordingly, or prints an error and exits if Guile was not found:
  70
  71 @findex PKG_CHECK_MODULES
  72
  73 @example
  74 PKG_CHECK_MODULES([GUILE], [guile-2.0])
  75 @end example
  76
  77 Guile comes with additional Autoconf macros providing more information,
  78 installed as @file{@var{prefix}/share/aclocal/guile.m4}.  Their names
  79 all begin with @code{GUILE_}.
  80
  81 @c see Makefile.am
  82 @include autoconf-macros.texi
  83
  84
  85 @node Using Autoconf Macros
  86 @section Using Autoconf Macros
  87
  88 Using the autoconf macros is straightforward: Add the macro "calls" (actually
  89 instantiations) to @file{configure.ac}, run @code{aclocal}, and finally,
  90 run @code{autoconf}.  If your system doesn't have guile.m4 installed, place
  91 the desired macro definitions (@code{AC_DEFUN} forms) in @file{acinclude.m4},
  92 and @code{aclocal} will do the right thing.
  93
  94 Some of the macros can be used inside normal shell constructs: @code{if foo ;
  95 then GUILE_BAZ ; fi}, but this is not guaranteed.  It's probably a good idea
  96 to instantiate macros at top-level.
  97
  98 We now include two examples, one simple and one complicated.
  99
 100 The first example is for a package that uses libguile, and thus needs to know
 101 how to compile and link against it.  So we use @code{GUILE_FLAGS} to set the
 102 vars @code{GUILE_CFLAGS} and @code{GUILE_LDFLAGS}, which are automatically
 103 substituted in the Makefile.
 104
 105 @example
 106 In configure.ac:
 107
 108   GUILE_FLAGS
 109
 110 In Makefile.in:
 111
 112   GUILE_CFLAGS  = @@GUILE_CFLAGS@@
 113   GUILE_LDFLAGS = @@GUILE_LDFLAGS@@
 114
 115   myprog.o: myprog.c
 116           $(CC) -o $@ $(GUILE_CFLAGS) $<
 117   myprog: myprog.o
 118           $(CC) -o $@ $< $(GUILE_LDFLAGS)
 119 @end example
 120
 121 The second example is for a package of Guile Scheme modules that uses an
 122 external program and other Guile Scheme modules (some might call this a "pure
 123 scheme" package).  So we use the @code{GUILE_SITE_DIR} macro, a regular
 124 @code{AC_PATH_PROG} macro, and the @code{GUILE_MODULE_AVAILABLE} macro.
 125
 126 @example
 127 In configure.ac:
 128
 129   GUILE_SITE_DIR
 130
 131   probably_wont_work=""
 132
 133   # pgtype pgtable
 134   GUILE_MODULE_AVAILABLE(have_guile_pg, (database postgres))
 135   test $have_guile_pg = no &&
 136       probably_wont_work="(my pgtype) (my pgtable) $probably_wont_work"
 137
 138   # gpgutils
 139   AC_PATH_PROG(GNUPG,gpg)
 140   test x"$GNUPG" = x &&
 141       probably_wont_work="(my gpgutils) $probably_wont_work"
 142
 143   if test ! "$probably_wont_work" = "" ; then
 144       p="         ***"
 145       echo
 146       echo "$p"
 147       echo "$p NOTE:"
 148       echo "$p The following modules probably won't work:"
 149       echo "$p   $probably_wont_work"
 150       echo "$p They can be installed anyway, and will work if their"
 151       echo "$p dependencies are installed later.  Please see README."
 152       echo "$p"
 153       echo
 154   fi
 155
 156 In Makefile.in:
 157
 158   instdir = @@GUILE_SITE@@/my
 159
 160   install:
 161         $(INSTALL) my/*.scm $(instdir)
 162 @end example
 163
 164
 165 @node Autofrisk
 166 @section Autofrisk
 167
 168 The @dfn{guile-tools autofrisk} command looks for the file @file{modules.af}
 169 in the current directory and writes out @file{modules.af.m4} containing
 170 autoconf definitions for @code{AUTOFRISK_CHECKS} and @code{AUTOFRISK_SUMMARY}.
 171 @xref{Autoconf Background}, and @xref{Using Autoconf Macros}, for more info.
 172
 173 The modules.af file consists of a series of configuration forms (Scheme
 174 lists), which have one of the following formats:
 175
 176 @example
 177   (files-glob PATTERN ...)                      ;; required
 178   (non-critical-external MODULE ...)            ;; optional
 179   (non-critical-internal MODULE ...)            ;; optional
 180   (programs (MODULE PROG ...) ...)              ;; optional
 181   (pww-varname VARNAME)                         ;; optional
 182 @end example
 183
 184 @var{pattern} is a string that may contain "*" and "?" characters to be
 185 expanded into filenames.  @var{module} is a list of symbols naming a module,
 186 such as `(srfi srfi-1)'.  @var{varname} is a shell-safe name to use instead of
 187 @code{probably_wont_work}, the default.  This var is passed to `AC_SUBST'.
 188 @var{prog} is a string that names a program, such as "gpg".
 189
 190 Autofrisk expands the @code{files-glob} pattern(s) into a list of files, scans
 191 each file's module definition form(s), and constructs a module dependency
 192 graph wherein modules defined by @code{define-module} are considered
 193 @dfn{internal} and the remaining, @dfn{external}.  For each external module
 194 that has an internal dependency, Autofrisk emits a
 195 @code{GUILE_MODULE_REQUIRED} check (@pxref{Autoconf Macros}), which altogether
 196 form the body of @code{AUTOFRISK_CHECKS}.
 197
 198 @code{GUILE_MODULE_REQUIRED} causes the @file{configure} script to exit with
 199 an error message if the specified module is not available; it enforces a
 200 strong dependency.  You can temper dependency strength by using the
 201 @code{non-critical-external} and @code{non-critical-internal} configuration
 202 forms in modules.af.  For graph edges that touch such non-critical modules,
 203 Autofrisk uses @code{GUILE_MODULE_AVAILABLE}, and arranges for
 204 @code{AUTOFRISK_SUMMARY} to display a warning if they are not found.
 205
 206 The shell code resulting from the expansion of @code{AUTOFRISK_CHECKS} and
 207 @code{AUTOFRISK_SUMMARY} uses the shell variable @code{probably_wont_work} to
 208 collect the names of unfound non-critical modules.  If this bothers you, use
 209 configuration form @code{(pww-name foo)} in modules.af.
 210
 211 Although Autofrisk does not detect when a module uses a program (for example,
 212 in a @code{system} call), it can generate @code{AC_PATH_PROG} forms anyway if
 213 you use the @code{programs} configuration form in modules.af.  These are
 214 collected into @code{AUTOCONF_CHECKS}.
 215
 216 @xref{Using Autofrisk}, for some modules.af examples.
 217
 218
 219 @node Using Autofrisk
 220 @section Using Autofrisk
 221
 222 Using Autofrisk (@pxref{Autofrisk}) involves writing @file{modules.af} and
 223 adding two macro calls to @file{configure.in}.  Here is an example of the
 224 latter:
 225
 226 @example
 227 AUTOFRISK_CHECKS
 228 AUTOFRISK_SUMMARY
 229 @end example
 230
 231 Here is an adaptation of the second "GUILE_*" example (@pxref{Using Autoconf
 232 Macros}) that does basically the same thing.
 233
 234 @example
 235 (files-glob "my/*.scm")
 236 (non-critical-external (database postgres))
 237 (programs ((my gpgutils) "gpg"))        ;; (my gpgutils) uses "gpg"
 238 @end example
 239
 240 If the SRFI modules (@pxref{SRFI Support}) were a separate package, we could
 241 use @code{guile-tools frisk} to find out its dependencies:
 242
 243 @example
 244 $ guile-tools frisk srfi/*.scm
 245 13 files, 18 modules (13 internal, 5 external), 9 edges
 246
 247 x (ice-9 and-let-star)
 248                          regular        (srfi srfi-2)
 249 x (ice-9 syncase)
 250                          regular        (srfi srfi-11)
 251 x (ice-9 rdelim)
 252                          regular        (srfi srfi-10)
 253 x (ice-9 receive)
 254                          regular        (srfi srfi-8)
 255                          regular        (srfi srfi-1)
 256 x (ice-9 session)
 257                          regular        (srfi srfi-1)
 258 @end example
 259
 260 Then, we could use the following modules.af to help configure it:
 261
 262 @example
 263 (files-glob "srfi/*.scm")
 264 (non-critical-external          ;; relatively recent
 265   (ice-9 rdelim)
 266   (ice-9 receive)
 267   (ice-9 and-let-star))
 268 (pww-varname not_fully_supported)
 269 @end example
 270
 271 @c autoconf.texi ends here