1This is version 3.0 of Guile, Project GNU's extension language library.
2Guile is an implementation of the Scheme programming language, packaged
3as a library that can be linked into applications to give them their own
4extension language. Guile supports other languages as well, giving
5users of Guile-based applications a choice of languages.
6
7Please send bug reports to bug-guile@gnu.org.
8
9See the LICENSE file for the specific terms that apply to Guile. Note
10that for any copyright year range specified as YYYY-ZZZZ in this
11package, the range specifies every single year in that closed interval.
12
13
14Additional INSTALL instructions ===========================================
15
16Generic instructions for configuring and compiling Guile can be found
17in the INSTALL file. Guile specific information and configure options
18can be found below, including instructions for installing SLIB.
19
20Guile depends on the following external libraries.
21- libgmp
22- libiconv
23- libintl
24- libltdl
25- libunistring
26- libgc
27- libffi
28It will also use the libreadline library if it is available.
29
30There is a corresponding `--with-XXX-prefix' option for each of these
31libraries (except for libgc and libffi which use `pkg-config', see
32below) that you can use when invoking ./configure, if you have these
33libraries installed in a location other than the standard places (/usr
34and /usr/local).
35
36These options are provided by the Gnulib `havelib' module, and details
37of how they work are documented in `Searching for Libraries' in the
38Gnulib manual (http://www.gnu.org/software/gnulib/manual). The extent
39to which they work on a given OS depends on whether that OS supports
40encoding full library path names in executables (aka `rpath'). Also
41note that using these options, and hence hardcoding full library path
42names (where that is supported), makes it impossible to later move the
43built executables and libraries to an installation location other than
44the one that was specified at build time.
45
46Another possible approach is to set CPPFLAGS and LDFLAGS on the
47configure command-line, so that they include -I options for all the
48non-standard places where you have installed header files and -L
49options for all the non-standard places where you have installed
50libraries. This will allow configure and make to find those headers
51and libraries during the build. E.g.:
52
53 ../configure [...] CPPFLAGS='-I/my/include' LDFLAGS='-L/my/lib'
54
55The locations found will not be hardcoded into the build executables and
56libraries, so with this approach you will probably also need to set
57LD_LIBRARY_PATH correspondingly, to allow Guile to find the necessary
58libraries again at runtime.
59
60
61Required External Packages ================================================
62
63Guile requires the following external packages:
64
65 - GNU MP, at least version 4.2
66
67 GNU MP is used for bignum arithmetic. It is available from
68 http://gmplib.org/ .
69
70 - libltdl from GNU Libtool, at least version 1.5.6
71
72 libltdl is used for loading extensions at run-time. It is
73 available from http://www.gnu.org/software/libtool/ .
74
75 - GNU libunistring, at least version 0.9.3
76
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/ .
80
81 - libgc, at least version 7.2
82
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/ .
86
87 - libffi
88
89 libffi provides a "foreign function interface", used by the
90 `(system foreign)' module. It is available from
91 http://sourceware.org/libffi/ .
92
93 - pkg-config
94
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:
99
100 PKG_CONFIG_PATH=/path/to/libgc/lib/pkgconfig:/path/to/libffi/lib/pkgconfig
101
102 Alternatively, when pkg-config is not installed, you can work around
103 this by setting some variables as part of the configure
104 command-line:
105
106 - PKG_CONFIG=true
107
108 - BDW_GC_CFLAGS=<compile flags for picking up libgc headers>
109
110 - BDW_GC_LIBS=<linker flags for picking up the libgc library>
111
112 Note that because you're bypassing all pkg-config checks, you will
113 also have to specify libffi flags as well:
114
115 - LIBFFI_CFLAGS=<compile flags for picking up libffi headers>
116
117 - LIBFFI_LIBS=<linker flags for picking up the libffi library>
118
119
120When building from a Git checkout, these additional packages are needed:
121
122 - GNU Autoconf
123 - GNU Automake
124 - GNU Libtool
125 - Flex
126 - GNU Gettext
127 - GNU Texinfo
128
129
130Special Instructions For Some Systems =====================================
131
132We would like Guile to build on all systems using the simple
133instructions above, but it seems that a few systems still need special
134treatment. If you can send us fixes for these problems, we'd be
135grateful.
136
137FreeBSD 11.0:
138 For a build supporting threads, please `pkg install' the following
139 - pkgconf : provides pkg-config
140 - gmake : /usr/bin/make does not work
141 - boehm-gc-threaded : needed for threaded support
142
143 Configure as:
144
145 ./configure --with-bdw-gc=bdw-gc-threaded
146
147 Alternately if you want a Guile without threads, then install boehm-gc
148 and configure as:
149
150 ./configure --without-threads
151
152Guile specific flags Accepted by Configure =================================
153
154If you run the configure script with no arguments, it should examine
155your system and set things up appropriately. However, there are a few
156switches specific to Guile you may find useful in some circumstances.
157
158--without-threads --- Build without thread support
159
160 Build a Guile executable and library that supports multi-threading.
161
162 The default is to enable threading support when your operating
163 system offsers 'POSIX threads'. When you do not want threading, use
164 `--without-threads'.
165
166--enable-deprecated=LEVEL
167
168 Guile may contain features that are `deprecated'. When a feature is
169 deprecated, it means that it is still there, but that there is a
170 better way of achieving the same thing, and we'd rather have you use
171 this better way. This allows us to eventually remove the old
172 implementation and helps to keep Guile reasonably clean of historic
173 baggage.
174
175 See the file NEWS for a list of features that are currently
176 deprecated. Each entry will also tell you what you should replace
177 your code with.
178
179 To give you some help with this process, and to encourage (OK,
180 nudge) people to switch to the newer methods, Guile can emit
181 warnings or errors when you use a deprecated feature. There is
182 quite a range of possibilities, from being completely silent to
183 giving errors at link time. What exactly happens is determined both
184 by the value of the `--enable-deprecated' configuration option when
185 Guile was built, and by the GUILE_WARN_DEPRECATED environment
186 variable.
187
188 It works like this:
189
190 When Guile has been configured with `--enable-deprecated=no' (or,
191 equivalently, with `--disable-deprecated') then all deprecated
192 features are omitted from Guile. You will get "undefined
193 reference", "variable unbound" or similar errors when you try to
194 use them.
195
196 When `--enable-deprecated=LEVEL' has been specified (for LEVEL not
197 "no"), LEVEL will be used as the default value of the environment
198 variable GUILE_WARN_DEPRECATED. A value of "yes" is changed to
199 "summary" and "shutup" is changed to "no", however.
200
201 When GUILE_WARN_DEPRECATED has the value "no", nothing special
202 will happen when a deprecated feature is used.
203
204 When GUILE_WARN_DEPRECATED has the value "summary", and a
205 deprecated feature has been used, Guile will print this message at
206 exit:
207
208 Some deprecated features have been used. Set the environment
209 variable GUILE_WARN_DEPRECATED to "detailed" and rerun the
210 program to get more information. Set it to "no" to suppress
211 this message.
212
213 When GUILE_WARN_DEPRECATED has the value "detailed", a detailed
214 warning is emitted immediatly for the first use of a deprecated
215 feature.
216
217 The default is `--enable-deprecated=yes'.
218
219 In addition to setting GUILE_WARN_DEPRECATED in the environment, you
220 can also use (debug-enable 'warn-deprecated) and (debug-disable
221 'warn-deprecated) to enable and disable the detailed messaged at run
222 time.
223
224 Additionally, if your toolchain is new enough, you will receive
225 warnings at link time if you have a Guile extension that uses
226 deprecated functions provided by Guile.
227
228--disable-shared --- Do not build shared libraries.
229--disable-static --- Do not build static libraries.
230
231 Normally, both static and shared libraries will be built if your
232 system supports them.
233
234--enable-debug-freelist --- Enable freelist debugging.
235
236 This enables a debugging version of scm_cell and scm_double_cell,
237 and also registers an extra primitive, the setter
238 `gc-set-debug-check-freelist!'.
239
240 Configure with the --enable-debug-freelist option to enable the
241 gc-set-debug-check-freelist! primitive, and then use:
242
243 (gc-set-debug-check-freelist! #t) # turn on checking of the freelist
244 (gc-set-debug-check-freelist! #f) # turn off checking
245
246 Checking of the freelist forces a traversal of the freelist and a
247 garbage collection before each allocation of a cell. This can slow
248 down the interpreter dramatically, so the setter should be used to
249 turn on this extra processing only when necessary.
250
251--enable-debug-malloc --- Enable malloc debugging.
252
253 Include code for debugging of calls to scm_malloc, scm_realloc, etc.
254
255 It records the number of allocated objects of each kind. This is
256 useful when searching for memory leaks.
257
258 A Guile compiled with this option provides the primitive
259 `malloc-stats' which returns an alist with pairs of kind and the
260 number of objects of that kind.
261
262--enable-guile-debug --- Include internal debugging functions
263--disable-posix --- omit posix interfaces
264--disable-networking --- omit networking interfaces
265--disable-regex --- omit regular expression interfaces
266
267
268Cross building Guile =====================================================
269
270As of Guile 3.0.x, the build process produces a library, libguile-3.0,
271along with Guile "object files" containing bytecode to be interpreted by
272Guile's virtual machine. The bytecode format depends on the endianness
273and word size of the host CPU.
274
275Thus, when cross building Guile, you first need to configure, build and
276install it for your build host.
277
278Then, you may configure Guile for cross building:
279
280 ./configure --host=i686-pc-cygwin --disable-shared
281
282A C compiler for the build system is required. If that doesn't suit it
283can be specified with the CC_FOR_BUILD variable in the usual way, for
284instance:
285
286 ./configure --host=m68k-unknown-linux-gnu CC_FOR_BUILD=/my/local/gcc
287
288Guile for the build system can be specified similarly with the
289GUILE_FOR_BUILD variable, which defaults to whatever `guile' executable
290is found in $PATH. It must have the exact same version has the Guile
291that you intend to cross-build.
292
293
294Using Guile Without Installing It =========================================
295
296The "meta/" subdirectory of the Guile sources contains a script called
297"guile" that can be used to run the Guile that has just been built. Note
298that this is not the same "guile" as the one that is installed; this
299"guile" is a wrapper script that sets up the environment appropriately,
300then invokes the Guile binary.
301
302You may also build external packages against an uninstalled Guile build
303tree. The "uninstalled-env" script in the "meta/" subdirectory will set
304up an environment with a path including "meta/", a modified dynamic
305linker path, a modified PKG_CONFIG_PATH, etc.
306
307For example, you can enter this environment via invoking
308
309 meta/uninstalled-env bash
310
311Within that shell, other packages should be able to build against
312uninstalled Guile.
313
314
315Installing SLIB ===========================================================
316
317In order to use SLIB from Guile you basically only need to put the
318`slib' directory _in_ one of the directories on Guile's load path.
319
320The standard installation is:
321
322 1. Obtain slib from http://www-swiss.ai.mit.edu/~jaffer/SLIB.html
323
324 2. Put it in Guile's data directory, that is the directory printed when
325 you type
326
327 guile-config info pkgdatadir
328
329 at the shell prompt. This is normally `/usr/local/share/guile', so the
330 directory will normally have full path `/usr/local/share/guile/slib'.
331
332 3. Start guile as a user with write access to the data directory and type
333
334 (use-modules (ice-9 slib))
335
336 at the Guile prompt. This will generate the slibcat catalog next to
337 the slib directory.
338
339SLIB's `require' is provided by the Guile module (ice-9 slib).
340
341Example:
342
343 (use-modules (ice-9 slib))
344 (require 'primes)
345 (prime? 7)
346
347
348Guile Documentation ==================================================
349
350The Guile Reference Manual (guile.info) is the primary documentation for
351Guile. A copy of the R5RS Scheme specification is included too
352(r5rs.info).
353
354Info format versions of this documentation are installed as part of
355the normal build process. The texinfo sources are under the doc
356directory, and other formats like Postscript, PDF, DVI or HTML can be
357generated from them with Tex and Texinfo tools.
358
359The doc directory also includes an example-smob subdirectory which has
360the example code from the "Defining New Types (Smobs)" chapter of the
361reference manual.
362
363The Guile WWW page is at
364
365 http://www.gnu.org/software/guile/guile.html
366
367It contains a link to the Guile FAQ.
368
369About This Distribution ==============================================
370
371Interesting files include:
372
373- LICENSE, which contains the exact terms of the Guile license.
374- COPYING.LESSER, which contains the terms of the GNU Lesser General Public License.
375- COPYING, which contains the terms of the GNU General Public License.
376- INSTALL, which contains general instructions for building/installing Guile.
377- NEWS, which describes user-visible changes since the last release of Guile.
378
379Files are usually installed according to the prefix specified to
380configure, /usr/local by default. Building and installing gives you:
381
382Executables, in ${prefix}/bin:
383
384 guile --- a stand-alone interpreter for Guile. With no arguments, this
385 is a simple interactive Scheme interpreter. It can also be used
386 as an interpreter for script files; see the NEWS file for details.
387 guile-config --- a Guile script which provides the information necessary
388 to link your programs against the Guile library.
389 guile-snarf --- a script to parse declarations in your C code for
390 Scheme-visible C functions, Scheme objects to be used by C code,
391 etc.
392
393Libraries, in ${prefix}/lib. Depending on the platform and options
394 given to configure, you may get shared libraries in addition
395 to or instead of these static libraries:
396
397 libguile.a --- an object library containing the Guile interpreter,
398 You can use Guile in your own programs by linking against this.
399 libguilereadline.a --- an object library containing glue code for the
400 GNU readline library.
401
402 libguile-srfi-*.a --- various SRFI support libraries
403
404Header files, in ${prefix}/include:
405
406 libguile.h, guile/gh.h, libguile/*.h --- for libguile.
407 guile-readline/readline.h --- for guile-readline.
408
409Support files, in ${prefix}/share/guile/<version>:
410
411 ice-9/* --- run-time support for Guile: the module system,
412 read-eval-print loop, some R4RS code and other infrastructure.
413 oop/* --- the Guile Object-Oriented Programming System (GOOPS)
414 scripts/* --- executable modules, i.e., scheme programs that can be both
415 called as an executable from the shell, and loaded and used as a
416 module from scheme code. See scripts/README for more info.
417 srfi/* --- SRFI support modules. See srfi/README for more info.
418
419Automake macros, in ${prefix}/share/aclocal:
420
421 guile.m4
422
423Documentation in Info format, in ${prefix}/info:
424
425 guile --- Guile reference manual.
426
427 GOOPS --- GOOPS reference manual.
428
429 r5rs --- Revised(5) Report on the Algorithmic Language Scheme.
430
431
432The Guile source tree is laid out as follows:
433
434libguile:
435 The Guile Scheme interpreter --- both the object library
436 for you to link with your programs, and the executable you can run.
437module: Scheme libraries included with Guile.
438guile-readline:
439 The glue code for using GNU readline with Guile. This
440 will be build when configure can find a recent enough readline
441 library on your system.
442doc: Documentation (see above).
443
444Git Repository Access ================================================
445
446Guile's source code is stored in a Git repository at Savannah. Anyone
447can access it using `git-clone' from one of the following URLs:
448
449 git://git.sv.gnu.org/guile.git
450 http://git.sv.gnu.org/r/guile.git
451
452Developers with a Savannah SSH account can also access it from:
453
454 ssh://git.sv.gnu.org/srv/git/guile.git
455
456The repository can also be browsed on-line at the following address:
457
458 http://git.sv.gnu.org/gitweb/?p=guile.git
459
460For more information on Git, please see:
461
462 http://git.or.cz/
463
464Please send problem reports to <bug-guile@gnu.org>.
465