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