*** empty log message ***

[bpt/guile.git] / README

!!! 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, 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.

  Deprecated features are considered harmful; using them is likely a
  bug.  See below for the related notion of `discouraged' features,
  which are OK but have fallen out of favour.

  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-discouraged

  In addition to deprecated features, Guile can also contain things
  that are merely `discouraged'.  It is OK to continue to use these
  features in old code, but new code should avoid them since there are
  better alternatives.

  There is nothing wrong with a discouraged feature per se, but they
  might have strange names, or be non-standard, for example.  Avoiding
  them will make your code better.

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

A C compiler for the build system is required.  The default is
"PATH=/usr/bin:$PATH cc".  If that doesn't suit it can be specified
with the CC_FOR_BUILD variable in the usual way, for instance

    ./configure --host=m68k-unknown-linux-gnu CC_FOR_BUILD=/my/local/gcc

Guile for the build system can be specified similarly with the
GUILE_FOR_BUILD variable, it defaults to just "guile".


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 ==================================================

If you've never used Scheme before, then the Guile Tutorial
(guile-tut.info) is a good starting point.  The Guile Reference Manual
(guile.info) is the primary documentation for Guile.  The Goops object
system is documented separately (goops.info).  A copy of the R5RS
Scheme specification is included too (r5rs.info).

Info format versions of this documentation are installed as part of
the normal build process.  The texinfo sources are under the doc
directory, and other formats like Postscript, PDF, DVI or HTML can be
generated from them with Tex and Texinfo tools.

The doc directory also includes an example-smob subdirectory which has
the example code from the "Defining New Types (Smobs)" chapter of the
reference manual.

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.