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 and fully functional,
 106   but that there is a better way of achieving the same thing, and we'd
 107   rather have you use this better way.  This allows us to eventually
 108   remove the old implementation and helps to keep Guile reasonably
 109   clean of historic baggage.
 110
 111   See the file NEWS for a list of features that are currently
 112   deprecated.  Each entry will also tell you what you should replace
 113   your code with.
 114
 115   To give you some help with this process, and to encourage (OK,
 116   nudge) people to switch to the newer methods, Guile can emit
 117   warnings or errors when you use a deprecated feature.  There is
 118   quite a range of possibilities, from being completely silent to
 119   giving errors at link time.  What exactly happens is determined both
 120   by the value of the `--enable-deprecated' configuration option when
 121   Guile was built, and by the GUILE_WARN_DEPRECATED environment
 122   variable.
 123
 124   It works like this:
 125
 126     When Guile has been configured with `--enable-deprecated=no' (or,
 127     equivalently, with `--disable-deprecated') then all deprecated
 128     features are omitted from Guile.  You will get "undefined
 129     reference", "variable unbound" or similar errors when you try to
 130     use them.
 131
 132     When `--enable-deprecated=LEVEL' has been specified (for LEVEL not
 133     "no"), LEVEL will be used as the default value of the environment
 134     variable GUILE_WARN_DEPRECATED.  A value of "yes" is changed to
 135     "summary" and "shutup" is changed to "no", however.
 136
 137     When GUILE_WARN_DEPRECATED has the value "no", nothing special
 138     will happen when a deprecated feature is used.
 139
 140     When GUILE_WARN_DEPRECATED has the value "summary", and a
 141     deprecated feature has been used, Guile will print this message at
 142     exit:
 143
 144       Some deprecated features have been used.  Set the environment
 145       variable GUILE_WARN_DEPRECATED to "detailed" and rerun the
 146       program to get more information.  Set it to "no" to suppress
 147       this message.
 148
 149     When GUILE_WARN_DEPRECATED has the value "detailed", a detailed
 150     warning is emitted immediatly for the first use of a deprecated
 151     feature.
 152
 153   The default is `--enable-deprecated=yes'.
 154
 155 --disable-shared  ---  Do not build shared libraries.
 156 --disable-static  ---  Do not build static libraries.
 157
 158   Normally, both static and shared libraries will be built if your
 159   system supports them.
 160
 161
 162 --enable-debug-freelist  ---  Enable freelist debugging.
 163
 164   This enables a debugging version of SCM_NEWCELL(), and also
 165   registers an extra primitive, the setter
 166   `gc-set-debug-check-freelist!'.
 167
 168   Configure with the --enable-debug-freelist option to enable the
 169   gc-set-debug-check-freelist! primitive, and then use:
 170
 171   (gc-set-debug-check-freelist! #t)  # turn on checking of the freelist
 172   (gc-set-debug-check-freelist! #f)  # turn off checking
 173
 174   Checking of the freelist forces a traversal of the freelist and a
 175   garbage collection before each allocation of a cell.  This can slow
 176   down the interpreter dramatically, so the setter should be used to
 177   turn on this extra processing only when necessary.
 178
 179
 180 --enable-debug-malloc  ---  Enable malloc debugging.
 181
 182   Include code for debugging of calls to scm_must_malloc/realloc/free.
 183
 184   Checks that
 185
 186   1. objects freed by scm_must_free has been mallocated by scm_must_malloc
 187   2. objects reallocated by scm_must_realloc has been allocated by
 188      scm_must_malloc
 189   3. reallocated objects are reallocated with the same what string
 190
 191   But, most importantly, it records the number of allocated objects of
 192   each kind.  This is useful when searching for memory leaks.
 193
 194   A Guile compiled with this option provides the primitive
 195   `malloc-stats' which returns an alist with pairs of kind and the
 196   number of objects of that kind.
 197
 198
 199 --enable-guile-debug  ---  Include internal debugging functions
 200 --disable-arrays      ---  omit array and uniform array support
 201 --disable-posix       ---  omit posix interfaces
 202 --disable-networking  ---  omit networking interfaces
 203 --disable-regex       ---  omit regular expression interfaces
 204
 205
 206 Cross building Guile  =====================================================
 207
 208 As of guile-1.5.x, the build process uses compiled C files for
 209 snarfing, and (indirectly, through libtool) for linking, and uses the
 210 guile executable for generating documentation.
 211
 212 When cross building guile, you first need to configure, build and
 213 install guile for your build host.
 214
 215 Then, you may configure guile for cross building, eg:
 216
 217     ./configure --host=i686-pc-cygwin --disable-shared
 218
 219 A C compiler for the build system is required.  The default is
 220 "PATH=/usr/bin:$PATH cc".  If that doesn't suit it can be specified
 221 with the CC_FOR_BUILD variable in the usual way, for instance
 222
 223     ./configure --host=m68k-unknown-linux-gnu CC_FOR_BUILD=/my/local/gcc
 224
 225 A further special option for cross building is available:
 226
 227 --with-guile-for-build   --- native Guile executable, to be used during build
 228                              defaults to: `guile', assuming you just
 229                              installed this guile natively.
 230
 231
 232 Using Guile Without Installing It =========================================
 233
 234 If you want to run Guile without installing it, set the environment
 235 variable `GUILE_LOAD_PATH' to a colon-separated list of directories,
 236 including the directory containing this INSTALL file.  If you used a
 237 separate build directory, you'll need to include the build directory
 238 in the path as well.
 239
 240 For example, suppose the Guile distribution unpacked into a directory
 241 called `/home/jimb/guile-snap' (so the full name of this INSTALL file
 242 would be `/home/jimb/guile-snap/INSTALL').  Then you might say, if
 243 you're using Bash or any other Bourne shell variant,
 244
 245   export GUILE_LOAD_PATH=/home/jimb/guile-snap
 246
 247 or if you're using CSH or one of its variants:
 248
 249   setenv GUILE_LOAD_PATH /home/jimb/guile-snap
 250
 251 You will additionally need to set your `LTDL_LIBRARY_PATH' environment
 252 variable to the directory in which the compiled SRFI support modules
 253 are created if you want to use the modules for SRFI-4, SRFI-13 or
 254 SRFI-14 support.  Similar to the example above, this will be,
 255
 256   export LTDL_LIBRARY_PATH=/home/jimb/guile-snap/srfi/.libs
 257
 258 or if you're using CSH or one of its variants:
 259
 260   setenv LTDL_LIBRARY_PATH /home/jimb/guile-snap/srfi/.libs
 261
 262
 263 Installing SLIB ===========================================================
 264
 265 In order to use SLIB from Guile you basically only need to put the
 266 `slib' directory _in_ one of the directories on Guile's load path.
 267
 268 The standard installation is:
 269
 270   1. Obtain slib from http://www-swiss.ai.mit.edu/~jaffer/SLIB.html
 271
 272   2. Put it in Guile's data directory, that is the directory printed when
 273      you type
 274
 275        guile-config info pkgdatadir
 276
 277      at the shell prompt.  This is normally `/usr/local/share/guile', so the
 278      directory will normally have full path `/usr/local/share/guile/slib'.
 279
 280   3. Start guile as a user with write access to the data directory and type
 281
 282        (use-modules (ice-9 slib))
 283
 284      at the Guile prompt.  This will generate the slibcat catalog next to
 285      the slib directory.
 286
 287 SLIB's `require' is provided by the Guile module (ice-9 slib).
 288
 289 Example:
 290
 291   (use-modules (ice-9 slib))
 292   (require 'primes)
 293   (prime? 7)
 294
 295 Guile Documentation ==================================================
 296
 297 The doc directory contains a few articles on specific topics and some
 298 examples, including data-rep.texi which describes the internal
 299 representation of data types in Guile.  The example-smob directory
 300 contains example source code for the "Defining New Types (Smobs)" chapter.
 301
 302 The incomplete Guile reference manual is available at
 303
 304   ftp://ftp.red-bean.com/pub/guile/snapshots/guile-doc-snap.tar.gz
 305
 306 Neil Jerram is working on the new reference manual, which will be
 307 distributed with guile-core.  The new manual will be synchronized with
 308 the docstrings in the sources.  Until then, please be aware that the
 309 docstrings are likely to be more up-to-date than the old reference
 310 manual (use `(help)' or see libguile/guile-procedures.txt which is
 311 generated by the build process).
 312
 313 The Guile WWW page is at
 314
 315   http://www.gnu.org/software/guile/guile.html
 316
 317 It contains a link to the Guile FAQ.
 318
 319 About This Distribution ==============================================
 320
 321 Interesting files include:
 322
 323 - LICENSE, which contains the exact terms of the Guile license.
 324 - COPYING, which contains the terms of the GNU General Public License.
 325 - INSTALL, which contains general instructions for building/installing Guile.
 326 - NEWS, which describes user-visible changes since the last release of Guile.
 327
 328 Files are usually installed according to the prefix specified to
 329 configure, /usr/local by default.  Building and installing gives you:
 330
 331 Executables, in ${prefix}/bin:
 332
 333  guile --- a stand-alone interpreter for Guile.  With no arguments, this
 334         is a simple interactive Scheme interpreter.  It can also be used
 335         as an interpreter for script files; see the NEWS file for details.
 336  guile-config --- a Guile script which provides the information necessary
 337         to link your programs against the Guile library.
 338  guile-snarf --- a script to parse declarations in your C code for
 339         Scheme-visible C functions, Scheme objects to be used by C code,
 340         etc.
 341  guile-tools --- a wrapper to invoke the executable modules in
 342         subdirectory `scripts' (also installed).
 343
 344 Libraries, in ${prefix}/lib.  Depending on the platform and options
 345         given to configure, you may get shared libraries in addition
 346         to or instead of these static libraries:
 347
 348  libguile.a --- an object library containing the Guile interpreter,
 349         You can use Guile in your own programs by linking against this.
 350  libqthreads.a --- an object library containing the QuickThreads
 351         primitives.  If you enabled thread support when you configured
 352         Guile, you will need to link your code against this too.
 353  libguilereadline.a --- an object library containing glue code for the
 354          GNU readline library.  See NEWS for instructions on how to enable
 355         readline for your personal use.
 356  libguile-srfi-*.a --- various SRFI support libraries
 357
 358 Header files, in ${prefix}/include:
 359
 360  libguile.h, guile/gh.h, libguile/*.h --- for libguile.
 361  guile-readline/readline.h --- for guile-readline.
 362
 363 Support files, in ${prefix}/share/guile/<version>:
 364
 365  ice-9/* --- run-time support for Guile: the module system,
 366         read-eval-print loop, some R4RS code and other infrastructure.
 367  oop/* --- the Guile Object-Oriented Programming System (GOOPS)
 368  scripts/* --- executable modules, i.e., scheme programs that can be both
 369         called as an executable from the shell, and loaded and used as a
 370         module from scheme code.  See scripts/README for more info.
 371  srfi/* --- SRFI support modules.  See srfi/README for more info.
 372
 373 Automake macros, in ${prefix}/share/aclocal:
 374
 375  guile.m4
 376
 377 Documentation in Info format, in ${prefix}/info:
 378
 379  guile --- Guile reference manual.
 380
 381  guile-tut --- Guile tutorial.
 382
 383  GOOPS --- GOOPS reference manual.
 384
 385  r5rs --- Revised(5) Report on the Algorithmic Language Scheme.
 386
 387
 388 The Guile source tree is laid out as follows:
 389
 390 libguile:
 391         The Guile Scheme interpreter --- both the object library
 392         for you to link with your programs, and the executable you can run.
 393 ice-9:  Guile's module system, initialization code, and other infrastructure.
 394 guile-config:
 395         Source for the guile-config script.
 396 qt:     A cooperative threads package from the University of Washington,
 397         which Guile can use.  If you configure Guile with the
 398         --with-threads flag, you will need to link against the -lqt
 399         library, found in this directory.  Qt is under a separate
 400         copyright; see `qt/README' for more details.
 401 guile-readline:
 402         The glue code for using GNU readline with Guile.  This
 403         will be build when configure can find a recent enough readline
 404         library on your system.
 405 doc:    Documentation (see above).
 406
 407 Anonymous CVS Access and FTP snapshots ===============================
 408
 409 We make the developers' working Guile sources available via anonymous
 410 CVS, and by nightly snapshots, accessible via FTP.  See the files
 411 `ANON-CVS' and `SNAPSHOTS' for details.
 412
 413 If you would like to receive mail when people commit changes to the
 414 Guile CVS repository, you can subscribe to guile-cvs@gnu.org by the
 415 Mailman mailing list interface at
 416
 417   <http://mail.gnu.org/mailman/listinfo/guile-cvs>
 418
 419
 420 Obtaining Guile ======================================================
 421
 422 The latest official Guile release is available via anonymous FTP from
 423
 424 ftp://ftp.gnu.org/pub/gnu/guile/guile-1.4.tar.gz
 425
 426 The mailing list `guile-user@gnu.org' carries discussions, questions,
 427 and often answers, about Guile.  To subscribe, use the Mailman mailing
 428 list interface at <http://mail.gnu.org/mailman/listinfo/guile-user>
 429 Of course, please send bug reports (and fixes!) to bug-guile@gnu.org.