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