-This is not a Guile release; it is a source tree retrieved via
+!!! This is not a Guile release; it is a source tree retrieved via
anonymous CVS or as a nightly snapshot at some random time after the
-Guile 1.4 release.
+Guile 1.4 release. If this were a Guile release, you would not see
+this message. !!! [fixme: zonk on release]
-This is a 1.5 development version of Guile, Project GNU's extension
+This is a 1.7 development version of Guile, Project GNU's extension
language library. Guile is an interpreter for Scheme, packaged as a
library that you can link into your applications to give them their
own scripting language. Guile will eventually support other languages
development versions. Even middle numbers indicate stable versions.
This has been the case since the 1.3.* series.
-The next stable release will be version 1.6.0.
+The next stable release will be version 1.8.0.
Please send bug reports to bug-guile@gnu.org.
+See the LICENSE file for the specific terms that apply to Guile.
+
+
+Additional INSTALL instructions ===========================================
+
+Generic instructions for configuring and compiling Guile can be found
+in the INSTALL file. Guile specific information and configure options
+can be found below, including instructions for installing SLIB.
+
+Guile can use a number of external packages such as `readline' when
+they are available. Guile expects to be able to find these packages
+in the default compiler setup, it does not try to make any special
+arrangements itself. For example, for the `readline' package, Guile
+expects to be able to find the include file <readline/readline.h>,
+without passing any special `-I' options to the compiler.
+
+If you installed an external package, and you used the --prefix
+installation option to install it somewhere else than /usr/local, you
+must arrange for your compiler to find it by default. If that
+compiler is gcc, one convenient way of making such arrangements is to
+use the --with-local-prefix option during installation, naming the
+same directory as you used in the --prefix option of the package. In
+particular, it is not good enough to use the same --prefix option when
+you install gcc and the package; you need to use the
+--with-local-prefix option as well. See the gcc documentation for
+more details.
+
+
+Special Instructions For Some Systems =====================================
+
+We would like Guile to build on all systems using the simple
+instructions above, but it seems that a few systems still need special
+treatment. If you can send us fixes for these problems, we'd be
+grateful.
+
+SunOS 4.1: Guile's shared library support seems to be confused, but
+ hey; shared libraries are confusing. You may need to configure
+ Guile with a command like:
+ ./configure --disable-shared
+ For more information on `--disable-shared', see below, "Flags
+ Accepted by Configure".
+
+HP/UX: GCC 2.7.2 (and maybe other versions) have trouble creating
+ shared libraries if they depend on any non-shared libraries. GCC
+ seems to have other problems as well. To work around this, we
+ suggest you configure Guile to use the system's C compiler:
+ CC=cc ./configure
+
+NetBSD: Perry Metzger says, "Guile will build under NetBSD only using
+ gmake -- the native make will not work. (gmake is in our package
+ system, so this will not be a problem when we packagize 1.3.)"
+
+
+Guile specific flags Accepted by Configure =================================
+
+If you run the configure script with no arguments, it should examine
+your system and set things up appropriately. However, there are a few
+switches specific to Guile you may find useful in some circumstances.
+
+--with-threads --- Build with thread support
+
+ Build a Guile executable and library that supports cooperative
+ threading. If you use this switch, Guile will also build and
+ install the QuickThreads non-preemptive threading library,
+ libqthreads, which you will need to link into your programs after
+ libguile. When you use `guile-config', you will pick up all
+ neccessary linker flags automatically.
+
+ Cooperative threads are not yet thoroughly tested; once they are,
+ they will be enabled by default. The interaction with blocking I/O
+ is pretty ad hoc at the moment. In our experience, bugs in the
+ thread support do not affect you if you don't actually use threads.
+
+--with-modules --- Specify statically linked `modules'
+
+ Guile can dynamically load `plugin modules' during runtime, using
+ facilities provided by libtool. Not all platforms support this,
+ however. On these platforms, you can statically link the plugin
+ modules into libguile when Guile itself is built. XXX - how does
+ one specify the modules?
+
+--enable-deprecated=LEVEL
+
+ Guile may contain features that are `deprecated'. When a feature is
+ deprecated, it means that it is still there and fully functional,
+ but that there is a better way of achieving the same thing, and we'd
+ rather have you use this better way. This allows us to eventually
+ remove the old implementation and helps to keep Guile reasonably
+ clean of historic baggage.
+
+ See the file NEWS for a list of features that are currently
+ deprecated. Each entry will also tell you what you should replace
+ your code with.
+
+ To give you some help with this process, and to encourage (OK,
+ nudge) people to switch to the newer methods, Guile can emit
+ warnings or errors when you use a deprecated feature. There is
+ quite a range of possibilities, from being completely silent to
+ giving errors at link time. What exactly happens is determined both
+ by the value of the `--enable-deprecated' configuration option when
+ Guile was built, and by the GUILE_WARN_DEPRECATED environment
+ variable.
+
+ It works like this:
+
+ When Guile has been configured with `--enable-deprecated=no' (or,
+ equivalently, with `--disable-deprecated') then all deprecated
+ features are omitted from Guile. You will get "undefined
+ reference", "variable unbound" or similar errors when you try to
+ use them.
+
+ When `--enable-deprecated=LEVEL' has been specified (for LEVEL not
+ "no"), LEVEL will be used as the default value of the environment
+ variable GUILE_WARN_DEPRECATED. A value of "yes" is changed to
+ "summary" and "shutup" is changed to "no", however.
+
+ When GUILE_WARN_DEPRECATED has the value "no", nothing special
+ will happen when a deprecated feature is used.
+
+ When GUILE_WARN_DEPRECATED has the value "summary", and a
+ deprecated feature has been used, Guile will print this message at
+ exit:
+
+ Some deprecated features have been used. Set the environment
+ variable GUILE_WARN_DEPRECATED to "detailed" and rerun the
+ program to get more information. Set it to "no" to suppress
+ this message.
+
+ When GUILE_WARN_DEPRECATED has the value "detailed", a detailed
+ warning is emitted immediatly for the first use of a deprecated
+ feature.
+
+ The default is `--enable-deprecated=yes'.
+
+--disable-shared --- Do not build shared libraries.
+--disable-static --- Do not build static libraries.
+
+ Normally, both static and shared libraries will be built if your
+ system supports them.
+
+
+--enable-debug-freelist --- Enable freelist debugging.
+
+ This enables a debugging version of SCM_NEWCELL(), and also
+ registers an extra primitive, the setter
+ `gc-set-debug-check-freelist!'.
+
+ Configure with the --enable-debug-freelist option to enable the
+ gc-set-debug-check-freelist! primitive, and then use:
+
+ (gc-set-debug-check-freelist! #t) # turn on checking of the freelist
+ (gc-set-debug-check-freelist! #f) # turn off checking
+
+ Checking of the freelist forces a traversal of the freelist and a
+ garbage collection before each allocation of a cell. This can slow
+ down the interpreter dramatically, so the setter should be used to
+ turn on this extra processing only when necessary.
+
+
+--enable-debug-malloc --- Enable malloc debugging.
+
+ Include code for debugging of calls to scm_must_malloc/realloc/free.
+
+ Checks that
+
+ 1. objects freed by scm_must_free has been mallocated by scm_must_malloc
+ 2. objects reallocated by scm_must_realloc has been allocated by
+ scm_must_malloc
+ 3. reallocated objects are reallocated with the same what string
+
+ But, most importantly, it records the number of allocated objects of
+ each kind. This is useful when searching for memory leaks.
+
+ A Guile compiled with this option provides the primitive
+ `malloc-stats' which returns an alist with pairs of kind and the
+ number of objects of that kind.
+
+
+--enable-guile-debug --- Include internal debugging functions
+--disable-arrays --- omit array and uniform array support
+--disable-posix --- omit posix interfaces
+--disable-networking --- omit networking interfaces
+--disable-regex --- omit regular expression interfaces
+
+
+Cross building Guile =====================================================
+
+As of guile-1.5.x, the build process uses compiled C files for
+snarfing, and (indirectly, through libtool) for linking, and uses the
+guile executable for generating documentation.
+
+When cross building guile, you first need to configure, build and
+install guile for your build host.
+
+Then, you may configure guile for cross building, eg:
+
+ ./configure --host=i686-pc-cygwin --disable-shared
+
+Two special options for cross building are available:
+
+--with-cc-for-build --- native C compiler, to be used during build
+ defaults to: `PATH=/usr/bin:$PATH cc'
+
+--with-guile-for-build --- native Guile executable, to be used during build
+ defaults to: `guile', assuming you just
+ installed this guile natively.
+
+
+Using Guile Without Installing It =========================================
+
+If you want to run Guile without installing it, set the environment
+variable `GUILE_LOAD_PATH' to a colon-separated list of directories,
+including the directory containing this INSTALL file. If you used a
+separate build directory, you'll need to include the build directory
+in the path as well.
+
+For example, suppose the Guile distribution unpacked into a directory
+called `/home/jimb/guile-snap' (so the full name of this INSTALL file
+would be `/home/jimb/guile-snap/INSTALL'). Then you might say, if
+you're using Bash or any other Bourne shell variant,
+
+ export GUILE_LOAD_PATH=/home/jimb/guile-snap
+
+or if you're using CSH or one of its variants:
+
+ setenv GUILE_LOAD_PATH /home/jimb/guile-snap
+
+You will additionally need to set your `LTDL_LIBRARY_PATH' environment
+variable to the directory in which the compiled SRFI support modules
+are created if you want to use the modules for SRFI-4, SRFI-13 or
+SRFI-14 support. Similar to the example above, this will be,
+
+ export LTDL_LIBRARY_PATH=/home/jimb/guile-snap/srfi/.libs
+
+or if you're using CSH or one of its variants:
+
+ setenv LTDL_LIBRARY_PATH /home/jimb/guile-snap/srfi/.libs
+
+
+Installing SLIB ===========================================================
+
+In order to use SLIB from Guile you basically only need to put the
+`slib' directory _in_ one of the directories on Guile's load path.
+
+The standard installation is:
+
+ 1. Obtain slib from http://www-swiss.ai.mit.edu/~jaffer/SLIB.html
+
+ 2. Put it in Guile's data directory, that is the directory printed when
+ you type
+
+ guile-config info pkgdatadir
+
+ at the shell prompt. This is normally `/usr/local/share/guile', so the
+ directory will normally have full path `/usr/local/share/guile/slib'.
+
+ 3. Start guile as a user with write access to the data directory and type
+
+ (use-modules (ice-9 slib))
+
+ at the Guile prompt. This will generate the slibcat catalog next to
+ the slib directory.
+
+SLIB's `require' is provided by the Guile module (ice-9 slib).
+
+Example:
+
+ (use-modules (ice-9 slib))
+ (require 'primes)
+ (prime? 7)
+
Guile Documentation ==================================================
The doc directory contains a few articles on specific topics and some
It contains a link to the Guile FAQ.
-Guile License ==================================================
-
-The license of Guile consists of the GNU GPL plus a special statement
-giving blanket permission to link with non-free software. This is the
-license statement as found in any individual file that it applies to:
-
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2, or (at your option)
- any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public License
- along with this software; see the file COPYING. If not, write to
- the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
- Boston, MA 02111-1307 USA
-
- As a special exception, the Free Software Foundation gives permission
- for additional uses of the text contained in its release of GUILE.
-
- The exception is that, if you link the GUILE library with other files
- to produce an executable, this does not by itself cause the
- resulting executable to be covered by the GNU General Public License.
- Your use of that executable is in no way restricted on account of
- linking the GUILE library code into it.
-
- This exception does not however invalidate any other reasons why
- the executable file might be covered by the GNU General Public License.
-
- This exception applies only to the code released by the
- Free Software Foundation under the name GUILE. If you copy
- code from other Free Software Foundation releases into a copy of
- GUILE, as the General Public License permits, the exception does
- not apply to the code that you add in this way. To avoid misleading
- anyone as to the status of such modified files, you must delete
- this exception notice from them.
-
- If you write modifications of your own for GUILE, it is your choice
- whether to permit this exception to apply to your modifications.
- If you do not wish that, delete this exception notice.
-
About This Distribution ==============================================
Interesting files include:
-- INSTALL, which contains instructions on building and installing Guile.
+- LICENSE, which contains the exact terms of the Guile license.
+- COPYING, which contains the terms of the GNU General Public License.
+- INSTALL, which contains general instructions for building/installing Guile.
- NEWS, which describes user-visible changes since the last release of Guile.
Files are usually installed according to the prefix specified to
Executables, in ${prefix}/bin:
-guile --- a stand-alone interpreter for Guile. With no arguments, this
- is a simple interactive Scheme interpreter. It can also be used
- as an interpreter for script files; see the NEWS file for details.
-guile-config --- a Guile script which provides the information necessary
- to link your programs against the Guile library.
-guile-snarf --- a script to parse declarations in your C code for
- Scheme-visible C functions, Scheme objects to be used by C code,
- etc.
+ guile --- a stand-alone interpreter for Guile. With no arguments, this
+ is a simple interactive Scheme interpreter. It can also be used
+ as an interpreter for script files; see the NEWS file for details.
+ guile-config --- a Guile script which provides the information necessary
+ to link your programs against the Guile library.
+ guile-snarf --- a script to parse declarations in your C code for
+ Scheme-visible C functions, Scheme objects to be used by C code,
+ etc.
+ guile-tools --- a wrapper to invoke the executable modules in
+ subdirectory `scripts' (also installed).
Libraries, in ${prefix}/lib. Depending on the platform and options
given to configure, you may get shared libraries in addition
to or instead of these static libraries:
-
-libguile.a --- an object library containing the Guile interpreter,
- You can use Guile in your own programs by linking against this.
-libqthreads.a --- an object library containing the QuickThreads
- primitives. If you enabled thread support when you configured
- Guile, you will need to link your code against this too.
-libguilereadline.a --- an object library containing glue code for the
- GNU readline library. See NEWS for instructions on how to enable
- readline for your personal use.
+
+ libguile.a --- an object library containing the Guile interpreter,
+ You can use Guile in your own programs by linking against this.
+ libqthreads.a --- an object library containing the QuickThreads
+ primitives. If you enabled thread support when you configured
+ Guile, you will need to link your code against this too.
+ libguilereadline.a --- an object library containing glue code for the
+ GNU readline library. See NEWS for instructions on how to enable
+ readline for your personal use.
+ libguile-srfi-*.a --- various SRFI support libraries
Header files, in ${prefix}/include:
-libguile.h, guile/gh.h, libguile/*.h --- for libguile.
-guile-readline/readline.h --- for guile-readline.
+ libguile.h, guile/gh.h, libguile/*.h --- for libguile.
+ guile-readline/readline.h --- for guile-readline.
Support files, in ${prefix}/share/guile/<version>:
-ice-9/* --- run-time support for Guile: the module system,
- read-eval-print loop, some R4RS code and other infrastructure.
+ ice-9/* --- run-time support for Guile: the module system,
+ read-eval-print loop, some R4RS code and other infrastructure.
+ oop/* --- the Guile Object-Oriented Programming System (GOOPS)
+ scripts/* --- executable modules, i.e., scheme programs that can be both
+ called as an executable from the shell, and loaded and used as a
+ module from scheme code. See scripts/README for more info.
+ srfi/* --- SRFI support modules. See srfi/README for more info.
Automake macros, in ${prefix}/share/aclocal:
-guile.m4
+ guile.m4
Documentation in Info format, in ${prefix}/info:
-data-rep.info --- an essay on how to write C code that works with
- Guile Scheme values.
+ guile --- Guile reference manual.
+
+ guile-tut --- Guile tutorial.
+
+ GOOPS --- GOOPS reference manual.
+
+ r5rs --- Revised(5) Report on the Algorithmic Language Scheme.
+
The Guile source tree is laid out as follows: