Commit | Line | Data |
---|---|---|
2da09c3f MV |
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 | |
4 | @c Free Software Foundation, Inc. | |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
d928d47f TTN |
7 | @page |
8 | @node Autoconf Support | |
9 | @chapter Autoconf Support | |
10 | ||
92826dd0 LC |
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. | |
d928d47f TTN |
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. | |
a284e708 TTN |
20 | * Autofrisk:: AUTOFRISK_CHECKS and AUTOFRISK_SUMMARY. |
21 | * Using Autofrisk:: Example modules.af files. | |
d928d47f TTN |
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 | |
a3f0622d NJ |
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. | |
d928d47f TTN |
43 | |
44 | ||
45 | @node Autoconf Macros | |
46 | @section Autoconf Macros | |
47 | ||
92826dd0 LC |
48 | @cindex pkg-config |
49 | @cindex autoconf | |
50 | ||
51 | GNU Guile provides a @dfn{pkg-config} description file, installed as | |
cdbbe192 | 52 | @file{@var{prefix}/lib/pkgconfig/guile-1.8.pc}, which contains all the |
92826dd0 LC |
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 | |
cdbbe192 LC |
62 | pkg-config guile-1.8 --cflags |
63 | pkg-config guile-1.8 --libs | |
92826dd0 LC |
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 | |
cdbbe192 | 74 | PKG_CHECK_MODULES([GUILE], [guile-1.8]) |
92826dd0 LC |
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_}. | |
d928d47f TTN |
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 | ||
a284e708 TTN |
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 | ||
d928d47f | 271 | @c autoconf.texi ends here |