summaryrefslogtreecommitdiff
path: root/doc/ref/autoconf.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ref/autoconf.texi')
-rw-r--r--doc/ref/autoconf.texi234
1 files changed, 0 insertions, 234 deletions
diff --git a/doc/ref/autoconf.texi b/doc/ref/autoconf.texi
deleted file mode 100644
index 8d05b2ecc..000000000
--- a/doc/ref/autoconf.texi
+++ /dev/null
@@ -1,234 +0,0 @@
-@page
-@node Autoconf Support
-@chapter Autoconf Support
-
-When Guile is installed, a set of autoconf macros is also installed as
-PREFIX/share/aclocal/guile.m4. This chapter documents the macros provided in
-that file, as well as the high-level guile-tool Autofrisk. @xref{Top,The GNU
-Autoconf Manual,,autoconf}, for more info.
-
-@menu
-* Autoconf Background:: Why use autoconf?
-* Autoconf Macros:: The GUILE_* macros.
-* Using Autoconf Macros:: How to use them, plus examples.
-* Autofrisk:: AUTOFRISK_CHECKS and AUTOFRISK_SUMMARY.
-* Using Autofrisk:: Example modules.af files.
-@end menu
-
-
-@node Autoconf Background
-@section Autoconf Background
-
-As explained elsewhere (@pxref{Top,The GNU Autoconf Manual,,autoconf}), any
-package needs configuration at build-time. 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 @file{configure} script, typically by adding the tests to
-@file{configure.ac}, and running @code{autoconf} to create @file{configure}.
-Users of your package then run @file{configure} in the normal way.
-
-Macros are a way to make common feature tests easy to express. Autoconf
-provides a wide range of macros (@pxref{Existing Tests,,,autoconf}), and
-Guile installation provides Guile-specific tests in the areas of:
-program detection, compilation flags reporting, and Scheme module
-checks.
-
-
-@node Autoconf Macros
-@section Autoconf Macros
-
-The macro names all begin with "GUILE_".
-
-@c see Makefile.am
-@include autoconf-macros.texi
-
-
-@node Using Autoconf Macros
-@section Using Autoconf Macros
-
-Using the autoconf macros is straightforward: Add the macro "calls" (actually
-instantiations) to @file{configure.ac}, run @code{aclocal}, and finally,
-run @code{autoconf}. If your system doesn't have guile.m4 installed, place
-the desired macro definitions (@code{AC_DEFUN} forms) in @file{acinclude.m4},
-and @code{aclocal} will do the right thing.
-
-Some of the macros can be used inside normal shell constructs: @code{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 @code{GUILE_FLAGS} to set the
-vars @code{GUILE_CFLAGS} and @code{GUILE_LDFLAGS}, which are automatically
-substituted in the Makefile.
-
-@example
-In configure.ac:
-
- GUILE_FLAGS
-
-In Makefile.in:
-
- GUILE_CFLAGS = @@GUILE_CFLAGS@@
- GUILE_LDFLAGS = @@GUILE_LDFLAGS@@
-
- myprog.o: myprog.c
- $(CC) -o $@ $(GUILE_CFLAGS) $<
- myprog: myprog.o
- $(CC) -o $@ $< $(GUILE_LDFLAGS)
-@end example
-
-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 @code{GUILE_SITE_DIR} macro, a regular
-@code{AC_PATH_PROG} macro, and the @code{GUILE_MODULE_AVAILABLE} macro.
-
-@example
-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)
-@end example
-
-
-@node Autofrisk
-@section Autofrisk
-
-The @dfn{guile-tools autofrisk} command looks for the file @file{modules.af}
-in the current directory and writes out @file{modules.af.m4} containing
-autoconf definitions for @code{AUTOFRISK_CHECKS} and @code{AUTOFRISK_SUMMARY}.
-@xref{Autoconf Background}, and @xref{Using Autoconf Macros}, for more info.
-
-The modules.af file consists of a series of configuration forms (Scheme
-lists), which have one of the following formats:
-
-@example
- (files-glob PATTERN ...) ;; required
- (non-critical-external MODULE ...) ;; optional
- (non-critical-internal MODULE ...) ;; optional
- (programs (MODULE PROG ...) ...) ;; optional
- (pww-varname VARNAME) ;; optional
-@end example
-
-@var{pattern} is a string that may contain "*" and "?" characters to be
-expanded into filenames. @var{module} is a list of symbols naming a module,
-such as `(srfi srfi-1)'. @var{varname} is a shell-safe name to use instead of
-@code{probably_wont_work}, the default. This var is passed to `AC_SUBST'.
-@var{prog} is a string that names a program, such as "gpg".
-
-Autofrisk expands the @code{files-glob} pattern(s) into a list of files, scans
-each file's module definition form(s), and constructs a module dependency
-graph wherein modules defined by @code{define-module} are considered
-@dfn{internal} and the remaining, @dfn{external}. For each external module
-that has an internal dependency, Autofrisk emits a
-@code{GUILE_MODULE_REQUIRED} check (@pxref{Autoconf Macros}), which altogether
-form the body of @code{AUTOFRISK_CHECKS}.
-
-@code{GUILE_MODULE_REQUIRED} causes the @file{configure} script to exit with
-an error message if the specified module is not available; it enforces a
-strong dependency. You can temper dependency strength by using the
-@code{non-critical-external} and @code{non-critical-internal} configuration
-forms in modules.af. For graph edges that touch such non-critical modules,
-Autofrisk uses @code{GUILE_MODULE_AVAILABLE}, and arranges for
-@code{AUTOFRISK_SUMMARY} to display a warning if they are not found.
-
-The shell code resulting from the expansion of @code{AUTOFRISK_CHECKS} and
-@code{AUTOFRISK_SUMMARY} uses the shell variable @code{probably_wont_work} to
-collect the names of unfound non-critical modules. If this bothers you, use
-configuration form @code{(pww-name foo)} in modules.af.
-
-Although Autofrisk does not detect when a module uses a program (for example,
-in a @code{system} call), it can generate @code{AC_PATH_PROG} forms anyway if
-you use the @code{programs} configuration form in modules.af. These are
-collected into @code{AUTOCONF_CHECKS}.
-
-@xref{Using Autofrisk}, for some modules.af examples.
-
-
-@node Using Autofrisk
-@section Using Autofrisk
-
-Using Autofrisk (@pxref{Autofrisk}) involves writing @file{modules.af} and
-adding two macro calls to @file{configure.in}. Here is an example of the
-latter:
-
-@example
-AUTOFRISK_CHECKS
-AUTOFRISK_SUMMARY
-@end example
-
-Here is an adaptation of the second "GUILE_*" example (@pxref{Using Autoconf
-Macros}) that does basically the same thing.
-
-@example
-(files-glob "my/*.scm")
-(non-critical-external (database postgres))
-(programs ((my gpgutils) "gpg")) ;; (my gpgutils) uses "gpg"
-@end example
-
-If the SRFI modules (@pxref{SRFI Support}) were a separate package, we could
-use @code{guile-tools frisk} to find out its dependencies:
-
-@example
-$ guile-tools frisk srfi/*.scm
-13 files, 18 modules (13 internal, 5 external), 9 edges
-
-x (ice-9 and-let-star)
- regular (srfi srfi-2)
-x (ice-9 syncase)
- regular (srfi srfi-11)
-x (ice-9 rdelim)
- regular (srfi srfi-10)
-x (ice-9 receive)
- regular (srfi srfi-8)
- regular (srfi srfi-1)
-x (ice-9 session)
- regular (srfi srfi-1)
-@end example
-
-Then, we could use the following modules.af to help configure it:
-
-@example
-(files-glob "srfi/*.scm")
-(non-critical-external ;; relatively recent
- (ice-9 rdelim)
- (ice-9 receive)
- (ice-9 and-let-star))
-(pww-varname not_fully_supported)
-@end example
-
-@c autoconf.texi ends here