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 See the LICENSE file for the specific terms that apply to Guile.
  22
  23
  24 Additional INSTALL instructions ===========================================
  25
  26 Generic instructions for configuring and compiling Guile can be found
  27 in the INSTALL file.  Guile specific information and configure options
  28 can be found below, including instructions for installing SLIB.
  29
  30 Guile can use a number of external packages such as `readline' when
  31 they are available.  Guile expects to be able to find these packages
  32 in the default compiler setup, it does not try to make any special
  33 arrangements itself.  For example, for the `readline' package, Guile
  34 expects to be able to find the include file <readline/readline.h>,
  35 without passing any special `-I' options to the compiler.
  36
  37 If you installed an external package, and you used the --prefix
  38 installation option to install it somewhere else than /usr/local, you
  39 must arrange for your compiler to find it by default.  If that
  40 compiler is gcc, one convenient way of making such arrangements is to
  41 use the --with-local-prefix option during installation, naming the
  42 same directory as you used in the --prefix option of the package.  In
  43 particular, it is not good enough to use the same --prefix option when
  44 you install gcc and the package; you need to use the
  45 --with-local-prefix option as well.  See the gcc documentation for
  46 more details.
  47
  48
  49 Special Instructions For Some Systems =====================================
  50
  51 We would like Guile to build on all systems using the simple
  52 instructions above, but it seems that a few systems still need special
  53 treatment.  If you can send us fixes for these problems, we'd be
  54 grateful.
  55
  56 SunOS 4.1: Guile's shared library support seems to be confused, but
  57     hey; shared libraries are confusing.  You may need to configure
  58     Guile with a command like:
  59         ./configure --disable-shared
  60     For more information on `--disable-shared', see below, "Flags
  61     Accepted by Configure".
  62
  63 HP/UX: GCC 2.7.2 (and maybe other versions) have trouble creating
  64     shared libraries if they depend on any non-shared libraries.  GCC
  65     seems to have other problems as well.  To work around this, we
  66     suggest you configure Guile to use the system's C compiler:
  67         CC=cc ./configure
  68
  69 NetBSD: Perry Metzger says, "Guile will build under NetBSD only using
  70     gmake -- the native make will not work.  (gmake is in our package
  71     system, so this will not be a problem when we packagize 1.3.)"
  72
  73
  74 Guile specific flags Accepted by Configure =================================
  75
  76 If you run the configure script with no arguments, it should examine
  77 your system and set things up appropriately.  However, there are a few
  78 switches specific to Guile you may find useful in some circumstances.
  79
  80 --with-threads  ---  Build with thread support
  81
  82   Build a Guile executable and library that supports cooperative
  83   threading.  If you use this switch, Guile will also build and
  84   install the QuickThreads non-preemptive threading library,
  85   libqthreads, which you will need to link into your programs after
  86   libguile.  When you use `guile-config', you will pick up all
  87   neccessary linker flags automatically.
  88
  89   Cooperative threads are not yet thoroughly tested; once they are,
  90   they will be enabled by default.  The interaction with blocking I/O
  91   is pretty ad hoc at the moment.  In our experience, bugs in the
  92   thread support do not affect you if you don't actually use threads.
  93
  94 --with-modules  ---  Specify statically linked `modules'
  95
  96   Guile can dynamically load `plugin modules' during runtime, using
  97   facilities provided by libtool.  Not all platforms support this,
  98   however.  On these platforms, you can statically link the plugin
  99   modules into libguile when Guile itself is built.  XXX - how does
 100   one specify the modules?
 101
 102 --enable-deprecated=LEVEL
 103
 104   Guile may contain features that are `deprecated'.  When a feature is
 105   deprecated, it means that it is still there, but that there is a
 106   better way of achieving the same thing, and we'd rather have you use
 107   this better way.  This allows us to eventually remove the old
 108   implementation and helps to keep Guile reasonably clean of historic
 109   baggage.
 110
 111   Deprecated features are considered harmful; using them is likely a
 112   bug.  See below for the related notion of `discouraged' features,
 113   which are OK but have fallen out of favour.
 114
 115   See the file NEWS for a list of features that are currently
 116   deprecated.  Each entry will also tell you what you should replace
 117   your code with.
 118
 119   To give you some help with this process, and to encourage (OK,
 120   nudge) people to switch to the newer methods, Guile can emit
 121   warnings or errors when you use a deprecated feature.  There is
 122   quite a range of possibilities, from being completely silent to
 123   giving errors at link time.  What exactly happens is determined both
 124   by the value of the `--enable-deprecated' configuration option when
 125   Guile was built, and by the GUILE_WARN_DEPRECATED environment
 126   variable.
 127
 128   It works like this:
 129
 130     When Guile has been configured with `--enable-deprecated=no' (or,
 131     equivalently, with `--disable-deprecated') then all deprecated
 132     features are omitted from Guile.  You will get "undefined
 133     reference", "variable unbound" or similar errors when you try to
 134     use them.
 135
 136     When `--enable-deprecated=LEVEL' has been specified (for LEVEL not
 137     "no"), LEVEL will be used as the default value of the environment
 138     variable GUILE_WARN_DEPRECATED.  A value of "yes" is changed to
 139     "summary" and "shutup" is changed to "no", however.
 140
 141     When GUILE_WARN_DEPRECATED has the value "no", nothing special
 142     will happen when a deprecated feature is used.
 143
 144     When GUILE_WARN_DEPRECATED has the value "summary", and a
 145     deprecated feature has been used, Guile will print this message at
 146     exit:
 147
 148       Some deprecated features have been used.  Set the environment
 149       variable GUILE_WARN_DEPRECATED to "detailed" and rerun the
 150       program to get more information.  Set it to "no" to suppress
 151       this message.
 152
 153     When GUILE_WARN_DEPRECATED has the value "detailed", a detailed
 154     warning is emitted immediatly for the first use of a deprecated
 155     feature.
 156
 157   The default is `--enable-deprecated=yes'.
 158
 159 --disable-discouraged
 160
 161   In addition to deprecated features, Guile can also contain things
 162   that are merely `discouraged'.  It is OK to continue to use these
 163   features in old code, but new code should avoid them since there are
 164   better alternatives.
 165
 166   There is nothing wrong with a discouraged feature per se, but they
 167   might have strange names, or be non-standard, for example.  Avoiding
 168   them will make your code better.
 169
 170 --disable-shared  ---  Do not build shared libraries.
 171 --disable-static  ---  Do not build static libraries.
 172
 173   Normally, both static and shared libraries will be built if your
 174   system supports them.
 175
 176
 177 --enable-debug-freelist  ---  Enable freelist debugging.
 178
 179   This enables a debugging version of SCM_NEWCELL(), and also
 180   registers an extra primitive, the setter
 181   `gc-set-debug-check-freelist!'.
 182
 183   Configure with the --enable-debug-freelist option to enable the
 184   gc-set-debug-check-freelist! primitive, and then use:
 185
 186   (gc-set-debug-check-freelist! #t)  # turn on checking of the freelist
 187   (gc-set-debug-check-freelist! #f)  # turn off checking
 188
 189   Checking of the freelist forces a traversal of the freelist and a
 190   garbage collection before each allocation of a cell.  This can slow
 191   down the interpreter dramatically, so the setter should be used to
 192   turn on this extra processing only when necessary.
 193
 194
 195 --enable-debug-malloc  ---  Enable malloc debugging.
 196
 197   Include code for debugging of calls to scm_must_malloc/realloc/free.
 198
 199   Checks that
 200
 201   1. objects freed by scm_must_free has been mallocated by scm_must_malloc
 202   2. objects reallocated by scm_must_realloc has been allocated by
 203      scm_must_malloc
 204   3. reallocated objects are reallocated with the same what string
 205
 206   But, most importantly, it records the number of allocated objects of
 207   each kind.  This is useful when searching for memory leaks.
 208
 209   A Guile compiled with this option provides the primitive
 210   `malloc-stats' which returns an alist with pairs of kind and the
 211   number of objects of that kind.
 212
 213
 214 --enable-guile-debug  ---  Include internal debugging functions
 215 --disable-arrays      ---  omit array and uniform array support
 216 --disable-posix       ---  omit posix interfaces
 217 --disable-networking  ---  omit networking interfaces
 218 --disable-regex       ---  omit regular expression interfaces
 219
 220
 221 Cross building Guile  =====================================================
 222
 223 As of guile-1.5.x, the build process uses compiled C files for
 224 snarfing, and (indirectly, through libtool) for linking, and uses the
 225 guile executable for generating documentation.
 226
 227 When cross building guile, you first need to configure, build and
 228 install guile for your build host.
 229
 230 Then, you may configure guile for cross building, eg:
 231
 232     ./configure --host=i686-pc-cygwin --disable-shared
 233
 234 A C compiler for the build system is required.  The default is
 235 "PATH=/usr/bin:$PATH cc".  If that doesn't suit it can be specified
 236 with the CC_FOR_BUILD variable in the usual way, for instance
 237
 238     ./configure --host=m68k-unknown-linux-gnu CC_FOR_BUILD=/my/local/gcc
 239
 240 Guile for the build system can be specified similarly with the
 241 GUILE_FOR_BUILD variable, it defaults to just "guile".
 242
 243
 244 Using Guile Without Installing It =========================================
 245
 246 If you want to run Guile without installing it, set the environment
 247 variable `GUILE_LOAD_PATH' to a colon-separated list of directories,
 248 including the directory containing this INSTALL file.  If you used a
 249 separate build directory, you'll need to include the build directory
 250 in the path as well.
 251
 252 For example, suppose the Guile distribution unpacked into a directory
 253 called `/home/jimb/guile-snap' (so the full name of this INSTALL file
 254 would be `/home/jimb/guile-snap/INSTALL').  Then you might say, if
 255 you're using Bash or any other Bourne shell variant,
 256
 257   export GUILE_LOAD_PATH=/home/jimb/guile-snap
 258
 259 or if you're using CSH or one of its variants:
 260
 261   setenv GUILE_LOAD_PATH /home/jimb/guile-snap
 262
 263 You will additionally need to set your `LTDL_LIBRARY_PATH' environment
 264 variable to the directory in which the compiled SRFI support modules
 265 are created if you want to use the modules for SRFI-4, SRFI-13 or
 266 SRFI-14 support.  Similar to the example above, this will be,
 267
 268   export LTDL_LIBRARY_PATH=/home/jimb/guile-snap/srfi/.libs
 269
 270 or if you're using CSH or one of its variants:
 271
 272   setenv LTDL_LIBRARY_PATH /home/jimb/guile-snap/srfi/.libs
 273
 274
 275 Installing SLIB ===========================================================
 276
 277 In order to use SLIB from Guile you basically only need to put the
 278 `slib' directory _in_ one of the directories on Guile's load path.
 279
 280 The standard installation is:
 281
 282   1. Obtain slib from http://www-swiss.ai.mit.edu/~jaffer/SLIB.html
 283
 284   2. Put it in Guile's data directory, that is the directory printed when
 285      you type
 286
 287        guile-config info pkgdatadir
 288
 289      at the shell prompt.  This is normally `/usr/local/share/guile', so the
 290      directory will normally have full path `/usr/local/share/guile/slib'.
 291
 292   3. Start guile as a user with write access to the data directory and type
 293
 294        (use-modules (ice-9 slib))
 295
 296      at the Guile prompt.  This will generate the slibcat catalog next to
 297      the slib directory.
 298
 299 SLIB's `require' is provided by the Guile module (ice-9 slib).
 300
 301 Example:
 302
 303   (use-modules (ice-9 slib))
 304   (require 'primes)
 305   (prime? 7)
 306
 307 Guile Documentation ==================================================
 308
 309 If you've never used Scheme before, then the Guile Tutorial
 310 (guile-tut.info) is a good starting point.  The Guile Reference Manual
 311 (guile.info) is the primary documentation for Guile.  The Goops object
 312 system is documented separately (goops.info).  A copy of the R5RS
 313 Scheme specification is included too (r5rs.info).
 314
 315 Info format versions of this documentation are installed as part of
 316 the normal build process.  The texinfo sources are under the doc
 317 directory, and other formats like Postscript, PDF, DVI or HTML can be
 318 generated from them with Tex and Texinfo tools.
 319
 320 The doc directory also includes an example-smob subdirectory which has
 321 the example code from the "Defining New Types (Smobs)" chapter of the
 322 reference manual.
 323
 324 The Guile WWW page is at
 325
 326   http://www.gnu.org/software/guile/guile.html
 327
 328 It contains a link to the Guile FAQ.
 329
 330 About This Distribution ==============================================
 331
 332 Interesting files include:
 333
 334 - LICENSE, which contains the exact terms of the Guile license.
 335 - COPYING, which contains the terms of the GNU General Public License.
 336 - INSTALL, which contains general instructions for building/installing Guile.
 337 - NEWS, which describes user-visible changes since the last release of Guile.
 338
 339 Files are usually installed according to the prefix specified to
 340 configure, /usr/local by default.  Building and installing gives you:
 341
 342 Executables, in ${prefix}/bin:
 343
 344  guile --- a stand-alone interpreter for Guile.  With no arguments, this
 345         is a simple interactive Scheme interpreter.  It can also be used
 346         as an interpreter for script files; see the NEWS file for details.
 347  guile-config --- a Guile script which provides the information necessary
 348         to link your programs against the Guile library.
 349  guile-snarf --- a script to parse declarations in your C code for
 350         Scheme-visible C functions, Scheme objects to be used by C code,
 351         etc.
 352  guile-tools --- a wrapper to invoke the executable modules in
 353         subdirectory `scripts' (also installed).
 354
 355 Libraries, in ${prefix}/lib.  Depending on the platform and options
 356         given to configure, you may get shared libraries in addition
 357         to or instead of these static libraries:
 358
 359  libguile.a --- an object library containing the Guile interpreter,
 360         You can use Guile in your own programs by linking against this.
 361  libqthreads.a --- an object library containing the QuickThreads
 362         primitives.  If you enabled thread support when you configured
 363         Guile, you will need to link your code against this too.
 364  libguilereadline.a --- an object library containing glue code for the
 365          GNU readline library.  See NEWS for instructions on how to enable
 366         readline for your personal use.
 367  libguile-srfi-*.a --- various SRFI support libraries
 368
 369 Header files, in ${prefix}/include:
 370
 371  libguile.h, guile/gh.h, libguile/*.h --- for libguile.
 372  guile-readline/readline.h --- for guile-readline.
 373
 374 Support files, in ${prefix}/share/guile/<version>:
 375
 376  ice-9/* --- run-time support for Guile: the module system,
 377         read-eval-print loop, some R4RS code and other infrastructure.
 378  oop/* --- the Guile Object-Oriented Programming System (GOOPS)
 379  scripts/* --- executable modules, i.e., scheme programs that can be both
 380         called as an executable from the shell, and loaded and used as a
 381         module from scheme code.  See scripts/README for more info.
 382  srfi/* --- SRFI support modules.  See srfi/README for more info.
 383
 384 Automake macros, in ${prefix}/share/aclocal:
 385
 386  guile.m4
 387
 388 Documentation in Info format, in ${prefix}/info:
 389
 390  guile --- Guile reference manual.
 391
 392  guile-tut --- Guile tutorial.
 393
 394  GOOPS --- GOOPS reference manual.
 395
 396  r5rs --- Revised(5) Report on the Algorithmic Language Scheme.
 397
 398
 399 The Guile source tree is laid out as follows:
 400
 401 libguile:
 402         The Guile Scheme interpreter --- both the object library
 403         for you to link with your programs, and the executable you can run.
 404 ice-9:  Guile's module system, initialization code, and other infrastructure.
 405 guile-config:
 406         Source for the guile-config script.
 407 qt:     A cooperative threads package from the University of Washington,
 408         which Guile can use.  If you configure Guile with the
 409         --with-threads flag, you will need to link against the -lqt
 410         library, found in this directory.  Qt is under a separate
 411         copyright; see `qt/README' for more details.
 412 guile-readline:
 413         The glue code for using GNU readline with Guile.  This
 414         will be build when configure can find a recent enough readline
 415         library on your system.
 416 doc:    Documentation (see above).
 417
 418 Anonymous CVS Access and FTP snapshots ===============================
 419
 420 We make the developers' working Guile sources available via anonymous
 421 CVS, and by nightly snapshots, accessible via FTP.  See the files
 422 `ANON-CVS' and `SNAPSHOTS' for details.
 423
 424 If you would like to receive mail when people commit changes to the
 425 Guile CVS repository, you can subscribe to guile-cvs@gnu.org by the
 426 Mailman mailing list interface at
 427
 428   <http://mail.gnu.org/mailman/listinfo/guile-cvs>
 429
 430
 431 Obtaining Guile ======================================================
 432
 433 The latest official Guile release is available via anonymous FTP from
 434
 435 ftp://ftp.gnu.org/pub/gnu/guile/guile-1.4.tar.gz
 436
 437 The mailing list `guile-user@gnu.org' carries discussions, questions,
 438 and often answers, about Guile.  To subscribe, use the Mailman mailing
 439 list interface at <http://mail.gnu.org/mailman/listinfo/guile-user>
 440 Of course, please send bug reports (and fixes!) to bug-guile@gnu.org.