README

   1 !!! This is not a Guile release; it is a source tree retrieved via
   2 Git or as a nightly snapshot at some random time after the
   3 Guile 1.8 release.  If this were a Guile release, you would not see
   4 this message. !!!  [fixme: zonk on release]
   5
   6 This is a 1.9 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.9.* 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 likely be version 1.10.0.
  18
  19 Please send bug reports to bug-guile@gnu.org.  Note that you must be
  20 subscribed to this list first, in order to successfully send a report
  21 to it.
  22
  23 See the LICENSE file for the specific terms that apply to Guile.
  24
  25
  26 Additional INSTALL instructions ===========================================
  27
  28 Generic instructions for configuring and compiling Guile can be found
  29 in the INSTALL file.  Guile specific information and configure options
  30 can be found below, including instructions for installing SLIB.
  31
  32 Guile requires a few external packages and can optionally use a number
  33 of external packages such as `readline' when they are available.
  34 Guile expects to be able to find these packages in the default
  35 compiler setup, it does not try to make any special arrangements
  36 itself.  For example, for the `readline' package, Guile expects to be
  37 able to find the include file <readline/readline.h>, without passing
  38 any special `-I' options to the compiler.
  39
  40 If you installed an external package, and you used the --prefix
  41 installation option to install it somewhere else than /usr/local, you
  42 must arrange for your compiler to find it by default.  If that
  43 compiler is gcc, one convenient way of making such arrangements is to
  44 use the --with-local-prefix option during installation, naming the
  45 same directory as you used in the --prefix option of the package.  In
  46 particular, it is not good enough to use the same --prefix option when
  47 you install gcc and the package; you need to use the
  48 --with-local-prefix option as well.  See the gcc documentation for
  49 more details.
  50
  51
  52 Required External Packages ================================================
  53
  54 Guile requires the following external packages:
  55
  56   - GNU MP, at least version 4.1
  57
  58     GNU MP is used for bignum arithmetic.  It is available from
  59     http://swox.com/gmp
  60
  61   - libltdl from libtool, at least from libtool version 1.5.6
  62
  63     libltdl is used for loading extensions at run-time.  It is
  64     available from http://www.gnu.org/software/libtool/
  65
  66
  67 Special Instructions For Some Systems =====================================
  68
  69 We would like Guile to build on all systems using the simple
  70 instructions above, but it seems that a few systems still need special
  71 treatment.  If you can send us fixes for these problems, we'd be
  72 grateful.
  73
  74    <none yet listed>
  75
  76 Guile specific flags Accepted by Configure =================================
  77
  78 If you run the configure script with no arguments, it should examine
  79 your system and set things up appropriately.  However, there are a few
  80 switches specific to Guile you may find useful in some circumstances.
  81
  82 --without-threads  ---  Build without thread support
  83
  84   Build a Guile executable and library that supports multi-threading.
  85
  86   The default is to enable threading support when your operating
  87   system offsers 'POSIX threads'.  When you do not want threading, use
  88   `--without-threads'.
  89
  90 --enable-deprecated=LEVEL
  91
  92   Guile may contain features that are `deprecated'.  When a feature is
  93   deprecated, it means that it is still there, but that there is a
  94   better way of achieving the same thing, and we'd rather have you use
  95   this better way.  This allows us to eventually remove the old
  96   implementation and helps to keep Guile reasonably clean of historic
  97   baggage.
  98
  99   Deprecated features are considered harmful; using them is likely a
 100   bug.  See below for the related notion of `discouraged' features,
 101   which are OK but have fallen out of favor.
 102
 103   See the file NEWS for a list of features that are currently
 104   deprecated.  Each entry will also tell you what you should replace
 105   your code with.
 106
 107   To give you some help with this process, and to encourage (OK,
 108   nudge) people to switch to the newer methods, Guile can emit
 109   warnings or errors when you use a deprecated feature.  There is
 110   quite a range of possibilities, from being completely silent to
 111   giving errors at link time.  What exactly happens is determined both
 112   by the value of the `--enable-deprecated' configuration option when
 113   Guile was built, and by the GUILE_WARN_DEPRECATED environment
 114   variable.
 115
 116   It works like this:
 117
 118     When Guile has been configured with `--enable-deprecated=no' (or,
 119     equivalently, with `--disable-deprecated') then all deprecated
 120     features are omitted from Guile.  You will get "undefined
 121     reference", "variable unbound" or similar errors when you try to
 122     use them.
 123
 124     When `--enable-deprecated=LEVEL' has been specified (for LEVEL not
 125     "no"), LEVEL will be used as the default value of the environment
 126     variable GUILE_WARN_DEPRECATED.  A value of "yes" is changed to
 127     "summary" and "shutup" is changed to "no", however.
 128
 129     When GUILE_WARN_DEPRECATED has the value "no", nothing special
 130     will happen when a deprecated feature is used.
 131
 132     When GUILE_WARN_DEPRECATED has the value "summary", and a
 133     deprecated feature has been used, Guile will print this message at
 134     exit:
 135
 136       Some deprecated features have been used.  Set the environment
 137       variable GUILE_WARN_DEPRECATED to "detailed" and rerun the
 138       program to get more information.  Set it to "no" to suppress
 139       this message.
 140
 141     When GUILE_WARN_DEPRECATED has the value "detailed", a detailed
 142     warning is emitted immediatly for the first use of a deprecated
 143     feature.
 144
 145   The default is `--enable-deprecated=yes'.
 146
 147   In addition to setting GUILE_WARN_DEPRECATED in the environment, you
 148   can also use (debug-enable 'warn-deprecated) and (debug-disable
 149   'warn-deprecated) to enable and disable the detailed messaged at run
 150   time.
 151
 152 --disable-discouraged
 153
 154   In addition to deprecated features, Guile can also contain things
 155   that are merely `discouraged'.  It is OK to continue to use these
 156   features in old code, but new code should avoid them since there are
 157   better alternatives.
 158
 159   There is nothing wrong with a discouraged feature per se, but they
 160   might have strange names, or be non-standard, for example.  Avoiding
 161   them will make your code better.
 162
 163 --disable-shared  ---  Do not build shared libraries.
 164 --disable-static  ---  Do not build static libraries.
 165
 166   Normally, both static and shared libraries will be built if your
 167   system supports them.
 168
 169 --enable-debug-freelist  ---  Enable freelist debugging.
 170
 171   This enables a debugging version of scm_cell and scm_double_cell,
 172   and also registers an extra primitive, the setter
 173   `gc-set-debug-check-freelist!'.
 174
 175   Configure with the --enable-debug-freelist option to enable the
 176   gc-set-debug-check-freelist! primitive, and then use:
 177
 178   (gc-set-debug-check-freelist! #t)  # turn on checking of the freelist
 179   (gc-set-debug-check-freelist! #f)  # turn off checking
 180
 181   Checking of the freelist forces a traversal of the freelist and a
 182   garbage collection before each allocation of a cell.  This can slow
 183   down the interpreter dramatically, so the setter should be used to
 184   turn on this extra processing only when necessary.
 185
 186 --enable-debug-malloc  ---  Enable malloc debugging.
 187
 188   Include code for debugging of calls to scm_malloc, scm_realloc, etc.
 189
 190   It records the number of allocated objects of each kind.  This is
 191   useful when searching for memory leaks.
 192
 193   A Guile compiled with this option provides the primitive
 194   `malloc-stats' which returns an alist with pairs of kind and the
 195   number of objects of that kind.
 196
 197 --enable-guile-debug  ---  Include internal debugging functions
 198 --disable-posix       ---  omit posix interfaces
 199 --disable-networking  ---  omit networking interfaces
 200 --disable-regex       ---  omit regular expression interfaces
 201
 202
 203 Cross building Guile  =====================================================
 204
 205 As of guile-1.5.x, the build process uses compiled C files for
 206 snarfing, and (indirectly, through libtool) for linking, and uses the
 207 guile executable for generating documentation.
 208
 209 When cross building guile, you first need to configure, build and
 210 install guile for your build host.
 211
 212 Then, you may configure guile for cross building, eg:
 213
 214     ./configure --host=i686-pc-cygwin --disable-shared
 215
 216 A C compiler for the build system is required.  The default is
 217 "PATH=/usr/bin:$PATH cc".  If that doesn't suit it can be specified
 218 with the CC_FOR_BUILD variable in the usual way, for instance
 219
 220     ./configure --host=m68k-unknown-linux-gnu CC_FOR_BUILD=/my/local/gcc
 221
 222 Guile for the build system can be specified similarly with the
 223 GUILE_FOR_BUILD variable, it defaults to just "guile".
 224
 225
 226 Using Guile Without Installing It =========================================
 227
 228 The top directory of the Guile sources contains a script called
 229 "pre-inst-guile" that can be used to run the Guile that has just been
 230 built.
 231
 232
 233 Installing SLIB ===========================================================
 234
 235 In order to use SLIB from Guile you basically only need to put the
 236 `slib' directory _in_ one of the directories on Guile's load path.
 237
 238 The standard installation is:
 239
 240   1. Obtain slib from http://www-swiss.ai.mit.edu/~jaffer/SLIB.html
 241
 242   2. Put it in Guile's data directory, that is the directory printed when
 243      you type
 244
 245        guile-config info pkgdatadir
 246
 247      at the shell prompt.  This is normally `/usr/local/share/guile', so the
 248      directory will normally have full path `/usr/local/share/guile/slib'.
 249
 250   3. Start guile as a user with write access to the data directory and type
 251
 252        (use-modules (ice-9 slib))
 253
 254      at the Guile prompt.  This will generate the slibcat catalog next to
 255      the slib directory.
 256
 257 SLIB's `require' is provided by the Guile module (ice-9 slib).
 258
 259 Example:
 260
 261   (use-modules (ice-9 slib))
 262   (require 'primes)
 263   (prime? 7)
 264
 265
 266 Guile Documentation ==================================================
 267
 268 If you've never used Scheme before, then the Guile Tutorial
 269 (guile-tut.info) is a good starting point.  The Guile Reference Manual
 270 (guile.info) is the primary documentation for Guile.  The Goops object
 271 system is documented separately (goops.info).  A copy of the R5RS
 272 Scheme specification is included too (r5rs.info).
 273
 274 Info format versions of this documentation are installed as part of
 275 the normal build process.  The texinfo sources are under the doc
 276 directory, and other formats like Postscript, PDF, DVI or HTML can be
 277 generated from them with Tex and Texinfo tools.
 278
 279 The doc directory also includes an example-smob subdirectory which has
 280 the example code from the "Defining New Types (Smobs)" chapter of the
 281 reference manual.
 282
 283 The Guile WWW page is at
 284
 285   http://www.gnu.org/software/guile/guile.html
 286
 287 It contains a link to the Guile FAQ.
 288
 289 About This Distribution ==============================================
 290
 291 Interesting files include:
 292
 293 - LICENSE, which contains the exact terms of the Guile license.
 294 - COPYING, which contains the terms of the GNU General Public License.
 295 - INSTALL, which contains general instructions for building/installing Guile.
 296 - NEWS, which describes user-visible changes since the last release of Guile.
 297
 298 Files are usually installed according to the prefix specified to
 299 configure, /usr/local by default.  Building and installing gives you:
 300
 301 Executables, in ${prefix}/bin:
 302
 303  guile --- a stand-alone interpreter for Guile.  With no arguments, this
 304         is a simple interactive Scheme interpreter.  It can also be used
 305         as an interpreter for script files; see the NEWS file for details.
 306  guile-config --- a Guile script which provides the information necessary
 307         to link your programs against the Guile library.
 308  guile-snarf --- a script to parse declarations in your C code for
 309         Scheme-visible C functions, Scheme objects to be used by C code,
 310         etc.
 311
 312 Libraries, in ${prefix}/lib.  Depending on the platform and options
 313         given to configure, you may get shared libraries in addition
 314         to or instead of these static libraries:
 315
 316  libguile.a --- an object library containing the Guile interpreter,
 317         You can use Guile in your own programs by linking against this.
 318  libguilereadline.a --- an object library containing glue code for the
 319         GNU readline library.
 320
 321  libguile-srfi-*.a --- various SRFI support libraries
 322
 323 Header files, in ${prefix}/include:
 324
 325  libguile.h, guile/gh.h, libguile/*.h --- for libguile.
 326  guile-readline/readline.h --- for guile-readline.
 327
 328 Support files, in ${prefix}/share/guile/<version>:
 329
 330  ice-9/* --- run-time support for Guile: the module system,
 331         read-eval-print loop, some R4RS code and other infrastructure.
 332  oop/* --- the Guile Object-Oriented Programming System (GOOPS)
 333  scripts/* --- executable modules, i.e., scheme programs that can be both
 334         called as an executable from the shell, and loaded and used as a
 335         module from scheme code.  See scripts/README for more info.
 336  srfi/* --- SRFI support modules.  See srfi/README for more info.
 337
 338 Automake macros, in ${prefix}/share/aclocal:
 339
 340  guile.m4
 341
 342 Documentation in Info format, in ${prefix}/info:
 343
 344  guile --- Guile reference manual.
 345
 346  guile-tut --- Guile tutorial.
 347
 348  GOOPS --- GOOPS reference manual.
 349
 350  r5rs --- Revised(5) Report on the Algorithmic Language Scheme.
 351
 352
 353 The Guile source tree is laid out as follows:
 354
 355 libguile:
 356         The Guile Scheme interpreter --- both the object library
 357         for you to link with your programs, and the executable you can run.
 358 ice-9:  Guile's module system, initialization code, and other infrastructure.
 359 guile-config:
 360         Source for the guile-config script.
 361 guile-readline:
 362         The glue code for using GNU readline with Guile.  This
 363         will be build when configure can find a recent enough readline
 364         library on your system.
 365 doc:    Documentation (see above).
 366
 367 Git Repository Access ================================================
 368
 369 Guile's source code is stored in a Git repository at Savannah.  Anyone
 370 can access it using `git-clone' from one of the following URLs:
 371
 372   git://git.sv.gnu.org/guile.git
 373   http://git.sv.gnu.org/r/guile.git
 374
 375 Developers with a Savannah SSH account can also access it from:
 376
 377   ssh://git.sv.gnu.org/srv/git/guile.git
 378
 379 The repository can also be browsed on-line at the following address:
 380
 381   http://git.sv.gnu.org/gitweb/?p=guile.git
 382
 383 For more information on Git, please see:
 384
 385   http://git.or.cz/
 386
 387 Please send problem reports to <bug-guile@gnu.org>.