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