-This is a nightly snapshot of Guile, a portable, embeddable Scheme
-implementation written in C. Guile provides a machine independent
-execution platform that can be linked in as a library when building
-extensible programs.
-
-Please send bug reports to bug-guile@prep.ai.mit.edu.
-
-
-Important Facts About Snapshots ======================================
-
-Please keep in mind that these sources are strictly experimental; they
-will usually not be well-tested, and may not even compile on some
-systems. They may contain interfaces which will change. They will
-usually not be of sufficient quality for use by people not comfortable
-hacking the innards of Guile. Caveat!
-
-However, we're providing them anyway for several reasons. We'd like
-to encourage people to get involved in developing Guile. People
-willing to use the bleeding edge of development can get earlier access
-to new, experimental features. Patches submitted relative to recent
-snapshots will be easier for us to evaluate and install, since the
-patch's original sources will be closer to what we're working with.
-And it allows us to start testing features earlier.
-
-Nightly snapshots of the Guile development sources are available via
-anonymous FTP from ftp.red-bean.com, as /pub/guile/guile-snap.tar.gz.
-
-Via the web, that's: ftp://ftp.red-bean.com/pub/guile/guile-snap.tar.gz
-For getit, that's: ftp.red-bean.com:/pub/guile/guile-snap.tar.gz
-
-
-The latest official Guile release is available via anonymous FTP from
-prep.ai.mit.edu, as /pub/gnu/guile-1.2.tar.gz.
-
-Via the web, that's: ftp://prep.ai.mit.edu/pub/gnu/guile-1.2.tar.gz
-For getit, that's: prep.ai.mit.edu:/pub/gnu/guile-1.2.tar.gz
-
-The mailing list `guile@cygnus.com' carries discussions, questions,
-and often answers, about Guile. To subscribe, send mail to
-guile-request@cygnus.com. Of course, please send bug reports (and
-fixes!) to bug-guile@prep.ai.mit.edu.
-
-
-About This Distribution ==============================================
-
-Building and installing this distribution gives you:
-guile --- a stand-alone interpreter for Guile, usually installed in
- /usr/local/bin. 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.
-libguile.a --- an object library containing the Guile interpreter,
- usually installed in /usr/local/lib. You can use Guile in
- your own programs by linking against this.
-libqt.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.
-<libguile.h>, <libguile/*.h> --- header files for libguile.a, usually
- installed in /usr/local/include.
-
-
-Interesting files include:
-- INSTALL, which contains instructions on building and installing Guile.
-- NEWS, which describes user-visible changes since the last release of Guile.
-- COPYING, which describes the terms under which you may redistribute
- Guile, and explains that there is no warranty.
-
-The Guile source tree is laid out as follows:
-
-libguile:
- The Guile Scheme interpreter --- both the object library
- for you to link with your programs, and the executable you can run.
-ice-9: Guile's module system, initialization code, and other infrastructure.
-
-qt: A cooperative threads package from Washington University,
- which Guile can use. If you configure Guile with the
- --with-threads flag, you will need to link against the -lqt
- library, found in this directory. Qt is under a separate
- copyright; see `qt/README' for more details.
-
-(The present release doesn't include any documentation; the Guile
-manual is incomplete, and is currently being revised.)
-
-
-Hacking It Yourself ==================================================
-
-As distributed, Guile needs only an ANSI C compiler and a Unix system
-to compile. However, Guile's makefiles, configuration scripts, and a
-few other files are automatically generated, not written by hand. If
-you want to make changes to the system (which we encourage!) you will
-find it helpful to have the tools we use to develop Guile. They
-are the following:
-
-Autoconf 2.12 --- a system for automatically generating `configure'
- scripts from templates which list the non-portable features a
- program would like to use. Available in
- "ftp://prep.ai.mit.edu/pub/gnu".
-
-Automake 1.1p --- a system for automatically generating Makefiles that
- conform to the (rather Byzantine) GNU coding standards. The
- nice thing is that it takes care of hairy targets like 'make
- dist' and 'make distclean', and automatically generates
- Makefile dependencies. Automake is available in
- "ftp://ftp.cygnus.com/pub/tromey".
-
- Before using automake, you may need to copy `threads.m4' and
- `guile.m4' from the top directory of the Guile core disty to
- `/usr/local/share/aclocal.
-
-libtool 0.9h --- a system for managing the zillion hairy options needed
- on various systems to produce shared libraries. Available in
- "ftp://alpha.gnu.ai.mit.edu/gnu".
-
-You are lost in a little maze of automatically generated files, all
-different.
->
-
-
-Authors And Contributors =============================================
-
-Many people have generously contributed to Guile. However, any errors
-are the responsibility of the primary Guile maintainer, Jim Blandy.
-
-Mikael Djurfeldt designed and implemented:
-* the source-level debugging support (although the debugger's user
- interface is not yet complete)
-* stack overflow detection,
-* the GDB patches to support debugging mixed Scheme/C code,
-* the original implementation of weak hash tables,
-* enhancements to the `threads' interface (based on Anthony Green's
- work), and
-* detection of circular references during printing.
-
-Mark Galassi contributed the Guile high-level functions (gh_*), and
-wrote the guile-programmer and guile-user manuals. (These are in the
-process of revision.)
-
-Anthony Green wrote the original version of `threads', the interface
-between Guile and qt.
-
-Gary Houston wrote much of the Unix system call support, including the
-socket support, and did a lot of work on the error handling code.
-
-Tom Lord librarified SCM, yielding Guile. He wrote Guile's operating
-system, Ice-9, and connected Guile to Tcl/Tk and the `rx' regular
-expression matcher.
-
-Aubrey Jaffer seriously tuned performance and added features. He
-designed many hairy but beautiful parts of the tag system and
-evaluator.
-
-George Carrette wrote SIOD, a stand-alone scheme interpreter.
-Although most of this code as been rewritten or replaced over time,
-the garbage collector from SIOD is still an important part of Guile.
+!!! 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. If this were a Guile release, you would not see
+this message. !!! [fixme: zonk on release]
+
+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
+as well, giving users of Guile-based applications a choice of
+languages.
+
+Guile versions with an odd middle number, i.e. 1.5.* are unstable
+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.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
+examples, including data-rep.texi which describes the internal
+representation of data types in Guile. The example-smob directory
+contains example source code for the "Defining New Types (Smobs)" chapter.
+
+The incomplete Guile reference manual is available at
+
+ ftp://ftp.red-bean.com/pub/guile/snapshots/guile-doc-snap.tar.gz
+
+Neil Jerram is working on the new reference manual, which will be
+distributed with guile-core. The new manual will be synchronized with
+the docstrings in the sources. Until then, please be aware that the
+docstrings are likely to be more up-to-date than the old reference
+manual (use `(help)' or see libguile/guile-procedures.txt which is
+generated by the build process).
+
+The Guile WWW page is at
+
+ http://www.gnu.org/software/guile/guile.html
+
+It contains a link to the Guile FAQ.
+
+About This Distribution ==============================================
+
+Interesting files include:
+
+- 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
+configure, /usr/local by default. Building and installing gives you:
+
+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-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-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.
+
+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.
+ 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
+
+Documentation in Info format, in ${prefix}/info:
+
+ 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:
+
+libguile:
+ The Guile Scheme interpreter --- both the object library
+ for you to link with your programs, and the executable you can run.
+ice-9: Guile's module system, initialization code, and other infrastructure.
+guile-config:
+ Source for the guile-config script.
+qt: A cooperative threads package from the University of Washington,
+ which Guile can use. If you configure Guile with the
+ --with-threads flag, you will need to link against the -lqt
+ library, found in this directory. Qt is under a separate
+ copyright; see `qt/README' for more details.
+guile-readline:
+ The glue code for using GNU readline with Guile. This
+ will be build when configure can find a recent enough readline
+ library on your system.
+doc: Documentation (see above).
+
+Anonymous CVS Access and FTP snapshots ===============================
+
+We make the developers' working Guile sources available via anonymous
+CVS, and by nightly snapshots, accessible via FTP. See the files
+`ANON-CVS' and `SNAPSHOTS' for details.
+
+If you would like to receive mail when people commit changes to the
+Guile CVS repository, you can subscribe to guile-cvs@gnu.org by the
+Mailman mailing list interface at
+
+ <http://mail.gnu.org/mailman/listinfo/guile-cvs>
+
+
+Obtaining Guile ======================================================
+
+The latest official Guile release is available via anonymous FTP from
+
+ftp://ftp.gnu.org/pub/gnu/guile/guile-1.4.tar.gz
+
+The mailing list `guile-user@gnu.org' carries discussions, questions,
+and often answers, about Guile. To subscribe, use the Mailman mailing
+list interface at <http://mail.gnu.org/mailman/listinfo/guile-user>
+Of course, please send bug reports (and fixes!) to bug-guile@gnu.org.
HCoop / bpt / guile.git / blobdiff