1 This is version 2.0 of Guile, Project GNU's extension language library.
2 Guile is an implementation of the Scheme programming language, packaged
3 as a library that can be linked into applications to give them their own
4 extension language. Guile supports other languages as well, giving
5 users of Guile-based applications a choice of languages.
7 Please send bug reports to bug-guile@gnu.org.
9 See the LICENSE file for the specific terms that apply to Guile. Note
10 that for any copyright year range specified as YYYY-ZZZZ in this
11 package, the range specifies every single year in that closed interval.
14 Additional INSTALL instructions ===========================================
16 Generic instructions for configuring and compiling Guile can be found
17 in the INSTALL file. Guile specific information and configure options
18 can be found below, including instructions for installing SLIB.
20 Guile depends on the following external libraries.
28 It will also use the libreadline library if it is available.
30 There is a corresponding `--with-XXX-prefix' option for each of these
31 libraries (except for libgc and libffi which use `pkg-config', see
32 below) that you can use when invoking ./configure, if you have these
33 libraries installed in a location other than the standard places (/usr
36 These options are provided by the Gnulib `havelib' module, and details
37 of how they work are documented in `Searching for Libraries' in the
38 Gnulib manual (http://www.gnu.org/software/gnulib/manual). The extent
39 to which they work on a given OS depends on whether that OS supports
40 encoding full library path names in executables (aka `rpath'). Also
41 note that using these options, and hence hardcoding full library path
42 names (where that is supported), makes it impossible to later move the
43 built executables and libraries to an installation location other than
44 the one that was specified at build time.
46 Another possible approach is to set CPPFLAGS and LDFLAGS on the
47 configure command-line, so that they include -I options for all the
48 non-standard places where you have installed header files and -L
49 options for all the non-standard places where you have installed
50 libraries. This will allow configure and make to find those headers
51 and libraries during the build. E.g.:
53 ../configure [...] CPPFLAGS='-I/my/include' LDFLAGS='-L/my/lib'
55 The locations found will not be hardcoded into the build executables and
56 libraries, so with this approach you will probably also need to set
57 LD_LIBRARY_PATH correspondingly, to allow Guile to find the necessary
58 libraries again at runtime.
61 Required External Packages ================================================
63 Guile requires the following external packages:
65 - GNU MP, at least version 4.2
67 GNU MP is used for bignum arithmetic. It is available from
70 - libltdl from GNU Libtool, at least version 1.5.6
72 libltdl is used for loading extensions at run-time. It is
73 available from http://www.gnu.org/software/libtool/ .
75 - GNU libunistring, at least version 0.9.3
77 libunistring is used for Unicode string operations, such as the
78 `utf*->string' procedures. It is available from
79 http://www.gnu.org/software/libunistring/ .
81 - libgc, at least version 7.0
83 libgc (aka. the Boehm-Demers-Weiser garbage collector) is the
84 conservative garbage collector used by Guile. It is available
85 from http://www.hboehm.info/gc/ .
89 libffi provides a "foreign function interface", used by the
90 `(system foreign)' module. It is available from
91 http://sourceware.org/libffi/ .
95 Guile's ./configure script uses pkg-config to discover the correct
96 compile and link options for libgc and libffi. For this to work,
97 the `PKG_CONFIG_PATH' environment variable must be set to point to
98 the places where libgc's and libffi's `.pc' files can be found:
100 PKG_CONFIG_PATH=/path/to/libgc/lib/pkgconfig:/path/to/libffi/lib/pkgconfig
102 Alternatively, when pkg-config is not installed, you can work around
103 this by setting some variables as part of the configure
108 - BDW_GC_CFLAGS=<compile flags for picking up libgc headers>
110 - BDW_GC_LIBS=<linker flags for picking up the libgc library>
112 Note that because you're bypassing all pkg-config checks, you will
113 also have to specify libffi flags as well:
115 - LIBFFI_CFLAGS=<compile flags for picking up libffi headers>
117 - LIBFFI_LIBS=<linker flags for picking up the libffi library>
120 Special Instructions For Some Systems =====================================
122 We would like Guile to build on all systems using the simple
123 instructions above, but it seems that a few systems still need special
124 treatment. If you can send us fixes for these problems, we'd be
129 Guile specific flags Accepted by Configure =================================
131 If you run the configure script with no arguments, it should examine
132 your system and set things up appropriately. However, there are a few
133 switches specific to Guile you may find useful in some circumstances.
135 --without-threads --- Build without thread support
137 Build a Guile executable and library that supports multi-threading.
139 The default is to enable threading support when your operating
140 system offsers 'POSIX threads'. When you do not want threading, use
143 --enable-deprecated=LEVEL
145 Guile may contain features that are `deprecated'. When a feature is
146 deprecated, it means that it is still there, but that there is a
147 better way of achieving the same thing, and we'd rather have you use
148 this better way. This allows us to eventually remove the old
149 implementation and helps to keep Guile reasonably clean of historic
152 See the file NEWS for a list of features that are currently
153 deprecated. Each entry will also tell you what you should replace
156 To give you some help with this process, and to encourage (OK,
157 nudge) people to switch to the newer methods, Guile can emit
158 warnings or errors when you use a deprecated feature. There is
159 quite a range of possibilities, from being completely silent to
160 giving errors at link time. What exactly happens is determined both
161 by the value of the `--enable-deprecated' configuration option when
162 Guile was built, and by the GUILE_WARN_DEPRECATED environment
167 When Guile has been configured with `--enable-deprecated=no' (or,
168 equivalently, with `--disable-deprecated') then all deprecated
169 features are omitted from Guile. You will get "undefined
170 reference", "variable unbound" or similar errors when you try to
173 When `--enable-deprecated=LEVEL' has been specified (for LEVEL not
174 "no"), LEVEL will be used as the default value of the environment
175 variable GUILE_WARN_DEPRECATED. A value of "yes" is changed to
176 "summary" and "shutup" is changed to "no", however.
178 When GUILE_WARN_DEPRECATED has the value "no", nothing special
179 will happen when a deprecated feature is used.
181 When GUILE_WARN_DEPRECATED has the value "summary", and a
182 deprecated feature has been used, Guile will print this message at
185 Some deprecated features have been used. Set the environment
186 variable GUILE_WARN_DEPRECATED to "detailed" and rerun the
187 program to get more information. Set it to "no" to suppress
190 When GUILE_WARN_DEPRECATED has the value "detailed", a detailed
191 warning is emitted immediatly for the first use of a deprecated
194 The default is `--enable-deprecated=yes'.
196 In addition to setting GUILE_WARN_DEPRECATED in the environment, you
197 can also use (debug-enable 'warn-deprecated) and (debug-disable
198 'warn-deprecated) to enable and disable the detailed messaged at run
201 Additionally, if your toolchain is new enough, you will receive
202 warnings at link time if you have a Guile extension that uses
203 deprecated functions provided by Guile.
205 --disable-shared --- Do not build shared libraries.
206 --disable-static --- Do not build static libraries.
208 Normally, both static and shared libraries will be built if your
209 system supports them.
211 --enable-debug-freelist --- Enable freelist debugging.
213 This enables a debugging version of scm_cell and scm_double_cell,
214 and also registers an extra primitive, the setter
215 `gc-set-debug-check-freelist!'.
217 Configure with the --enable-debug-freelist option to enable the
218 gc-set-debug-check-freelist! primitive, and then use:
220 (gc-set-debug-check-freelist! #t) # turn on checking of the freelist
221 (gc-set-debug-check-freelist! #f) # turn off checking
223 Checking of the freelist forces a traversal of the freelist and a
224 garbage collection before each allocation of a cell. This can slow
225 down the interpreter dramatically, so the setter should be used to
226 turn on this extra processing only when necessary.
228 --enable-debug-malloc --- Enable malloc debugging.
230 Include code for debugging of calls to scm_malloc, scm_realloc, etc.
232 It records the number of allocated objects of each kind. This is
233 useful when searching for memory leaks.
235 A Guile compiled with this option provides the primitive
236 `malloc-stats' which returns an alist with pairs of kind and the
237 number of objects of that kind.
239 --enable-guile-debug --- Include internal debugging functions
240 --disable-posix --- omit posix interfaces
241 --disable-networking --- omit networking interfaces
242 --disable-regex --- omit regular expression interfaces
245 Cross building Guile =====================================================
247 As of Guile 2.0.x, the build process produces a library, libguile-2.0,
248 along with Guile "object files" containing bytecode to be interpreted by
249 Guile's virtual machine. The bytecode format depends on the endianness
250 and word size of the host CPU.
252 Thus, when cross building Guile, you first need to configure, build and
253 install it for your build host.
255 Then, you may configure Guile for cross building:
257 ./configure --host=i686-pc-cygwin --disable-shared
259 A C compiler for the build system is required. If that doesn't suit it
260 can be specified with the CC_FOR_BUILD variable in the usual way, for
263 ./configure --host=m68k-unknown-linux-gnu CC_FOR_BUILD=/my/local/gcc
265 Guile for the build system can be specified similarly with the
266 GUILE_FOR_BUILD variable, which defaults to whatever `guile' executable
267 is found in $PATH. It must have the exact same version has the Guile
268 that you intend to cross-build.
271 Using Guile Without Installing It =========================================
273 The "meta/" subdirectory of the Guile sources contains a script called
274 "guile" that can be used to run the Guile that has just been built. Note
275 that this is not the same "guile" as the one that is installed; this
276 "guile" is a wrapper script that sets up the environment appropriately,
277 then invokes the Guile binary.
279 You may also build external packages against an uninstalled Guile build
280 tree. The "uninstalled-env" script in the "meta/" subdirectory will set
281 up an environment with a path including "meta/", a modified dynamic
282 linker path, a modified PKG_CONFIG_PATH, etc.
284 For example, you can enter this environment via invoking
286 meta/uninstalled-env bash
288 Within that shell, other packages should be able to build against
292 Installing SLIB ===========================================================
294 In order to use SLIB from Guile you basically only need to put the
295 `slib' directory _in_ one of the directories on Guile's load path.
297 The standard installation is:
299 1. Obtain slib from http://www-swiss.ai.mit.edu/~jaffer/SLIB.html
301 2. Put it in Guile's data directory, that is the directory printed when
304 guile-config info pkgdatadir
306 at the shell prompt. This is normally `/usr/local/share/guile', so the
307 directory will normally have full path `/usr/local/share/guile/slib'.
309 3. Start guile as a user with write access to the data directory and type
311 (use-modules (ice-9 slib))
313 at the Guile prompt. This will generate the slibcat catalog next to
316 SLIB's `require' is provided by the Guile module (ice-9 slib).
320 (use-modules (ice-9 slib))
325 Guile Documentation ==================================================
327 The Guile Reference Manual (guile.info) is the primary documentation for
328 Guile. A copy of the R5RS Scheme specification is included too
331 Info format versions of this documentation are installed as part of
332 the normal build process. The texinfo sources are under the doc
333 directory, and other formats like Postscript, PDF, DVI or HTML can be
334 generated from them with Tex and Texinfo tools.
336 The doc directory also includes an example-smob subdirectory which has
337 the example code from the "Defining New Types (Smobs)" chapter of the
340 The Guile WWW page is at
342 http://www.gnu.org/software/guile/guile.html
344 It contains a link to the Guile FAQ.
346 About This Distribution ==============================================
348 Interesting files include:
350 - LICENSE, which contains the exact terms of the Guile license.
351 - COPYING.LESSER, which contains the terms of the GNU Lesser General Public License.
352 - COPYING, which contains the terms of the GNU General Public License.
353 - INSTALL, which contains general instructions for building/installing Guile.
354 - NEWS, which describes user-visible changes since the last release of Guile.
356 Files are usually installed according to the prefix specified to
357 configure, /usr/local by default. Building and installing gives you:
359 Executables, in ${prefix}/bin:
361 guile --- a stand-alone interpreter for Guile. With no arguments, this
362 is a simple interactive Scheme interpreter. It can also be used
363 as an interpreter for script files; see the NEWS file for details.
364 guile-config --- a Guile script which provides the information necessary
365 to link your programs against the Guile library.
366 guile-snarf --- a script to parse declarations in your C code for
367 Scheme-visible C functions, Scheme objects to be used by C code,
370 Libraries, in ${prefix}/lib. Depending on the platform and options
371 given to configure, you may get shared libraries in addition
372 to or instead of these static libraries:
374 libguile.a --- an object library containing the Guile interpreter,
375 You can use Guile in your own programs by linking against this.
376 libguilereadline.a --- an object library containing glue code for the
377 GNU readline library.
379 libguile-srfi-*.a --- various SRFI support libraries
381 Header files, in ${prefix}/include:
383 libguile.h, guile/gh.h, libguile/*.h --- for libguile.
384 guile-readline/readline.h --- for guile-readline.
386 Support files, in ${prefix}/share/guile/<version>:
388 ice-9/* --- run-time support for Guile: the module system,
389 read-eval-print loop, some R4RS code and other infrastructure.
390 oop/* --- the Guile Object-Oriented Programming System (GOOPS)
391 scripts/* --- executable modules, i.e., scheme programs that can be both
392 called as an executable from the shell, and loaded and used as a
393 module from scheme code. See scripts/README for more info.
394 srfi/* --- SRFI support modules. See srfi/README for more info.
396 Automake macros, in ${prefix}/share/aclocal:
400 Documentation in Info format, in ${prefix}/info:
402 guile --- Guile reference manual.
404 guile-tut --- Guile tutorial.
406 GOOPS --- GOOPS reference manual.
408 r5rs --- Revised(5) Report on the Algorithmic Language Scheme.
411 The Guile source tree is laid out as follows:
414 The Guile Scheme interpreter --- both the object library
415 for you to link with your programs, and the executable you can run.
416 ice-9: Guile's module system, initialization code, and other infrastructure.
418 Source for the guile-config script.
420 The glue code for using GNU readline with Guile. This
421 will be build when configure can find a recent enough readline
422 library on your system.
423 doc: Documentation (see above).
425 Git Repository Access ================================================
427 Guile's source code is stored in a Git repository at Savannah. Anyone
428 can access it using `git-clone' from one of the following URLs:
430 git://git.sv.gnu.org/guile.git
431 http://git.sv.gnu.org/r/guile.git
433 Developers with a Savannah SSH account can also access it from:
435 ssh://git.sv.gnu.org/srv/git/guile.git
437 The repository can also be browsed on-line at the following address:
439 http://git.sv.gnu.org/gitweb/?p=guile.git
441 For more information on Git, please see:
445 Please send problem reports to <bug-guile@gnu.org>.