diff options
Diffstat (limited to 'doc/ref/autoconf.texi')
-rw-r--r-- | doc/ref/autoconf.texi | 234 |
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 |