README

   1 This is release 1.3 of Guile, Project GNU's extension language
   2 library.  Guile is an interpreter for Scheme, packaged as a library
   3 that you can link into your applications to give them their own
   4 scripting language.  Guile will eventually support other languages as
   5 well, giving users of Guile-based applications a choice of languages.
   6
   7 Please send bug reports to bug-guile@gnu.org.
   8
   9 About This Distribution ==============================================
  10
  11 Building and installing this distribution gives you:
  12 guile --- a stand-alone interpreter for Guile, usually installed in
  13         /usr/local/bin.  With no arguments, this is a simple
  14         interactive Scheme interpreter.  It can also be used as an
  15         interpreter for script files; see the NEWS file for details.
  16 guile-config --- a Guile script which provides the information necessary
  17         to link your programs against the Guile library.
  18 guile-snarf --- a script to parse declarations in your C code for
  19         Scheme-visible C functions, Scheme objects to be used by C code, etc.
  20 libguile.a --- an object library containing the Guile interpreter,
  21         usually installed in /usr/local/lib.  You can use Guile in
  22         your own programs by linking against this.
  23 libqthreads.a --- an object library containing the QuickThreads
  24         primitives.  If you enabled thread support when you configured
  25         Guile, you will need to link your code against this too.
  26 <libguile.h>, <guile/gh.h>, <libguile/*.h> --- header files for
  27         libguile.a, usually installed in /usr/local/include.
  28 ice-9, ice-9/*.scm --- run-time support for Guile: the module
  29         system, read-eval-print loop, some R4RS code and other
  30         infrastructure.  Usually installed in
  31         /usr/local/share/guile/<version>.
  32 data-rep.info --- An essay on how to write C code that works with
  33         Guile Scheme values.
  34
  35 Interesting files include:
  36 - INSTALL, which contains instructions on building and installing Guile.
  37 - NEWS, which describes user-visible changes since the last release of Guile.
  38 - COPYING, which describes the terms under which you may redistribute
  39   Guile, and explains that there is no warranty.
  40
  41 The Guile source tree is laid out as follows:
  42
  43 libguile:
  44         The Guile Scheme interpreter --- both the object library
  45         for you to link with your programs, and the executable you can run.
  46 ice-9:  Guile's module system, initialization code, and other infrastructure.
  47 guile-config:
  48         Source for the guile-config script.
  49 qt:     A cooperative threads package from the University of Washington,
  50         which Guile can use.  If you configure Guile with the
  51         --with-threads flag, you will need to link against the -lqt
  52         library, found in this directory.  Qt is under a separate
  53         copyright; see `qt/README' for more details.
  54 doc:    Some preliminary documentation for Guile.  The real Guile
  55         manual is incomplete, and is currently being revised.
  56 doc/example-smob: Sample code, discussed in the preliminary
  57         documentation above, for a program that extends Guile with a
  58         new data type, and functions that operate on it.
  59
  60
  61 Anonymous CVS Access and FTP snapshots ===============================
  62
  63 We make the developers' working Guile sources available via anonymous
  64 CVS, and by nightly snapshots, accessible via FTP.  See the files
  65 `ANON-CVS' and `SNAPSHOTS' for details.
  66
  67 If you would like to receive mail when people commit changes to the
  68 Guile CVS repository, you can subscribe to guile-cvs@egcs.cygnus.com
  69 by sending a message to guile-cvs-subscribe@egcs.cygnus.com.  Even
  70 better, you can get daily digests of these commit messages by sending
  71 a message to guile-cvs-digest-subscribe@egcs.cygnus.com.
  72
  73 If you want to subscribe an e-mail address other than the one that
  74 appears in your From: header, say foo@bar.com, send a mail note to
  75 guile-cvs-subscribe-foo=bar.com@egcs.cygnus.com.
  76
  77
  78 Hacking It Yourself ==================================================
  79
  80 As distributed, Guile needs only an ANSI C compiler and a Unix system
  81 to compile.  However, Guile's makefiles, configuration scripts, and a
  82 few other files are automatically generated, not written by hand.  If
  83 you want to make changes to the system (which we encourage!) you will
  84 find it helpful to have the tools we use to develop Guile.  They
  85 are the following:
  86
  87 Autoconf 2.13 --- a system for automatically generating `configure'
  88         scripts from templates which list the non-portable features a
  89         program would like to use.  Available in
  90         "ftp://ftp.gnu.org/pub/gnu/autoconf"
  91
  92 Automake 1.4 --- a system for automatically generating Makefiles that
  93         conform to the (rather Byzantine) GNU coding standards.  The
  94         nice thing is that it takes care of hairy targets like 'make
  95         dist' and 'make distclean', and automatically generates
  96         Makefile dependencies.  Automake is available in
  97         "ftp://ftp.gnu.org/pub/gnu/automake"
  98
  99         Before using automake, you may need to copy `threads.m4' and
 100         `guile.m4' from the top directory of the Guile core disty to
 101         `/usr/local/share/aclocal.
 102
 103 libtool 1.2f --- a system for managing the zillion hairy options needed
 104         on various systems to produce shared libraries.  Available in
 105         "ftp://alpha.gnu.org/gnu".
 106
 107 You are lost in a little maze of automatically generated files, all
 108 different.
 109 >
 110
 111
 112 Obtaining Guile ======================================================
 113
 114 The latest official Guile release is available via anonymous FTP from
 115 prep.ai.mit.edu, as /pub/gnu/guile-1.3.tar.gz.
 116
 117 Via the web, that's:  ftp://prep.ai.mit.edu/pub/gnu/guile-1.3.tar.gz
 118 For getit, that's:    prep.ai.mit.edu:/pub/gnu/guile-1.3.tar.gz
 119
 120 The mailing list `guile@cygnus.com' carries discussions, questions,
 121 and often answers, about Guile.  To subscribe, send mail to
 122 guile-request@cygnus.com.  Of course, please send bug reports (and
 123 fixes!) to bug-guile@gnu.org.  Note that one address is @cygnus.com,
 124 and the other is at @gnu.org.
 125
 126
 127 Authors And Contributors =============================================
 128
 129 Many people have generously contributed to Guile.  However, any errors
 130 are the responsibility of the primary Guile maintainer, Jim Blandy.
 131
 132 Mikael Djurfeldt designed and implemented:
 133 * the source-level debugging support (although the debugger's user
 134   interface is not yet complete)
 135 * stack overflow detection,
 136 * the GDB patches to support debugging mixed Scheme/C code,
 137 * the original implementation of weak hash tables,
 138 * enhancements to the `threads' interface (based on Anthony Green's
 139   work), and
 140 * detection of circular references during printing.
 141
 142 Mark Galassi contributed the Guile high-level functions (gh_*), and
 143 wrote the guile-programmer and guile-user manuals.  (These are in the
 144 process of revision.)
 145
 146 Anthony Green wrote the original version of `threads', the interface
 147 between Guile and qt.
 148
 149 Gary Houston wrote much of the Unix system call support, including the
 150 socket support, and did a lot of work on the error handling code.
 151
 152 Tom Lord librarified SCM, yielding Guile.  He wrote Guile's operating
 153 system, Ice-9, and connected Guile to Tcl/Tk and the `rx' regular
 154 expression matcher.
 155
 156 Aubrey Jaffer is the author of SCM upon which Guile is based.  Guile
 157 started from SCM version 4e1 in November -94 and is still largely
 158 composed of the original SCM code.
 159
 160 George Carrette wrote SIOD, a stand-alone scheme interpreter.
 161 Although most of this code as been rewritten or replaced over time,
 162 the garbage collector from SIOD is still an important part of Guile.