1 This is version 1.8.7 of Guile, Project GNU's extension language
2 library. Guile is an interpreter for Scheme, packaged as a library
3 that you can link into your applications to give them their own
4 scripting language. Guile will eventually support other languages as
5 well, giving 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.
12 Additional INSTALL instructions ===========================================
14 Generic instructions for configuring and compiling Guile can be found
15 in the INSTALL file. Guile specific information and configure options
16 can be found below, including instructions for installing SLIB.
18 Guile requires a few external packages and can optionally use a number
19 of external packages such as `readline' when they are available.
20 Guile expects to be able to find these packages in the default
21 compiler setup, it does not try to make any special arrangements
22 itself. For example, for the `readline' package, Guile expects to be
23 able to find the include file <readline/readline.h>, without passing
24 any special `-I' options to the compiler.
26 If you installed an external package, and you used the --prefix
27 installation option to install it somewhere else than /usr/local, you
28 must arrange for your compiler to find it by default. If that
29 compiler is gcc, one convenient way of making such arrangements is to
30 use the --with-local-prefix option during installation, naming the
31 same directory as you used in the --prefix option of the package. In
32 particular, it is not good enough to use the same --prefix option when
33 you install gcc and the package; you need to use the
34 --with-local-prefix option as well. See the gcc documentation for
38 Required External Packages ================================================
40 Guile requires the following external packages:
42 - GNU MP, at least version 4.1
44 GNU MP is used for bignum arithmetic. It is available from
47 - libltdl from libtool, at least from libtool version 1.5.6
49 libltdl is used for loading extensions at run-time. It is
50 available from http://www.gnu.org/software/libtool/
53 Guile specific flags Accepted by Configure =================================
55 If you run the configure script with no arguments, it should examine
56 your system and set things up appropriately. However, there are a few
57 switches specific to Guile you may find useful in some circumstances.
59 --without-threads --- Build without thread support
61 Build a Guile executable and library that supports multi-threading.
63 The default is to enable threading support when your operating
64 system offsers 'POSIX threads'. When you do not want threading, use
67 --enable-deprecated=LEVEL
69 Guile may contain features that are `deprecated'. When a feature is
70 deprecated, it means that it is still there, but that there is a
71 better way of achieving the same thing, and we'd rather have you use
72 this better way. This allows us to eventually remove the old
73 implementation and helps to keep Guile reasonably clean of historic
76 Deprecated features are considered harmful; using them is likely a
77 bug. See below for the related notion of `discouraged' features,
78 which are OK but have fallen out of favor.
80 See the file NEWS for a list of features that are currently
81 deprecated. Each entry will also tell you what you should replace
84 To give you some help with this process, and to encourage (OK,
85 nudge) people to switch to the newer methods, Guile can emit
86 warnings or errors when you use a deprecated feature. There is
87 quite a range of possibilities, from being completely silent to
88 giving errors at link time. What exactly happens is determined both
89 by the value of the `--enable-deprecated' configuration option when
90 Guile was built, and by the GUILE_WARN_DEPRECATED environment
95 When Guile has been configured with `--enable-deprecated=no' (or,
96 equivalently, with `--disable-deprecated') then all deprecated
97 features are omitted from Guile. You will get "undefined
98 reference", "variable unbound" or similar errors when you try to
101 When `--enable-deprecated=LEVEL' has been specified (for LEVEL not
102 "no"), LEVEL will be used as the default value of the environment
103 variable GUILE_WARN_DEPRECATED. A value of "yes" is changed to
104 "summary" and "shutup" is changed to "no", however.
106 When GUILE_WARN_DEPRECATED has the value "no", nothing special
107 will happen when a deprecated feature is used.
109 When GUILE_WARN_DEPRECATED has the value "summary", and a
110 deprecated feature has been used, Guile will print this message at
113 Some deprecated features have been used. Set the environment
114 variable GUILE_WARN_DEPRECATED to "detailed" and rerun the
115 program to get more information. Set it to "no" to suppress
118 When GUILE_WARN_DEPRECATED has the value "detailed", a detailed
119 warning is emitted immediatly for the first use of a deprecated
122 The default is `--enable-deprecated=yes'.
124 In addition to setting GUILE_WARN_DEPRECATED in the environment, you
125 can also use (debug-enable 'warn-deprecated) and (debug-disable
126 'warn-deprecated) to enable and disable the detailed messaged at run
129 --disable-discouraged
131 In addition to deprecated features, Guile can also contain things
132 that are merely `discouraged'. It is OK to continue to use these
133 features in old code, but new code should avoid them since there are
136 There is nothing wrong with a discouraged feature per se, but they
137 might have strange names, or be non-standard, for example. Avoiding
138 them will make your code better.
140 --disable-shared --- Do not build shared libraries.
141 --disable-static --- Do not build static libraries.
143 Normally, both static and shared libraries will be built if your
144 system supports them.
146 --enable-debug-freelist --- Enable freelist debugging.
148 This enables a debugging version of scm_cell and scm_double_cell,
149 and also registers an extra primitive, the setter
150 `gc-set-debug-check-freelist!'.
152 Configure with the --enable-debug-freelist option to enable the
153 gc-set-debug-check-freelist! primitive, and then use:
155 (gc-set-debug-check-freelist! #t) # turn on checking of the freelist
156 (gc-set-debug-check-freelist! #f) # turn off checking
158 Checking of the freelist forces a traversal of the freelist and a
159 garbage collection before each allocation of a cell. This can slow
160 down the interpreter dramatically, so the setter should be used to
161 turn on this extra processing only when necessary.
163 --enable-debug-malloc --- Enable malloc debugging.
165 Include code for debugging of calls to scm_malloc, scm_realloc, etc.
167 It records the number of allocated objects of each kind. This is
168 useful when searching for memory leaks.
170 A Guile compiled with this option provides the primitive
171 `malloc-stats' which returns an alist with pairs of kind and the
172 number of objects of that kind.
174 --enable-guile-debug --- Include internal debugging functions
175 --disable-posix --- omit posix interfaces
176 --disable-networking --- omit networking interfaces
177 --disable-regex --- omit regular expression interfaces
180 Cross building Guile =====================================================
182 Guile can be cross-compiled for Windows using the i586-mingw32msvc
183 cross-compiler. To do this, you first need to cross-build Guile's
184 prerequisites - GNU MP and libtool/libltdl (as described above) - and
185 then cross-build Guile itself.
187 For each of these steps, configure using an invocation like this:
189 CPPFLAGS=-I/usr/local/i586-mingw32msvc/include \
190 LDFLAGS=-L/usr/local/i586-mingw32msvc/lib \
191 GUILE_FOR_BUILD=/usr/local/bin/guile \
192 ./configure --prefix=/usr/local/i586-mingw32msvc --host=i586-mingw32msvc
194 Then run `make' - which should complete without any errors - and `sudo
195 make install'. (`make check' doesn't work when cross-compiling,
196 because the built DLLs and program cannot be run on GNU/Linux.)
198 The `GUILE_FOR_BUILD=...' setting is needed because some later steps
199 of the build process use Guile itself. In the non-cross-compiling
200 case this is the version of Guile that has just been built. When
201 cross-compiling, you have to set GUILE_FOR_BUILD to tell the build
202 where it can find a native version of Guile, to use for these steps.
204 Cross-compiling for other hosts may also work, using the following
205 instructions; but this has not been recently tested.
207 To configure Guile for cross building, for example for Cygwin:
209 ./configure --host=i686-pc-cygwin --disable-shared
211 A C compiler for the build system is required. The default is
212 "PATH=/usr/bin:$PATH cc". If that doesn't suit it can be specified
213 with the CC_FOR_BUILD variable in the usual way, for instance
215 ./configure --host=m68k-unknown-linux-gnu CC_FOR_BUILD=/my/local/gcc
217 Guile for the build system can be specified similarly with the
218 GUILE_FOR_BUILD variable, it defaults to just "guile".
221 Using Guile Without Installing It =========================================
223 The top directory of the Guile sources contains a script called
224 "pre-inst-guile" that can be used to run the Guile that has just been
228 Installing SLIB ===========================================================
230 In order to use SLIB from Guile you basically only need to put the
231 `slib' directory _in_ one of the directories on Guile's load path.
233 The standard installation is:
235 1. Obtain slib from http://www-swiss.ai.mit.edu/~jaffer/SLIB.html
237 2. Put it in Guile's data directory, that is the directory printed when
240 guile-config info pkgdatadir
242 at the shell prompt. This is normally `/usr/local/share/guile', so the
243 directory will normally have full path `/usr/local/share/guile/slib'.
245 3. Start guile as a user with write access to the data directory and type
247 (use-modules (ice-9 slib))
249 at the Guile prompt. This will generate the slibcat catalog next to
252 SLIB's `require' is provided by the Guile module (ice-9 slib).
256 (use-modules (ice-9 slib))
261 Guile Documentation ==================================================
263 If you've never used Scheme before, then the Guile Tutorial
264 (guile-tut.info) is a good starting point. The Guile Reference Manual
265 (guile.info) is the primary documentation for Guile. The Goops object
266 system is documented separately (goops.info). A copy of the R5RS
267 Scheme specification is included too (r5rs.info).
269 Info format versions of this documentation are installed as part of
270 the normal build process. The texinfo sources are under the doc
271 directory, and other formats like Postscript, PDF, DVI or HTML can be
272 generated from them with Tex and Texinfo tools.
274 The doc directory also includes an example-smob subdirectory which has
275 the example code from the "Defining New Types (Smobs)" chapter of the
278 The Guile WWW page is at
280 http://www.gnu.org/software/guile/guile.html
282 It contains a link to the Guile FAQ.
284 About This Distribution ==============================================
286 Interesting files include:
288 - LICENSE, which contains the exact terms of the Guile license.
289 - COPYING, which contains the terms of the GNU General Public License.
290 - INSTALL, which contains general instructions for building/installing Guile.
291 - NEWS, which describes user-visible changes since the last release of Guile.
293 Files are usually installed according to the prefix specified to
294 configure, /usr/local by default. Building and installing gives you:
296 Executables, in ${prefix}/bin:
298 guile --- a stand-alone interpreter for Guile. With no arguments, this
299 is a simple interactive Scheme interpreter. It can also be used
300 as an interpreter for script files; see the NEWS file for details.
301 guile-config --- a Guile script which provides the information necessary
302 to link your programs against the Guile library.
303 guile-snarf --- a script to parse declarations in your C code for
304 Scheme-visible C functions, Scheme objects to be used by C code,
307 Libraries, in ${prefix}/lib. Depending on the platform and options
308 given to configure, you may get shared libraries in addition
309 to or instead of these static libraries:
311 libguile.a --- an object library containing the Guile interpreter,
312 You can use Guile in your own programs by linking against this.
313 libguilereadline.a --- an object library containing glue code for the
314 GNU readline library.
316 libguile-srfi-*.a --- various SRFI support libraries
318 Header files, in ${prefix}/include:
320 libguile.h, guile/gh.h, libguile/*.h --- for libguile.
321 guile-readline/readline.h --- for guile-readline.
323 Support files, in ${prefix}/share/guile/<version>:
325 ice-9/* --- run-time support for Guile: the module system,
326 read-eval-print loop, some R4RS code and other infrastructure.
327 oop/* --- the Guile Object-Oriented Programming System (GOOPS)
328 scripts/* --- executable modules, i.e., scheme programs that can be both
329 called as an executable from the shell, and loaded and used as a
330 module from scheme code. See scripts/README for more info.
331 srfi/* --- SRFI support modules. See srfi/README for more info.
333 Automake macros, in ${prefix}/share/aclocal:
337 Documentation in Info format, in ${prefix}/info:
339 guile --- Guile reference manual.
341 guile-tut --- Guile tutorial.
343 GOOPS --- GOOPS reference manual.
345 r5rs --- Revised(5) Report on the Algorithmic Language Scheme.
348 The Guile source tree is laid out as follows:
351 The Guile Scheme interpreter --- both the object library
352 for you to link with your programs, and the executable you can run.
353 ice-9: Guile's module system, initialization code, and other infrastructure.
355 Source for the guile-config script.
357 The glue code for using GNU readline with Guile. This
358 will be build when configure can find a recent enough readline
359 library on your system.
360 doc: Documentation (see above).
362 Git Repository Access ================================================
364 Guile's source code is stored in a Git repository at Savannah. Anyone
365 can access it using `git-clone' from one of the following URLs:
367 git://git.sv.gnu.org/guile.git
368 http://git.sv.gnu.org/r/guile.git
370 Developers with a Savannah SSH account can also access it from:
372 ssh://git.sv.gnu.org/srv/git/guile.git
374 The repository can also be browsed on-line at the following address:
376 http://git.sv.gnu.org/gitweb/?p=guile.git
378 For more information on Git, please see:
382 Please send problem reports to <bug-guile@gnu.org>.