X-Git-Url: http://git.hcoop.net/bpt/guile.git/blobdiff_plain/04873705f6d4b410e672a87c95f88eb138bc9ca8..970aac161bd7a18ea6018a7a4aad1f5b6cdb063a:/README diff --git a/README b/README dissimilarity index 63% index 68313686f..d7a22805a 100644 --- a/README +++ b/README @@ -1,242 +1,377 @@ -!!! This is not a Guile release; it is a source tree retrieved via -anonymous CVS or as a nightly snapshot at some random time after the -Guile 1.4 release. If this were a Guile release, you would not see -this message. !!! [fixme: zonk on release] - -This is a 1.5 development version of Guile, Project GNU's extension -language library. Guile is an interpreter for Scheme, packaged as a -library that you can link into your applications to give them their -own scripting language. Guile will eventually support other languages -as well, giving users of Guile-based applications a choice of -languages. - -Guile versions with an odd middle number, i.e. 1.5.* are unstable -development versions. Even middle numbers indicate stable versions. -This has been the case since the 1.3.* series. - -The next stable release will be version 1.6.0. - -Please send bug reports to bug-guile@gnu.org. - -Guile Documentation ================================================== - -The doc directory contains a few articles on specific topics and some -examples, including data-rep.texi which describes the internal -representation of data types in Guile. The example-smob directory -contains example source code for the "Defining New Types (Smobs)" chapter. - -The incomplete Guile reference manual is available at - - ftp://ftp.red-bean.com/pub/guile/snapshots/guile-doc-snap.tar.gz - -Neil Jerram is working on the new reference manual, which will be -distributed with guile-core. The new manual will be synchronized with -the docstrings in the sources. Until then, please be aware that the -docstrings are likely to be more up-to-date than the old reference -manual (use `(help)' or see libguile/guile-procedures.txt which is -generated by the build process). - -The Guile WWW page is at - - http://www.gnu.org/software/guile/guile.html - -It contains a link to the Guile FAQ. - -Guile License ================================================== - -The license of Guile consists of the GNU GPL plus a special statement -giving blanket permission to link with non-free software. This is the -license statement as found in any individual file that it applies to: - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2, or (at your option) - any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this software; see the file COPYING. If not, write to - the Free Software Foundation, Inc., 59 Temple Place, Suite 330, - Boston, MA 02111-1307 USA - - As a special exception, the Free Software Foundation gives permission - for additional uses of the text contained in its release of GUILE. - - The exception is that, if you link the GUILE library with other files - to produce an executable, this does not by itself cause the - resulting executable to be covered by the GNU General Public License. - Your use of that executable is in no way restricted on account of - linking the GUILE library code into it. - - This exception does not however invalidate any other reasons why - the executable file might be covered by the GNU General Public License. - - This exception applies only to the code released by the - Free Software Foundation under the name GUILE. If you copy - code from other Free Software Foundation releases into a copy of - GUILE, as the General Public License permits, the exception does - not apply to the code that you add in this way. To avoid misleading - anyone as to the status of such modified files, you must delete - this exception notice from them. - - If you write modifications of your own for GUILE, it is your choice - whether to permit this exception to apply to your modifications. - If you do not wish that, delete this exception notice. - -Handling of Deprecated Features ====================================== - -Guile may contain features that are `deprecated'. When a feature is -deprecated, it means that it is still there and fully functional, but -that there is a better way of achieving the same thing, and we'd -rather have you use this better way. This allows us to eventually -remove the old implementation and helps to keep Guile reasonably clean -of historic baggage. - -See the file NEWS for a list of features that are currently -deprecated. Each entry will also tell you what you should replace -your code with. - -To give you some help with this process, and to encourage (OK, nudge) -people to switch to the newer methods, Guile can emit warnings or -errors when you use a deprecated feature. There is quite a range of -possibilities, from being completely silent to giving errors at link -time. What exactly happens is determined both by the value of the -`--enable-deprecated' configuration option when Guile was built, and -by the GUILE_WARN_DEPRECATED environment variable. - -It works like this: - - When Guile has been configured with `--enable-deprecated=no' (or, - equivalently, with `--disable-deprecated') then all deprecated - features are omitted from Guile. You will get "undefined - reference", "variable unbound" or similar errors when you try to use - them. - - When `--enable-deprecated=LEVEL' has been specified (for LEVEL not - "no"), LEVEL will be used as the default value of the environment - variable GUILE_WARN_DEPRECATED. A value of "yes" is changed to - "summary" and "shutup" is changed to "no", however. - - When GUILE_WARN_DEPRECATION has the value "no", nothing special will - happen when a deprecated feature is used. - - When GUILE_WARN_DEPRECATION has the value "summary", and a deprecated - feature has been used, Guile will print this message at exit: - - Some deprecated features have been used. Set the environment - variable GUILE_WARN_DEPRECATED to "detailed" and rerun the program - to get more information. Set it to "no" to suppress this message. - - When GUILE_WARN_DEPRECATION has the value "detailed", a detailed - warning is emitted immediatly for the first use of a deprecated - feature. - -The default is `--enable-deprecated=yes'. - -About This Distribution ============================================== - -Interesting files include: - -- INSTALL, which contains instructions on building and installing Guile. -- NEWS, which describes user-visible changes since the last release of Guile. - -Files are usually installed according to the prefix specified to -configure, /usr/local by default. Building and installing gives you: - -Executables, in ${prefix}/bin: - - guile --- a stand-alone interpreter for Guile. With no arguments, this - is a simple interactive Scheme interpreter. It can also be used - as an interpreter for script files; see the NEWS file for details. - guile-config --- a Guile script which provides the information necessary - to link your programs against the Guile library. - guile-snarf --- a script to parse declarations in your C code for - Scheme-visible C functions, Scheme objects to be used by C code, - etc. - guile-tools --- a wrapper to invoke the executable modules in - subdirectory `scripts' (also installed). - -Libraries, in ${prefix}/lib. Depending on the platform and options - given to configure, you may get shared libraries in addition - to or instead of these static libraries: - - libguile.a --- an object library containing the Guile interpreter, - You can use Guile in your own programs by linking against this. - libqthreads.a --- an object library containing the QuickThreads - primitives. If you enabled thread support when you configured - Guile, you will need to link your code against this too. - libguilereadline.a --- an object library containing glue code for the - GNU readline library. See NEWS for instructions on how to enable - readline for your personal use. - libguile-srfi-*.a --- various SRFI support libraries - -Header files, in ${prefix}/include: - - libguile.h, guile/gh.h, libguile/*.h --- for libguile. - guile-readline/readline.h --- for guile-readline. - -Support files, in ${prefix}/share/guile/: - - ice-9/* --- run-time support for Guile: the module system, - read-eval-print loop, some R4RS code and other infrastructure. - oop/* --- the Guile Object-Oriented Programming System (GOOPS) - scripts/* --- executable modules, i.e., scheme programs that can be both - called as an executable from the shell, and loaded and used as a - module from scheme code. See scripts/README for more info. - srfi/* --- SRFI support modules. See srfi/README for more info. - -Automake macros, in ${prefix}/share/aclocal: - - guile.m4 - -Documentation in Info format, in ${prefix}/info: - - data-rep.info --- an essay on how to write C code that works with - Guile Scheme values. - -The Guile source tree is laid out as follows: - -libguile: - The Guile Scheme interpreter --- both the object library - for you to link with your programs, and the executable you can run. -ice-9: Guile's module system, initialization code, and other infrastructure. -guile-config: - Source for the guile-config script. -qt: A cooperative threads package from the University of Washington, - which Guile can use. If you configure Guile with the - --with-threads flag, you will need to link against the -lqt - library, found in this directory. Qt is under a separate - copyright; see `qt/README' for more details. -guile-readline: - The glue code for using GNU readline with Guile. This - will be build when configure can find a recent enough readline - library on your system. -doc: Documentation (see above). - -Anonymous CVS Access and FTP snapshots =============================== - -We make the developers' working Guile sources available via anonymous -CVS, and by nightly snapshots, accessible via FTP. See the files -`ANON-CVS' and `SNAPSHOTS' for details. - -If you would like to receive mail when people commit changes to the -Guile CVS repository, you can subscribe to guile-cvs@gnu.org by the -Mailman mailing list interface at - - - - -Obtaining Guile ====================================================== - -The latest official Guile release is available via anonymous FTP from - -ftp://ftp.gnu.org/pub/gnu/guile/guile-1.4.tar.gz - -The mailing list `guile-user@gnu.org' carries discussions, questions, -and often answers, about Guile. To subscribe, use the Mailman mailing -list interface at -Of course, please send bug reports (and fixes!) to bug-guile@gnu.org. +!!! This is not a Guile release; it is a source tree retrieved via +anonymous CVS or as a nightly snapshot at some random time after the +Guile 1.8 release. If this were a Guile release, you would not see +this message. !!! [fixme: zonk on release] + +This is a 1.9 development version of Guile, Project GNU's extension +language library. Guile is an interpreter for Scheme, packaged as a +library that you can link into your applications to give them their +own scripting language. Guile will eventually support other languages +as well, giving users of Guile-based applications a choice of +languages. + +Guile versions with an odd middle number, i.e. 1.9.* are unstable +development versions. Even middle numbers indicate stable versions. +This has been the case since the 1.3.* series. + +The next stable release will likely be version 1.10.0. + +Please send bug reports to bug-guile@gnu.org. Note that you must be +subscribed to this list first, in order to successfully send a report +to it. + +See the LICENSE file for the specific terms that apply to Guile. + + +Additional INSTALL instructions =========================================== + +Generic instructions for configuring and compiling Guile can be found +in the INSTALL file. Guile specific information and configure options +can be found below, including instructions for installing SLIB. + +Guile requires a few external packages and can optionally use a number +of external packages such as `readline' when they are available. +Guile expects to be able to find these packages in the default +compiler setup, it does not try to make any special arrangements +itself. For example, for the `readline' package, Guile expects to be +able to find the include file , without passing +any special `-I' options to the compiler. + +If you installed an external package, and you used the --prefix +installation option to install it somewhere else than /usr/local, you +must arrange for your compiler to find it by default. If that +compiler is gcc, one convenient way of making such arrangements is to +use the --with-local-prefix option during installation, naming the +same directory as you used in the --prefix option of the package. In +particular, it is not good enough to use the same --prefix option when +you install gcc and the package; you need to use the +--with-local-prefix option as well. See the gcc documentation for +more details. + + +Required External Packages ================================================ + +Guile requires the following external packages: + + - GNU MP, at least version 4.1 + + GNU MP is used for bignum arithmetic. It is available from + http://swox.com/gmp + + - libltdl from libtool, at least from libtool version 1.5.6 + + libltdl is used for loading extensions at run-time. It is + available from http://www.gnu.org/software/libtool/ + + +Special Instructions For Some Systems ===================================== + +We would like Guile to build on all systems using the simple +instructions above, but it seems that a few systems still need special +treatment. If you can send us fixes for these problems, we'd be +grateful. + + + +Guile specific flags Accepted by Configure ================================= + +If you run the configure script with no arguments, it should examine +your system and set things up appropriately. However, there are a few +switches specific to Guile you may find useful in some circumstances. + +--without-threads --- Build without thread support + + Build a Guile executable and library that supports multi-threading. + + The default is to enable threading support when your operating + system offsers 'POSIX threads'. When you do not want threading, use + `--without-threads'. + +--enable-deprecated=LEVEL + + Guile may contain features that are `deprecated'. When a feature is + deprecated, it means that it is still there, but that there is a + better way of achieving the same thing, and we'd rather have you use + this better way. This allows us to eventually remove the old + implementation and helps to keep Guile reasonably clean of historic + baggage. + + Deprecated features are considered harmful; using them is likely a + bug. See below for the related notion of `discouraged' features, + which are OK but have fallen out of favor. + + See the file NEWS for a list of features that are currently + deprecated. Each entry will also tell you what you should replace + your code with. + + To give you some help with this process, and to encourage (OK, + nudge) people to switch to the newer methods, Guile can emit + warnings or errors when you use a deprecated feature. There is + quite a range of possibilities, from being completely silent to + giving errors at link time. What exactly happens is determined both + by the value of the `--enable-deprecated' configuration option when + Guile was built, and by the GUILE_WARN_DEPRECATED environment + variable. + + It works like this: + + When Guile has been configured with `--enable-deprecated=no' (or, + equivalently, with `--disable-deprecated') then all deprecated + features are omitted from Guile. You will get "undefined + reference", "variable unbound" or similar errors when you try to + use them. + + When `--enable-deprecated=LEVEL' has been specified (for LEVEL not + "no"), LEVEL will be used as the default value of the environment + variable GUILE_WARN_DEPRECATED. A value of "yes" is changed to + "summary" and "shutup" is changed to "no", however. + + When GUILE_WARN_DEPRECATED has the value "no", nothing special + will happen when a deprecated feature is used. + + When GUILE_WARN_DEPRECATED has the value "summary", and a + deprecated feature has been used, Guile will print this message at + exit: + + Some deprecated features have been used. Set the environment + variable GUILE_WARN_DEPRECATED to "detailed" and rerun the + program to get more information. Set it to "no" to suppress + this message. + + When GUILE_WARN_DEPRECATED has the value "detailed", a detailed + warning is emitted immediatly for the first use of a deprecated + feature. + + The default is `--enable-deprecated=yes'. + + In addition to setting GUILE_WARN_DEPRECATED in the environment, you + can also use (debug-enable 'warn-deprecated) and (debug-disable + 'warn-deprecated) to enable and disable the detailed messaged at run + time. + +--disable-discouraged + + In addition to deprecated features, Guile can also contain things + that are merely `discouraged'. It is OK to continue to use these + features in old code, but new code should avoid them since there are + better alternatives. + + There is nothing wrong with a discouraged feature per se, but they + might have strange names, or be non-standard, for example. Avoiding + them will make your code better. + +--disable-shared --- Do not build shared libraries. +--disable-static --- Do not build static libraries. + + Normally, both static and shared libraries will be built if your + system supports them. + +--enable-debug-freelist --- Enable freelist debugging. + + This enables a debugging version of scm_cell and scm_double_cell, + and also registers an extra primitive, the setter + `gc-set-debug-check-freelist!'. + + Configure with the --enable-debug-freelist option to enable the + gc-set-debug-check-freelist! primitive, and then use: + + (gc-set-debug-check-freelist! #t) # turn on checking of the freelist + (gc-set-debug-check-freelist! #f) # turn off checking + + Checking of the freelist forces a traversal of the freelist and a + garbage collection before each allocation of a cell. This can slow + down the interpreter dramatically, so the setter should be used to + turn on this extra processing only when necessary. + +--enable-debug-malloc --- Enable malloc debugging. + + Include code for debugging of calls to scm_malloc, scm_realloc, etc. + + It records the number of allocated objects of each kind. This is + useful when searching for memory leaks. + + A Guile compiled with this option provides the primitive + `malloc-stats' which returns an alist with pairs of kind and the + number of objects of that kind. + +--enable-guile-debug --- Include internal debugging functions +--disable-posix --- omit posix interfaces +--disable-networking --- omit networking interfaces +--disable-regex --- omit regular expression interfaces + + +Cross building Guile ===================================================== + +As of guile-1.5.x, the build process uses compiled C files for +snarfing, and (indirectly, through libtool) for linking, and uses the +guile executable for generating documentation. + +When cross building guile, you first need to configure, build and +install guile for your build host. + +Then, you may configure guile for cross building, eg: + + ./configure --host=i686-pc-cygwin --disable-shared + +A C compiler for the build system is required. The default is +"PATH=/usr/bin:$PATH cc". If that doesn't suit it can be specified +with the CC_FOR_BUILD variable in the usual way, for instance + + ./configure --host=m68k-unknown-linux-gnu CC_FOR_BUILD=/my/local/gcc + +Guile for the build system can be specified similarly with the +GUILE_FOR_BUILD variable, it defaults to just "guile". + + +Using Guile Without Installing It ========================================= + +The top directory of the Guile sources contains a script called +"pre-inst-guile" that can be used to run the Guile that has just been +built. + + +Installing SLIB =========================================================== + +In order to use SLIB from Guile you basically only need to put the +`slib' directory _in_ one of the directories on Guile's load path. + +The standard installation is: + + 1. Obtain slib from http://www-swiss.ai.mit.edu/~jaffer/SLIB.html + + 2. Put it in Guile's data directory, that is the directory printed when + you type + + guile-config info pkgdatadir + + at the shell prompt. This is normally `/usr/local/share/guile', so the + directory will normally have full path `/usr/local/share/guile/slib'. + + 3. Start guile as a user with write access to the data directory and type + + (use-modules (ice-9 slib)) + + at the Guile prompt. This will generate the slibcat catalog next to + the slib directory. + +SLIB's `require' is provided by the Guile module (ice-9 slib). + +Example: + + (use-modules (ice-9 slib)) + (require 'primes) + (prime? 7) + + +Guile Documentation ================================================== + +If you've never used Scheme before, then the Guile Tutorial +(guile-tut.info) is a good starting point. The Guile Reference Manual +(guile.info) is the primary documentation for Guile. The Goops object +system is documented separately (goops.info). A copy of the R5RS +Scheme specification is included too (r5rs.info). + +Info format versions of this documentation are installed as part of +the normal build process. The texinfo sources are under the doc +directory, and other formats like Postscript, PDF, DVI or HTML can be +generated from them with Tex and Texinfo tools. + +The doc directory also includes an example-smob subdirectory which has +the example code from the "Defining New Types (Smobs)" chapter of the +reference manual. + +The Guile WWW page is at + + http://www.gnu.org/software/guile/guile.html + +It contains a link to the Guile FAQ. + +About This Distribution ============================================== + +Interesting files include: + +- LICENSE, which contains the exact terms of the Guile license. +- COPYING, which contains the terms of the GNU General Public License. +- INSTALL, which contains general instructions for building/installing Guile. +- NEWS, which describes user-visible changes since the last release of Guile. + +Files are usually installed according to the prefix specified to +configure, /usr/local by default. Building and installing gives you: + +Executables, in ${prefix}/bin: + + guile --- a stand-alone interpreter for Guile. With no arguments, this + is a simple interactive Scheme interpreter. It can also be used + as an interpreter for script files; see the NEWS file for details. + guile-config --- a Guile script which provides the information necessary + to link your programs against the Guile library. + guile-snarf --- a script to parse declarations in your C code for + Scheme-visible C functions, Scheme objects to be used by C code, + etc. + +Libraries, in ${prefix}/lib. Depending on the platform and options + given to configure, you may get shared libraries in addition + to or instead of these static libraries: + + libguile.a --- an object library containing the Guile interpreter, + You can use Guile in your own programs by linking against this. + libguilereadline.a --- an object library containing glue code for the + GNU readline library. + + libguile-srfi-*.a --- various SRFI support libraries + +Header files, in ${prefix}/include: + + libguile.h, guile/gh.h, libguile/*.h --- for libguile. + guile-readline/readline.h --- for guile-readline. + +Support files, in ${prefix}/share/guile/: + + ice-9/* --- run-time support for Guile: the module system, + read-eval-print loop, some R4RS code and other infrastructure. + oop/* --- the Guile Object-Oriented Programming System (GOOPS) + scripts/* --- executable modules, i.e., scheme programs that can be both + called as an executable from the shell, and loaded and used as a + module from scheme code. See scripts/README for more info. + srfi/* --- SRFI support modules. See srfi/README for more info. + +Automake macros, in ${prefix}/share/aclocal: + + guile.m4 + +Documentation in Info format, in ${prefix}/info: + + guile --- Guile reference manual. + + guile-tut --- Guile tutorial. + + GOOPS --- GOOPS reference manual. + + r5rs --- Revised(5) Report on the Algorithmic Language Scheme. + + +The Guile source tree is laid out as follows: + +libguile: + The Guile Scheme interpreter --- both the object library + for you to link with your programs, and the executable you can run. +ice-9: Guile's module system, initialization code, and other infrastructure. +guile-config: + Source for the guile-config script. +guile-readline: + The glue code for using GNU readline with Guile. This + will be build when configure can find a recent enough readline + library on your system. +doc: Documentation (see above). + +Anonymous CVS Access and FTP snapshots =============================== + +We make the developers' working Guile sources available via anonymous +CVS, and by nightly snapshots, accessible via FTP. See the files +`ANON-CVS' and `SNAPSHOTS' for details. + +If you would like to receive mail when people commit changes to the +Guile CVS repository, you can subscribe to guile-cvs@gnu.org by the +Mailman mailing list interface at + +