1 !!! This is not a Guile release; it is a source tree retrieved via
2 anonymous CVS 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 1.10.0.
19 Please send bug reports to bug-guile@gnu.org. Note that you must be
20 subscribed to this list first, in order to successfully send a report
23 See the LICENSE file for the specific terms that apply to Guile.
26 Additional INSTALL instructions ===========================================
28 Generic instructions for configuring and compiling Guile can be found
29 in the INSTALL file. Guile specific information and configure options
30 can be found below, including instructions for installing SLIB.
32 Guile requires a few external packages and can optionally use a number
33 of external packages such as `readline' when they are available.
34 Guile expects to be able to find these packages in the default
35 compiler setup, it does not try to make any special arrangements
36 itself. For example, for the `readline' package, Guile expects to be
37 able to find the include file <readline/readline.h>, without passing
38 any special `-I' options to the compiler.
40 If you installed an external package, and you used the --prefix
41 installation option to install it somewhere else than /usr/local, you
42 must arrange for your compiler to find it by default. If that
43 compiler is gcc, one convenient way of making such arrangements is to
44 use the --with-local-prefix option during installation, naming the
45 same directory as you used in the --prefix option of the package. In
46 particular, it is not good enough to use the same --prefix option when
47 you install gcc and the package; you need to use the
48 --with-local-prefix option as well. See the gcc documentation for
52 Required External Packages ================================================
54 Guile requires the following external packages:
56 - GNU MP, at least version 4.1
58 GNU MP is used for bignum arithmetic. It is available from
61 - libltdl from libtool, at least from libtool version 1.5.6
63 libltdl is used for loading extensions at run-time. It is
64 available from http://www.gnu.org/software/libtool/
67 Special Instructions For Some Systems =====================================
69 We would like Guile to build on all systems using the simple
70 instructions above, but it seems that a few systems still need special
71 treatment. If you can send us fixes for these problems, we'd be
76 Guile specific flags Accepted by Configure =================================
78 If you run the configure script with no arguments, it should examine
79 your system and set things up appropriately. However, there are a few
80 switches specific to Guile you may find useful in some circumstances.
82 --without-threads --- Build without thread support
84 Build a Guile executable and library that supports multi-threading.
86 The default is to enable threading support when your operating
87 system offsers 'POSIX threads'. When you do not want threading, use
90 --enable-deprecated=LEVEL
92 Guile may contain features that are `deprecated'. When a feature is
93 deprecated, it means that it is still there, but that there is a
94 better way of achieving the same thing, and we'd rather have you use
95 this better way. This allows us to eventually remove the old
96 implementation and helps to keep Guile reasonably clean of historic
99 Deprecated features are considered harmful; using them is likely a
100 bug. See below for the related notion of `discouraged' features,
101 which are OK but have fallen out of favor.
103 See the file NEWS for a list of features that are currently
104 deprecated. Each entry will also tell you what you should replace
107 To give you some help with this process, and to encourage (OK,
108 nudge) people to switch to the newer methods, Guile can emit
109 warnings or errors when you use a deprecated feature. There is
110 quite a range of possibilities, from being completely silent to
111 giving errors at link time. What exactly happens is determined both
112 by the value of the `--enable-deprecated' configuration option when
113 Guile was built, and by the GUILE_WARN_DEPRECATED environment
118 When Guile has been configured with `--enable-deprecated=no' (or,
119 equivalently, with `--disable-deprecated') then all deprecated
120 features are omitted from Guile. You will get "undefined
121 reference", "variable unbound" or similar errors when you try to
124 When `--enable-deprecated=LEVEL' has been specified (for LEVEL not
125 "no"), LEVEL will be used as the default value of the environment
126 variable GUILE_WARN_DEPRECATED. A value of "yes" is changed to
127 "summary" and "shutup" is changed to "no", however.
129 When GUILE_WARN_DEPRECATED has the value "no", nothing special
130 will happen when a deprecated feature is used.
132 When GUILE_WARN_DEPRECATED has the value "summary", and a
133 deprecated feature has been used, Guile will print this message at
136 Some deprecated features have been used. Set the environment
137 variable GUILE_WARN_DEPRECATED to "detailed" and rerun the
138 program to get more information. Set it to "no" to suppress
141 When GUILE_WARN_DEPRECATED has the value "detailed", a detailed
142 warning is emitted immediatly for the first use of a deprecated
145 The default is `--enable-deprecated=yes'.
147 In addition to setting GUILE_WARN_DEPRECATED in the environment, you
148 can also use (debug-enable 'warn-deprecated) and (debug-disable
149 'warn-deprecated) to enable and disable the detailed messaged at run
152 --disable-discouraged
154 In addition to deprecated features, Guile can also contain things
155 that are merely `discouraged'. It is OK to continue to use these
156 features in old code, but new code should avoid them since there are
159 There is nothing wrong with a discouraged feature per se, but they
160 might have strange names, or be non-standard, for example. Avoiding
161 them will make your code better.
163 --disable-shared --- Do not build shared libraries.
164 --disable-static --- Do not build static libraries.
166 Normally, both static and shared libraries will be built if your
167 system supports them.
169 --enable-debug-freelist --- Enable freelist debugging.
171 This enables a debugging version of scm_cell and scm_double_cell,
172 and also registers an extra primitive, the setter
173 `gc-set-debug-check-freelist!'.
175 Configure with the --enable-debug-freelist option to enable the
176 gc-set-debug-check-freelist! primitive, and then use:
178 (gc-set-debug-check-freelist! #t) # turn on checking of the freelist
179 (gc-set-debug-check-freelist! #f) # turn off checking
181 Checking of the freelist forces a traversal of the freelist and a
182 garbage collection before each allocation of a cell. This can slow
183 down the interpreter dramatically, so the setter should be used to
184 turn on this extra processing only when necessary.
186 --enable-debug-malloc --- Enable malloc debugging.
188 Include code for debugging of calls to scm_malloc, scm_realloc, etc.
190 It records the number of allocated objects of each kind. This is
191 useful when searching for memory leaks.
193 A Guile compiled with this option provides the primitive
194 `malloc-stats' which returns an alist with pairs of kind and the
195 number of objects of that kind.
197 --enable-guile-debug --- Include internal debugging functions
198 --disable-posix --- omit posix interfaces
199 --disable-networking --- omit networking interfaces
200 --disable-regex --- omit regular expression interfaces
203 Cross building Guile =====================================================
205 As of guile-1.5.x, the build process uses compiled C files for
206 snarfing, and (indirectly, through libtool) for linking, and uses the
207 guile executable for generating documentation.
209 When cross building guile, you first need to configure, build and
210 install guile for your build host.
212 Then, you may configure guile for cross building, eg:
214 ./configure --host=i686-pc-cygwin --disable-shared
216 A C compiler for the build system is required. The default is
217 "PATH=/usr/bin:$PATH cc". If that doesn't suit it can be specified
218 with the CC_FOR_BUILD variable in the usual way, for instance
220 ./configure --host=m68k-unknown-linux-gnu CC_FOR_BUILD=/my/local/gcc
222 Guile for the build system can be specified similarly with the
223 GUILE_FOR_BUILD variable, it defaults to just "guile".
226 Using Guile Without Installing It =========================================
228 The top directory of the Guile sources contains a script called
229 "pre-inst-guile" that can be used to run the Guile that has just been
233 Installing SLIB ===========================================================
235 In order to use SLIB from Guile you basically only need to put the
236 `slib' directory _in_ one of the directories on Guile's load path.
238 The standard installation is:
240 1. Obtain slib from http://www-swiss.ai.mit.edu/~jaffer/SLIB.html
242 2. Put it in Guile's data directory, that is the directory printed when
245 guile-config info pkgdatadir
247 at the shell prompt. This is normally `/usr/local/share/guile', so the
248 directory will normally have full path `/usr/local/share/guile/slib'.
250 3. Start guile as a user with write access to the data directory and type
252 (use-modules (ice-9 slib))
254 at the Guile prompt. This will generate the slibcat catalog next to
257 SLIB's `require' is provided by the Guile module (ice-9 slib).
261 (use-modules (ice-9 slib))
266 Guile Documentation ==================================================
268 If you've never used Scheme before, then the Guile Tutorial
269 (guile-tut.info) is a good starting point. The Guile Reference Manual
270 (guile.info) is the primary documentation for Guile. The Goops object
271 system is documented separately (goops.info). A copy of the R5RS
272 Scheme specification is included too (r5rs.info).
274 Info format versions of this documentation are installed as part of
275 the normal build process. The texinfo sources are under the doc
276 directory, and other formats like Postscript, PDF, DVI or HTML can be
277 generated from them with Tex and Texinfo tools.
279 The doc directory also includes an example-smob subdirectory which has
280 the example code from the "Defining New Types (Smobs)" chapter of the
283 The Guile WWW page is at
285 http://www.gnu.org/software/guile/guile.html
287 It contains a link to the Guile FAQ.
289 About This Distribution ==============================================
291 Interesting files include:
293 - LICENSE, which contains the exact terms of the Guile license.
294 - COPYING, which contains the terms of the GNU General Public License.
295 - INSTALL, which contains general instructions for building/installing Guile.
296 - NEWS, which describes user-visible changes since the last release of Guile.
298 Files are usually installed according to the prefix specified to
299 configure, /usr/local by default. Building and installing gives you:
301 Executables, in ${prefix}/bin:
303 guile --- a stand-alone interpreter for Guile. With no arguments, this
304 is a simple interactive Scheme interpreter. It can also be used
305 as an interpreter for script files; see the NEWS file for details.
306 guile-config --- a Guile script which provides the information necessary
307 to link your programs against the Guile library.
308 guile-snarf --- a script to parse declarations in your C code for
309 Scheme-visible C functions, Scheme objects to be used by C code,
312 Libraries, in ${prefix}/lib. Depending on the platform and options
313 given to configure, you may get shared libraries in addition
314 to or instead of these static libraries:
316 libguile.a --- an object library containing the Guile interpreter,
317 You can use Guile in your own programs by linking against this.
318 libguilereadline.a --- an object library containing glue code for the
319 GNU readline library.
321 libguile-srfi-*.a --- various SRFI support libraries
323 Header files, in ${prefix}/include:
325 libguile.h, guile/gh.h, libguile/*.h --- for libguile.
326 guile-readline/readline.h --- for guile-readline.
328 Support files, in ${prefix}/share/guile/<version>:
330 ice-9/* --- run-time support for Guile: the module system,
331 read-eval-print loop, some R4RS code and other infrastructure.
332 oop/* --- the Guile Object-Oriented Programming System (GOOPS)
333 scripts/* --- executable modules, i.e., scheme programs that can be both
334 called as an executable from the shell, and loaded and used as a
335 module from scheme code. See scripts/README for more info.
336 srfi/* --- SRFI support modules. See srfi/README for more info.
338 Automake macros, in ${prefix}/share/aclocal:
342 Documentation in Info format, in ${prefix}/info:
344 guile --- Guile reference manual.
346 guile-tut --- Guile tutorial.
348 GOOPS --- GOOPS reference manual.
350 r5rs --- Revised(5) Report on the Algorithmic Language Scheme.
353 The Guile source tree is laid out as follows:
356 The Guile Scheme interpreter --- both the object library
357 for you to link with your programs, and the executable you can run.
358 ice-9: Guile's module system, initialization code, and other infrastructure.
360 Source for the guile-config script.
362 The glue code for using GNU readline with Guile. This
363 will be build when configure can find a recent enough readline
364 library on your system.
365 doc: Documentation (see above).
367 Anonymous CVS Access and FTP snapshots ===============================
369 We make the developers' working Guile sources available via anonymous
370 CVS, and by nightly snapshots, accessible via FTP. See the files
371 `ANON-CVS' and `SNAPSHOTS' for details.
373 If you would like to receive mail when people commit changes to the
374 Guile CVS repository, you can subscribe to guile-cvs@gnu.org by the
375 Mailman mailing list interface at
377 <http://mail.gnu.org/mailman/listinfo/guile-cvs>