* README (Guile Documentation, About This Distribution): updated.

[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.3.4 release.

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

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

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

There is a plan to distribute the reference manual with guile-core,
with much of the text generated from the docstrings in the sources.
The docstrings are likely to be more up-to-date than the reference
manual at present (see libguile/guile-procedures.txt which is
generated by the build process).

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.
- COPYING, which describes the terms under which you may redistribute
  Guile, and explains that there is no warranty.

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.

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.

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.

Automake macros, in ${prefix}/share/aclocal:

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.

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@sourceware.cygnus.com
by sending a message to guile-cvs-subscribe@sourceware.cygnus.com.  Even
better, you can get daily digests of these commit messages by sending
a message to guile-cvs-digest-subscribe@sourceware.cygnus.com.

If you want to subscribe an e-mail address other than the one that
appears in your From: header, say foo@bar.com, send a mail note to
guile-cvs-subscribe-foo=bar.com@sourceware.cygnus.com.


Obtaining Guile ======================================================

The latest official Guile release is available via anonymous FTP from

ftp://ftp.gnu.org/pub/gnu/guile/guile-1.3.4.tar.gz

The mailing list `guile@sourceware.cygnus.com' carries discussions,
questions, and often answers, about Guile.  To subscribe, send mail to
guile-subscribe@sourceware.cygnus.com.  Of course, please send bug
reports (and fixes!) to bug-guile@gnu.org.  Note that one address is
@sourceware.cygnus.com, and the other is at @gnu.org.