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.
38 It will also use the libreadline library if it is available.
40 There is a corresponding `--with-XXX-prefix' option for each of these
41 libraries (except for libgc and libffi which use `pkg-config', see
42 below) that you can use when invoking ./configure, if you have these
43 libraries installed in a location other than the standard places (/usr
46 These options are provided by the Gnulib `havelib' module, and details
47 of how they work are documented in `Searching for Libraries' in the
48 Gnulib manual (http://www.gnu.org/software/gnulib/manual). The extent
49 to which they work on a given OS depends on whether that OS supports
50 encoding full library path names in executables (aka `rpath'). Also
51 note that using these options, and hence hardcoding full library path
52 names (where that is supported), makes it impossible to later move the
53 built executables and libraries to an installation location other than
54 the one that was specified at build time.
56 Another possible approach is to set CPPFLAGS and LDFLAGS on the
57 configure command-line, so that they include -I options for all the
58 non-standard places where you have installed header files and -L
59 options for all the non-standard places where you have installed
60 libraries. This will allow configure and make to find those headers
61 and libraries during the build. E.g.:
63 ../configure [...] CPPFLAGS='-I/my/include' LDFLAGS='-L/my/lib'
65 The locations found will not be hardcoded into the build executables and
66 libraries, so with this approach you will probably also need to set
67 LD_LIBRARY_PATH correspondingly, to allow Guile to find the necessary
68 libraries again at runtime.
71 Required External Packages ================================================
73 Guile requires the following external packages:
75 - GNU MP, at least version 4.1
77 GNU MP is used for bignum arithmetic. It is available from
80 - libltdl from GNU Libtool, at least version 1.5.6
82 libltdl is used for loading extensions at run-time. It is
83 available from http://www.gnu.org/software/libtool/ .
87 libunistring is used for Unicode string operations, such as the
88 `utf*->string' procedures. It is available from
89 http://www.gnu.org/software/libunistring/ .
91 - libgc, at least version 7.0
93 libgc (aka. the Boehm-Demers-Weiser garbage collector) is the
94 conservative garbage collector used by Guile. It is available
95 from http://www.hpl.hp.com/personal/Hans_Boehm/gc/ .
99 libffi provides a "foreign function interface", used by the
100 `(system foreign)' module. It is available from
101 http://sourceware.org/libffi/ .
105 Guile's ./configure script uses pkg-config to discover the correct
106 compile and link options for libgc and libffi. If you don't have
107 pkg-config installed, or you have a version of libgc that doesn't
108 provide a .pc file, you can work around this by setting some
109 variables as part of the configure command-line:
113 - BDW_GC_CFLAGS=<compile flags for picking up libgc headers>
115 - BDW_GC_LIBS=<linker flags for picking up the libgc library>
117 Note that because you're bypassing all pkg-config checks, you will
118 also have to specify libffi flags as well:
120 - LIBFFI_CFLAGS=<compile flags for picking up libffi headers>
122 - LIBFFI_LIBS=<linker flags for picking up the libffi library>
125 Special Instructions For Some Systems =====================================
127 We would like Guile to build on all systems using the simple
128 instructions above, but it seems that a few systems still need special
129 treatment. If you can send us fixes for these problems, we'd be
134 Guile specific flags Accepted by Configure =================================
136 If you run the configure script with no arguments, it should examine
137 your system and set things up appropriately. However, there are a few
138 switches specific to Guile you may find useful in some circumstances.
140 --without-threads --- Build without thread support
142 Build a Guile executable and library that supports multi-threading.
144 The default is to enable threading support when your operating
145 system offsers 'POSIX threads'. When you do not want threading, use
148 --enable-deprecated=LEVEL
150 Guile may contain features that are `deprecated'. When a feature is
151 deprecated, it means that it is still there, but that there is a
152 better way of achieving the same thing, and we'd rather have you use
153 this better way. This allows us to eventually remove the old
154 implementation and helps to keep Guile reasonably clean of historic
157 See the file NEWS for a list of features that are currently
158 deprecated. Each entry will also tell you what you should replace
161 To give you some help with this process, and to encourage (OK,
162 nudge) people to switch to the newer methods, Guile can emit
163 warnings or errors when you use a deprecated feature. There is
164 quite a range of possibilities, from being completely silent to
165 giving errors at link time. What exactly happens is determined both
166 by the value of the `--enable-deprecated' configuration option when
167 Guile was built, and by the GUILE_WARN_DEPRECATED environment
172 When Guile has been configured with `--enable-deprecated=no' (or,
173 equivalently, with `--disable-deprecated') then all deprecated
174 features are omitted from Guile. You will get "undefined
175 reference", "variable unbound" or similar errors when you try to
178 When `--enable-deprecated=LEVEL' has been specified (for LEVEL not
179 "no"), LEVEL will be used as the default value of the environment
180 variable GUILE_WARN_DEPRECATED. A value of "yes" is changed to
181 "summary" and "shutup" is changed to "no", however.
183 When GUILE_WARN_DEPRECATED has the value "no", nothing special
184 will happen when a deprecated feature is used.
186 When GUILE_WARN_DEPRECATED has the value "summary", and a
187 deprecated feature has been used, Guile will print this message at
190 Some deprecated features have been used. Set the environment
191 variable GUILE_WARN_DEPRECATED to "detailed" and rerun the
192 program to get more information. Set it to "no" to suppress
195 When GUILE_WARN_DEPRECATED has the value "detailed", a detailed
196 warning is emitted immediatly for the first use of a deprecated
199 The default is `--enable-deprecated=yes'.
201 In addition to setting GUILE_WARN_DEPRECATED in the environment, you
202 can also use (debug-enable 'warn-deprecated) and (debug-disable
203 'warn-deprecated) to enable and disable the detailed messaged at run
206 Additionally, if your toolchain is new enough, you will receive
207 warnings at link time if you have a Guile extension that uses
208 deprecated functions provided by Guile.
210 --disable-shared --- Do not build shared libraries.
211 --disable-static --- Do not build static libraries.
213 Normally, both static and shared libraries will be built if your
214 system supports them.
216 --enable-debug-freelist --- Enable freelist debugging.
218 This enables a debugging version of scm_cell and scm_double_cell,
219 and also registers an extra primitive, the setter
220 `gc-set-debug-check-freelist!'.
222 Configure with the --enable-debug-freelist option to enable the
223 gc-set-debug-check-freelist! primitive, and then use:
225 (gc-set-debug-check-freelist! #t) # turn on checking of the freelist
226 (gc-set-debug-check-freelist! #f) # turn off checking
228 Checking of the freelist forces a traversal of the freelist and a
229 garbage collection before each allocation of a cell. This can slow
230 down the interpreter dramatically, so the setter should be used to
231 turn on this extra processing only when necessary.
233 --enable-debug-malloc --- Enable malloc debugging.
235 Include code for debugging of calls to scm_malloc, scm_realloc, etc.
237 It records the number of allocated objects of each kind. This is
238 useful when searching for memory leaks.
240 A Guile compiled with this option provides the primitive
241 `malloc-stats' which returns an alist with pairs of kind and the
242 number of objects of that kind.
244 --enable-guile-debug --- Include internal debugging functions
245 --disable-posix --- omit posix interfaces
246 --disable-networking --- omit networking interfaces
247 --disable-regex --- omit regular expression interfaces
250 Cross building Guile =====================================================
252 As of guile-1.5.x, the build process uses compiled C files for
253 snarfing, and (indirectly, through libtool) for linking, and uses the
254 guile executable for generating documentation.
256 When cross building guile, you first need to configure, build and
257 install guile for your build host.
259 Then, you may configure guile for cross building, eg:
261 ./configure --host=i686-pc-cygwin --disable-shared
263 A C compiler for the build system is required. The default is
264 "PATH=/usr/bin:$PATH cc". If that doesn't suit it can be specified
265 with the CC_FOR_BUILD variable in the usual way, for instance
267 ./configure --host=m68k-unknown-linux-gnu CC_FOR_BUILD=/my/local/gcc
269 Guile for the build system can be specified similarly with the
270 GUILE_FOR_BUILD variable, it defaults to just "guile".
273 Using Guile Without Installing It =========================================
275 The "meta/" subdirectory of the Guile sources contains a script called
276 "guile" that can be used to run the Guile that has just been built. Note
277 that this is not the same "guile" as the one that is installed; this
278 "guile" is a wrapper script that sets up the environment appropriately,
279 then invokes the Guile binary.
281 You may also build external packages against an uninstalled Guile build
282 tree. The "uninstalled-env" script in the "meta/" subdirectory will set
283 up an environment with a path including "meta/", a modified dynamic
284 linker path, a modified PKG_CONFIG_PATH, etc.
286 For example, you can enter this environment via invoking
288 meta/uninstalled-env bash
290 Within that shell, other packages should be able to build against
294 Installing SLIB ===========================================================
296 In order to use SLIB from Guile you basically only need to put the
297 `slib' directory _in_ one of the directories on Guile's load path.
299 The standard installation is:
301 1. Obtain slib from http://www-swiss.ai.mit.edu/~jaffer/SLIB.html
303 2. Put it in Guile's data directory, that is the directory printed when
306 guile-config info pkgdatadir
308 at the shell prompt. This is normally `/usr/local/share/guile', so the
309 directory will normally have full path `/usr/local/share/guile/slib'.
311 3. Start guile as a user with write access to the data directory and type
313 (use-modules (ice-9 slib))
315 at the Guile prompt. This will generate the slibcat catalog next to
318 SLIB's `require' is provided by the Guile module (ice-9 slib).
322 (use-modules (ice-9 slib))
327 Guile Documentation ==================================================
329 If you've never used Scheme before, then the Guile Tutorial
330 (guile-tut.info) is a good starting point. The Guile Reference Manual
331 (guile.info) is the primary documentation for Guile. A copy of the
332 R5RS Scheme specification is included too (r5rs.info).
334 Info format versions of this documentation are installed as part of
335 the normal build process. The texinfo sources are under the doc
336 directory, and other formats like Postscript, PDF, DVI or HTML can be
337 generated from them with Tex and Texinfo tools.
339 The doc directory also includes an example-smob subdirectory which has
340 the example code from the "Defining New Types (Smobs)" chapter of the
343 The Guile WWW page is at
345 http://www.gnu.org/software/guile/guile.html
347 It contains a link to the Guile FAQ.
349 About This Distribution ==============================================
351 Interesting files include:
353 - LICENSE, which contains the exact terms of the Guile license.
354 - COPYING.LESSER, which contains the terms of the GNU Lesser General Public License.
355 - COPYING, which contains the terms of the GNU General Public License.
356 - INSTALL, which contains general instructions for building/installing Guile.
357 - NEWS, which describes user-visible changes since the last release of Guile.
359 Files are usually installed according to the prefix specified to
360 configure, /usr/local by default. Building and installing gives you:
362 Executables, in ${prefix}/bin:
364 guile --- a stand-alone interpreter for Guile. With no arguments, this
365 is a simple interactive Scheme interpreter. It can also be used
366 as an interpreter for script files; see the NEWS file for details.
367 guile-config --- a Guile script which provides the information necessary
368 to link your programs against the Guile library.
369 guile-snarf --- a script to parse declarations in your C code for
370 Scheme-visible C functions, Scheme objects to be used by C code,
373 Libraries, in ${prefix}/lib. Depending on the platform and options
374 given to configure, you may get shared libraries in addition
375 to or instead of these static libraries:
377 libguile.a --- an object library containing the Guile interpreter,
378 You can use Guile in your own programs by linking against this.
379 libguilereadline.a --- an object library containing glue code for the
380 GNU readline library.
382 libguile-srfi-*.a --- various SRFI support libraries
384 Header files, in ${prefix}/include:
386 libguile.h, guile/gh.h, libguile/*.h --- for libguile.
387 guile-readline/readline.h --- for guile-readline.
389 Support files, in ${prefix}/share/guile/<version>:
391 ice-9/* --- run-time support for Guile: the module system,
392 read-eval-print loop, some R4RS code and other infrastructure.
393 oop/* --- the Guile Object-Oriented Programming System (GOOPS)
394 scripts/* --- executable modules, i.e., scheme programs that can be both
395 called as an executable from the shell, and loaded and used as a
396 module from scheme code. See scripts/README for more info.
397 srfi/* --- SRFI support modules. See srfi/README for more info.
399 Automake macros, in ${prefix}/share/aclocal:
403 Documentation in Info format, in ${prefix}/info:
405 guile --- Guile reference manual.
407 guile-tut --- Guile tutorial.
409 GOOPS --- GOOPS reference manual.
411 r5rs --- Revised(5) Report on the Algorithmic Language Scheme.
414 The Guile source tree is laid out as follows:
417 The Guile Scheme interpreter --- both the object library
418 for you to link with your programs, and the executable you can run.
419 ice-9: Guile's module system, initialization code, and other infrastructure.
421 Source for the guile-config script.
423 The glue code for using GNU readline with Guile. This
424 will be build when configure can find a recent enough readline
425 library on your system.
426 doc: Documentation (see above).
428 Git Repository Access ================================================
430 Guile's source code is stored in a Git repository at Savannah. Anyone
431 can access it using `git-clone' from one of the following URLs:
433 git://git.sv.gnu.org/guile.git
434 http://git.sv.gnu.org/r/guile.git
436 Developers with a Savannah SSH account can also access it from:
438 ssh://git.sv.gnu.org/srv/git/guile.git
440 The repository can also be browsed on-line at the following address:
442 http://git.sv.gnu.org/gitweb/?p=guile.git
444 For more information on Git, please see:
448 Please send problem reports to <bug-guile@gnu.org>.