README

   1 This is not a Guile release; it is a source tree retrieved via
   2 anonymous CVS or as a nightly snapshot at some random time after the
   3 Guile 1.4 release.
   4
   5 This is a 1.5 development version of Guile, Project GNU's extension
   6 language library.  Guile is an interpreter for Scheme, packaged as a
   7 library that you can link into your applications to give them their
   8 own scripting language.  Guile will eventually support other languages
   9 as well, giving users of Guile-based applications a choice of
  10 languages.
  11
  12 Guile versions with an odd middle number, i.e. 1.5.* are unstable
  13 development versions.  Even middle numbers indicate stable versions.
  14 This has been the case since the 1.3.* series.
  15
  16 The next stable release will be version 1.6.0.
  17
  18 Please send bug reports to bug-guile@gnu.org.
  19
  20 Guile Documentation ==================================================
  21
  22 The doc directory contains a few articles on specific topics and some
  23 examples, including data-rep.texi which describes the internal
  24 representation of data types in Guile.  The example-smob directory
  25 contains example source code for the "Defining New Types (Smobs)" chapter.
  26
  27 The incomplete Guile reference manual is available at
  28
  29   ftp://ftp.red-bean.com/pub/guile/snapshots/guile-doc-snap.tar.gz
  30
  31 Neil Jerram is working on the new reference manual, which will be
  32 distributed with guile-core.  The new manual will be synchronized with
  33 the docstrings in the sources.  Until then, please be aware that the
  34 docstrings are likely to be more up-to-date than the old reference
  35 manual (use `(help)' or see libguile/guile-procedures.txt which is
  36 generated by the build process).
  37
  38 The Guile WWW page is at
  39
  40   http://www.gnu.org/software/guile/guile.html
  41
  42 It contains a link to the Guile FAQ.
  43
  44 Guile License ==================================================
  45
  46 The license of Guile consists of the GNU GPL plus a special statement
  47 giving blanket permission to link with non-free software.  This is the
  48 license statement as found in any individual file that it applies to:
  49
  50  This program is free software; you can redistribute it and/or modify
  51  it under the terms of the GNU General Public License as published by
  52  the Free Software Foundation; either version 2, or (at your option)
  53  any later version.
  54
  55  This program is distributed in the hope that it will be useful,
  56  but WITHOUT ANY WARRANTY; without even the implied warranty of
  57  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  58  GNU General Public License for more details.
  59
  60  You should have received a copy of the GNU General Public License
  61  along with this software; see the file COPYING.  If not, write to
  62  the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  63  Boston, MA 02111-1307 USA
  64
  65  As a special exception, the Free Software Foundation gives permission
  66  for additional uses of the text contained in its release of GUILE.
  67
  68  The exception is that, if you link the GUILE library with other files
  69  to produce an executable, this does not by itself cause the
  70  resulting executable to be covered by the GNU General Public License.
  71  Your use of that executable is in no way restricted on account of
  72  linking the GUILE library code into it.
  73
  74  This exception does not however invalidate any other reasons why
  75  the executable file might be covered by the GNU General Public License.
  76
  77  This exception applies only to the code released by the
  78  Free Software Foundation under the name GUILE.  If you copy
  79  code from other Free Software Foundation releases into a copy of
  80  GUILE, as the General Public License permits, the exception does
  81  not apply to the code that you add in this way.  To avoid misleading
  82  anyone as to the status of such modified files, you must delete
  83  this exception notice from them.
  84
  85  If you write modifications of your own for GUILE, it is your choice
  86  whether to permit this exception to apply to your modifications.
  87  If you do not wish that, delete this exception notice.
  88
  89 Handling of Deprecated Features ======================================
  90
  91 Guile may contain features that are `deprecated'.  When a feature is
  92 deprecated, it means that it is still there and fully functional, but
  93 that there is a better way of achieving the same thing, and we'd
  94 rather have you use this better way.  This allows us to eventually
  95 remove the old implementation and helps to keep Guile reasonably clean
  96 of historic baggage.
  97
  98 See the file NEWS for a list of features that are currently
  99 deprecated.  Each entry will also tell you what you should replace
 100 your code with.
 101
 102 To give you some help with this process, and to encourage (OK, nudge)
 103 people to switch to the newer methods, Guile can emit warnings or
 104 errors when you use a deprecated feature.  There is quite a range of
 105 possibilities, from being completely silent to giving errors at link
 106 time.  What exactly happens is determined both by the value of the
 107 `--enable-deprecated' configuration option when Guile was built, and
 108 by the GUILE_WARN_DEPRECATED environment variable.
 109
 110 It works like this:
 111
 112   When Guile has been configured with `--enable-deprecated=no' (or,
 113   equivalently, with `--disable-deprecated') then all deprecated
 114   features are omitted from Guile.  You will get "undefined
 115   reference", "variable unbound" or similar errors when you try to use
 116   them.
 117
 118   When `--enable-deprecated=LEVEL' has been specified (for LEVEL not
 119   "no"), LEVEL will be used as the default value of the environment
 120   variable GUILE_WARN_DEPRECATED.  A value of "yes" is changed to
 121   "summary" and "shutup" is changed to "no", however.
 122
 123   When GUILE_WARN_DEPRECATION has the value "no", nothing special will
 124   happen when a deprecated feature is used.
 125
 126   When GUILE_WARN_DEPRECATION has the value "summary", and a deprecated
 127   feature has been used, Guile will print this message at exit:
 128
 129     Some deprecated features have been used.  Set the environment
 130     variable GUILE_WARN_DEPRECATED to "detailed" and rerun the program
 131     to get more information.  Set it to "no" to suppress this message.
 132
 133   When GUILE_WARN_DEPRECATION has the value "detailed", a detailed
 134   warning is emitted immediatly for the first use of a deprecated
 135   feature.
 136
 137 The default is `--enable-deprecated=yes'.
 138
 139 About This Distribution ==============================================
 140
 141 Interesting files include:
 142
 143 - INSTALL, which contains instructions on building and installing Guile.
 144 - NEWS, which describes user-visible changes since the last release of Guile.
 145
 146 Files are usually installed according to the prefix specified to
 147 configure, /usr/local by default.  Building and installing gives you:
 148
 149 Executables, in ${prefix}/bin:
 150
 151 guile --- a stand-alone interpreter for Guile.  With no arguments, this
 152         is a simple interactive Scheme interpreter.  It can also be used
 153         as an interpreter for script files; see the NEWS file for details.
 154 guile-config --- a Guile script which provides the information necessary
 155         to link your programs against the Guile library.
 156 guile-snarf --- a script to parse declarations in your C code for
 157         Scheme-visible C functions, Scheme objects to be used by C code,
 158         etc.
 159 guile-tools --- a wrapper to invoke the executable modules in
 160         subdirectory `scripts' (also installed).
 161
 162 Libraries, in ${prefix}/lib.  Depending on the platform and options
 163         given to configure, you may get shared libraries in addition
 164         to or instead of these static libraries:
 165
 166 libguile.a --- an object library containing the Guile interpreter,
 167         You can use Guile in your own programs by linking against this.
 168 libqthreads.a --- an object library containing the QuickThreads
 169         primitives.  If you enabled thread support when you configured
 170         Guile, you will need to link your code against this too.
 171 libguilereadline.a --- an object library containing glue code for the
 172         GNU readline library.  See NEWS for instructions on how to enable
 173         readline for your personal use.
 174
 175 Header files, in ${prefix}/include:
 176
 177 libguile.h, guile/gh.h, libguile/*.h --- for libguile.
 178 guile-readline/readline.h --- for guile-readline.
 179
 180 Support files, in ${prefix}/share/guile/<version>:
 181
 182 ice-9/* --- run-time support for Guile: the module system,
 183         read-eval-print loop, some R4RS code and other infrastructure.
 184
 185 Automake macros, in ${prefix}/share/aclocal:
 186
 187 guile.m4
 188
 189 Documentation in Info format, in ${prefix}/info:
 190
 191 data-rep.info --- an essay on how to write C code that works with
 192         Guile Scheme values.
 193
 194 The Guile source tree is laid out as follows:
 195
 196 libguile:
 197         The Guile Scheme interpreter --- both the object library
 198         for you to link with your programs, and the executable you can run.
 199 ice-9:  Guile's module system, initialization code, and other infrastructure.
 200 guile-config:
 201         Source for the guile-config script.
 202 qt:     A cooperative threads package from the University of Washington,
 203         which Guile can use.  If you configure Guile with the
 204         --with-threads flag, you will need to link against the -lqt
 205         library, found in this directory.  Qt is under a separate
 206         copyright; see `qt/README' for more details.
 207 guile-readline:
 208         The glue code for using GNU readline with Guile.  This
 209         will be build when configure can find a recent enough readline
 210         library on your system.
 211 doc:    Documentation (see above).
 212
 213 Anonymous CVS Access and FTP snapshots ===============================
 214
 215 We make the developers' working Guile sources available via anonymous
 216 CVS, and by nightly snapshots, accessible via FTP.  See the files
 217 `ANON-CVS' and `SNAPSHOTS' for details.
 218
 219 If you would like to receive mail when people commit changes to the
 220 Guile CVS repository, you can subscribe to guile-cvs@gnu.org by the
 221 Mailman mailing list interface at
 222
 223   <http://mail.gnu.org/mailman/listinfo/guile-cvs>
 224
 225
 226 Obtaining Guile ======================================================
 227
 228 The latest official Guile release is available via anonymous FTP from
 229
 230 ftp://ftp.gnu.org/pub/gnu/guile/guile-1.4.tar.gz
 231
 232 The mailing list `guile-user@gnu.org' carries discussions, questions,
 233 and often answers, about Guile.  To subscribe, use the Mailman mailing
 234 list interface at <http://mail.gnu.org/mailman/listinfo/guile-user>
 235 Of course, please send bug reports (and fixes!) to bug-guile@gnu.org.