1 !!! This is not a Guile release; it is a source tree retrieved via
2 Git or as a nightly snapshot at some random time after the
3 Guile 1.8 release. If this were a Guile release, you would not see
4 this message. !!! [fixme: zonk on release]
6 This is a 1.9 development version of Guile, Project GNU's extension
7 language library. Guile is an interpreter for Scheme, packaged as a
8 library that you can link into your applications to give them their
9 own scripting language. Guile will eventually support other languages
10 as well, giving users of Guile-based applications a choice of
13 Guile versions with an odd middle number, i.e. 1.9.* are unstable
14 development versions. Even middle numbers indicate stable versions.
15 This has been the case since the 1.3.* series.
17 The next stable release will likely be version 2.0.0.
19 Please send bug reports to bug-guile@gnu.org.
21 See the LICENSE file for the specific terms that apply to Guile.
24 Additional INSTALL instructions ===========================================
26 Generic instructions for configuring and compiling Guile can be found
27 in the INSTALL file. Guile specific information and configure options
28 can be found below, including instructions for installing SLIB.
30 Guile depends on the following external libraries.
37 It will also use the libreadline library if it is available. For each
38 of these there is a corresponding --with-XXX-prefix option that you
39 can use when invoking ./configure, if you have these libraries
40 installed in a location other than the standard places (/usr and
43 These options are provided by the Gnulib `havelib' module, and details
44 of how they work are documented in `Searching for Libraries' in the
45 Gnulib manual (http://www.gnu.org/software/gnulib/manual). The extent
46 to which they work on a given OS depends on whether that OS supports
47 encoding full library path names in executables (aka `rpath'). Also
48 note that using these options, and hence hardcoding full library path
49 names (where that is supported), makes it impossible to later move the
50 built executables and libraries to an installation location other than
51 the one that was specified at build time.
53 Another possible approach is to set CPPFLAGS and LDFLAGS before
54 running configure, so that they include -I options for all the
55 non-standard places where you have installed header files and -L
56 options for all the non-standard places where you have installed
57 libraries. This will allow configure and make to find those headers
58 and libraries during the build. The locations found will not be
59 hardcoded into the build executables and libraries, so with this
60 approach you will probably also need to set LD_LIBRARY_PATH
61 correspondingly, to allow Guile to find the necessary libraries again
65 Required External Packages ================================================
67 Guile requires the following external packages:
69 - GNU MP, at least version 4.1
71 GNU MP is used for bignum arithmetic. It is available from
74 - libltdl from GNU Libtool, at least version 1.5.6
76 libltdl is used for loading extensions at run-time. It is
77 available from http://www.gnu.org/software/libtool/ .
81 libunistring is used for Unicode string operations, such as the
82 `utf*->string' procedures. It is available from
83 http://www.gnu.org/software/libunistring/ .
85 - libgc, at least version 7.0
87 libgc (aka. the Boehm-Demers-Weiser garbage collector) is the
88 conservative garbage collector used by Guile. It is available
89 from http://www.hpl.hp.com/personal/Hans_Boehm/gc/ .
92 Special Instructions For Some Systems =====================================
94 We would like Guile to build on all systems using the simple
95 instructions above, but it seems that a few systems still need special
96 treatment. If you can send us fixes for these problems, we'd be
101 Guile specific flags Accepted by Configure =================================
103 If you run the configure script with no arguments, it should examine
104 your system and set things up appropriately. However, there are a few
105 switches specific to Guile you may find useful in some circumstances.
107 --without-threads --- Build without thread support
109 Build a Guile executable and library that supports multi-threading.
111 The default is to enable threading support when your operating
112 system offsers 'POSIX threads'. When you do not want threading, use
115 --enable-deprecated=LEVEL
117 Guile may contain features that are `deprecated'. When a feature is
118 deprecated, it means that it is still there, but that there is a
119 better way of achieving the same thing, and we'd rather have you use
120 this better way. This allows us to eventually remove the old
121 implementation and helps to keep Guile reasonably clean of historic
124 Deprecated features are considered harmful; using them is likely a
125 bug. See below for the related notion of `discouraged' features,
126 which are OK but have fallen out of favor.
128 See the file NEWS for a list of features that are currently
129 deprecated. Each entry will also tell you what you should replace
132 To give you some help with this process, and to encourage (OK,
133 nudge) people to switch to the newer methods, Guile can emit
134 warnings or errors when you use a deprecated feature. There is
135 quite a range of possibilities, from being completely silent to
136 giving errors at link time. What exactly happens is determined both
137 by the value of the `--enable-deprecated' configuration option when
138 Guile was built, and by the GUILE_WARN_DEPRECATED environment
143 When Guile has been configured with `--enable-deprecated=no' (or,
144 equivalently, with `--disable-deprecated') then all deprecated
145 features are omitted from Guile. You will get "undefined
146 reference", "variable unbound" or similar errors when you try to
149 When `--enable-deprecated=LEVEL' has been specified (for LEVEL not
150 "no"), LEVEL will be used as the default value of the environment
151 variable GUILE_WARN_DEPRECATED. A value of "yes" is changed to
152 "summary" and "shutup" is changed to "no", however.
154 When GUILE_WARN_DEPRECATED has the value "no", nothing special
155 will happen when a deprecated feature is used.
157 When GUILE_WARN_DEPRECATED has the value "summary", and a
158 deprecated feature has been used, Guile will print this message at
161 Some deprecated features have been used. Set the environment
162 variable GUILE_WARN_DEPRECATED to "detailed" and rerun the
163 program to get more information. Set it to "no" to suppress
166 When GUILE_WARN_DEPRECATED has the value "detailed", a detailed
167 warning is emitted immediatly for the first use of a deprecated
170 The default is `--enable-deprecated=yes'.
172 In addition to setting GUILE_WARN_DEPRECATED in the environment, you
173 can also use (debug-enable 'warn-deprecated) and (debug-disable
174 'warn-deprecated) to enable and disable the detailed messaged at run
177 --disable-discouraged
179 In addition to deprecated features, Guile can also contain things
180 that are merely `discouraged'. It is OK to continue to use these
181 features in old code, but new code should avoid them since there are
184 There is nothing wrong with a discouraged feature per se, but they
185 might have strange names, or be non-standard, for example. Avoiding
186 them will make your code better.
188 --disable-shared --- Do not build shared libraries.
189 --disable-static --- Do not build static libraries.
191 Normally, both static and shared libraries will be built if your
192 system supports them.
194 --enable-debug-freelist --- Enable freelist debugging.
196 This enables a debugging version of scm_cell and scm_double_cell,
197 and also registers an extra primitive, the setter
198 `gc-set-debug-check-freelist!'.
200 Configure with the --enable-debug-freelist option to enable the
201 gc-set-debug-check-freelist! primitive, and then use:
203 (gc-set-debug-check-freelist! #t) # turn on checking of the freelist
204 (gc-set-debug-check-freelist! #f) # turn off checking
206 Checking of the freelist forces a traversal of the freelist and a
207 garbage collection before each allocation of a cell. This can slow
208 down the interpreter dramatically, so the setter should be used to
209 turn on this extra processing only when necessary.
211 --enable-debug-malloc --- Enable malloc debugging.
213 Include code for debugging of calls to scm_malloc, scm_realloc, etc.
215 It records the number of allocated objects of each kind. This is
216 useful when searching for memory leaks.
218 A Guile compiled with this option provides the primitive
219 `malloc-stats' which returns an alist with pairs of kind and the
220 number of objects of that kind.
222 --enable-guile-debug --- Include internal debugging functions
223 --disable-posix --- omit posix interfaces
224 --disable-networking --- omit networking interfaces
225 --disable-regex --- omit regular expression interfaces
228 Cross building Guile =====================================================
230 As of guile-1.5.x, the build process uses compiled C files for
231 snarfing, and (indirectly, through libtool) for linking, and uses the
232 guile executable for generating documentation.
234 When cross building guile, you first need to configure, build and
235 install guile for your build host.
237 Then, you may configure guile for cross building, eg:
239 ./configure --host=i686-pc-cygwin --disable-shared
241 A C compiler for the build system is required. The default is
242 "PATH=/usr/bin:$PATH cc". If that doesn't suit it can be specified
243 with the CC_FOR_BUILD variable in the usual way, for instance
245 ./configure --host=m68k-unknown-linux-gnu CC_FOR_BUILD=/my/local/gcc
247 Guile for the build system can be specified similarly with the
248 GUILE_FOR_BUILD variable, it defaults to just "guile".
251 Using Guile Without Installing It =========================================
253 The "meta/" subdirectory of the Guile sources contains a script called
254 "guile" that can be used to run the Guile that has just been built. Note
255 that this is not the same "guile" as the one that is installed; this
256 "guile" is a wrapper script that sets up the environment appropriately,
257 then invokes the Guile binary.
259 You may also build external packages against an uninstalled Guile build
260 tree. The "uninstalled-env" script in the "meta/" subdirectory will set
261 up an environment with a path including "meta/", a modified dynamic
262 linker path, a modified PKG_CONFIG_PATH, etc.
264 For example, you can enter this environment via invoking
266 meta/uninstalled-env bash
268 Within that shell, other packages should be able to build against
272 Installing SLIB ===========================================================
274 In order to use SLIB from Guile you basically only need to put the
275 `slib' directory _in_ one of the directories on Guile's load path.
277 The standard installation is:
279 1. Obtain slib from http://www-swiss.ai.mit.edu/~jaffer/SLIB.html
281 2. Put it in Guile's data directory, that is the directory printed when
284 guile-config info pkgdatadir
286 at the shell prompt. This is normally `/usr/local/share/guile', so the
287 directory will normally have full path `/usr/local/share/guile/slib'.
289 3. Start guile as a user with write access to the data directory and type
291 (use-modules (ice-9 slib))
293 at the Guile prompt. This will generate the slibcat catalog next to
296 SLIB's `require' is provided by the Guile module (ice-9 slib).
300 (use-modules (ice-9 slib))
305 Guile Documentation ==================================================
307 If you've never used Scheme before, then the Guile Tutorial
308 (guile-tut.info) is a good starting point. The Guile Reference Manual
309 (guile.info) is the primary documentation for Guile. A copy of the
310 R5RS Scheme specification is included too (r5rs.info).
312 Info format versions of this documentation are installed as part of
313 the normal build process. The texinfo sources are under the doc
314 directory, and other formats like Postscript, PDF, DVI or HTML can be
315 generated from them with Tex and Texinfo tools.
317 The doc directory also includes an example-smob subdirectory which has
318 the example code from the "Defining New Types (Smobs)" chapter of the
321 The Guile WWW page is at
323 http://www.gnu.org/software/guile/guile.html
325 It contains a link to the Guile FAQ.
327 About This Distribution ==============================================
329 Interesting files include:
331 - LICENSE, which contains the exact terms of the Guile license.
332 - COPYING.LESSER, which contains the terms of the GNU Lesser General Public License.
333 - COPYING, which contains the terms of the GNU General Public License.
334 - INSTALL, which contains general instructions for building/installing Guile.
335 - NEWS, which describes user-visible changes since the last release of Guile.
337 Files are usually installed according to the prefix specified to
338 configure, /usr/local by default. Building and installing gives you:
340 Executables, in ${prefix}/bin:
342 guile --- a stand-alone interpreter for Guile. With no arguments, this
343 is a simple interactive Scheme interpreter. It can also be used
344 as an interpreter for script files; see the NEWS file for details.
345 guile-config --- a Guile script which provides the information necessary
346 to link your programs against the Guile library.
347 guile-snarf --- a script to parse declarations in your C code for
348 Scheme-visible C functions, Scheme objects to be used by C code,
351 Libraries, in ${prefix}/lib. Depending on the platform and options
352 given to configure, you may get shared libraries in addition
353 to or instead of these static libraries:
355 libguile.a --- an object library containing the Guile interpreter,
356 You can use Guile in your own programs by linking against this.
357 libguilereadline.a --- an object library containing glue code for the
358 GNU readline library.
360 libguile-srfi-*.a --- various SRFI support libraries
362 Header files, in ${prefix}/include:
364 libguile.h, guile/gh.h, libguile/*.h --- for libguile.
365 guile-readline/readline.h --- for guile-readline.
367 Support files, in ${prefix}/share/guile/<version>:
369 ice-9/* --- run-time support for Guile: the module system,
370 read-eval-print loop, some R4RS code and other infrastructure.
371 oop/* --- the Guile Object-Oriented Programming System (GOOPS)
372 scripts/* --- executable modules, i.e., scheme programs that can be both
373 called as an executable from the shell, and loaded and used as a
374 module from scheme code. See scripts/README for more info.
375 srfi/* --- SRFI support modules. See srfi/README for more info.
377 Automake macros, in ${prefix}/share/aclocal:
381 Documentation in Info format, in ${prefix}/info:
383 guile --- Guile reference manual.
385 guile-tut --- Guile tutorial.
387 GOOPS --- GOOPS reference manual.
389 r5rs --- Revised(5) Report on the Algorithmic Language Scheme.
392 The Guile source tree is laid out as follows:
395 The Guile Scheme interpreter --- both the object library
396 for you to link with your programs, and the executable you can run.
397 ice-9: Guile's module system, initialization code, and other infrastructure.
399 Source for the guile-config script.
401 The glue code for using GNU readline with Guile. This
402 will be build when configure can find a recent enough readline
403 library on your system.
404 doc: Documentation (see above).
406 Git Repository Access ================================================
408 Guile's source code is stored in a Git repository at Savannah. Anyone
409 can access it using `git-clone' from one of the following URLs:
411 git://git.sv.gnu.org/guile.git
412 http://git.sv.gnu.org/r/guile.git
414 Developers with a Savannah SSH account can also access it from:
416 ssh://git.sv.gnu.org/srv/git/guile.git
418 The repository can also be browsed on-line at the following address:
420 http://git.sv.gnu.org/gitweb/?p=guile.git
422 For more information on Git, please see:
426 Please send problem reports to <bug-guile@gnu.org>.