This is 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.

This release is version 1.6.8.  Any bugs found will be addressed by
further bugfix releases numbered 1.6.*.  The next stable Guile release
with significant functional improvements will be version 1.8.0.

In between 1.6.x and 1.8.x, you can follow Guile development in CVS
and in the Guile mailing lists (see ANON-CVS and HACKING).  Guile
builds from the development branch of CVS will have version numbers
1.7.*.

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.

Please send bug reports to bug-guile@gnu.org.

Guile Documentation ==================================================

The doc directory contains the Guile Reference Manual, the Guile
Tutorial, the GOOPS Manual and the Revised^5 Report on Scheme.  The
example-smob directory contains example source code for the "Defining
New Types (Smobs)" chapter.

Additionally, help on specific procedures can be obtained directly
from the Guile prompt.  Type `(help)' to see usage information for the
online documentation system.

The examples directory contains some example scripts, programs and
modules which demonstrate various ways in which Guile can be used.

See the file NEWS to see what is new in this release of Guile.

The Guile WWW page is at

  http://www.gnu.org/software/guile/guile.html

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., 51 Franklin Street, Fifth Floor,
 Boston, MA 02110-1301 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.

Handling of Deprecated Features ======================================

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'.

About This Distribution ==============================================

Interesting files include:

- INSTALL, which contains instructions on building and 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 Guile Reference
	Manual 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 R5RS 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.info     --- The Guile Reference Manual
 guile-tut.info --- The Guile Tutorial
 goops.info     --- Reference Manual and Tutorial for GOOPS, Guile's
		    Object-Oriented Programming System
 r5rs.info      --- The Revised^5 Report on Scheme, the official Scheme
		    language definition.

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.
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).
examples:
        A collection of ready-to-build example scripts, programs and
	modules, which are meant to demonstrate how Guile can be
	used for different needs.  See examples/README for more info.
libltdl:
        A library for generic access to shared libraries from libtool.
oop:    GOOPS source code.
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.
scripts:
        Some useful scripts, packages as `executable scripts'.  See
	scripts/README for details.
srfi:   A lot of SRFI support modules.  See srfi/README for more info.
test-suite:
        Guile's regression test suite.

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/

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.
