X-Git-Url: https://git.hcoop.net/bpt/guile.git/blobdiff_plain/6ca345f3219b020f5399ab674696573a692d3220..HEAD:/README diff --git a/README b/README dissimilarity index 89% index 84d2f0870..92d786c06 100644 --- a/README +++ b/README @@ -1,124 +1,445 @@ -This is release 1.3 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. - -Please send bug reports to bug-guile@gnu.org. - -About This Distribution ============================================== - -Building and installing this distribution gives you: -guile --- a stand-alone interpreter for Guile, usually installed in - /usr/local/bin. 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. -libguile.a --- an object library containing the Guile interpreter, - usually installed in /usr/local/lib. 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. -, , --- header files for - libguile.a, usually installed in /usr/local/include. -ice-9, ice-9/*.scm --- run-time support for Guile: the module - system, read-eval-print loop, some R4RS code and other - infrastructure. Usually installed in - /usr/local/share/guile/. -data-rep.info --- An essay on how to write C code that works with - Guile Scheme values. - -Interesting files include: -- INSTALL, which contains instructions on building and installing Guile. -- NEWS, which describes user-visible changes since the last release of Guile. -- COPYING, which describes the terms under which you may redistribute - Guile, and explains that there is no warranty. - -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. -doc: Some preliminary documentation for Guile. The real Guile - manual is incomplete, and is currently being revised. -doc/example-smob: Sample code, discussed in the preliminary - documentation above, for a program that extends Guile with a - new data type, and functions that operate on it. - - -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@sourceware.cygnus.com -by sending a message to guile-cvs-subscribe@sourceware.cygnus.com. Even -better, you can get daily digests of these commit messages by sending -a message to guile-cvs-digest-subscribe@sourceware.cygnus.com. - -If you want to subscribe an e-mail address other than the one that -appears in your From: header, say foo@bar.com, send a mail note to -guile-cvs-subscribe-foo=bar.com@sourceware.cygnus.com. - - -Hacking It Yourself ================================================== - -As distributed, Guile needs only an ANSI C compiler and a Unix system -to compile. However, Guile's makefiles, configuration scripts, and a -few other files are automatically generated, not written by hand. If -you want to make changes to the system (which we encourage!) you will -find it helpful to have the tools we use to develop Guile. They -are the following: - -Autoconf 2.13 --- a system for automatically generating `configure' - scripts from templates which list the non-portable features a - program would like to use. Available in - "ftp://ftp.gnu.org/pub/gnu/autoconf" - -Automake 1.4 --- a system for automatically generating Makefiles that - conform to the (rather Byzantine) GNU coding standards. The - nice thing is that it takes care of hairy targets like 'make - dist' and 'make distclean', and automatically generates - Makefile dependencies. Automake is available in - "ftp://ftp.gnu.org/pub/gnu/automake" - - Before using automake, you may need to copy `threads.m4' and - `guile.m4' from the top directory of the Guile core disty to - `/usr/local/share/aclocal. - -libtool 1.3.3 --- a system for managing the zillion hairy options needed - on various systems to produce shared libraries. Available in - "ftp://ftp.gnu.org/pub/gnu/libtool" - -You are lost in a little maze of automatically generated files, all -different. -> - - -Obtaining Guile ====================================================== - -The latest official Guile release is available via anonymous FTP from -prep.ai.mit.edu, as /pub/gnu/guile-1.3.tar.gz. - -Via the web, that's: ftp://prep.ai.mit.edu/pub/gnu/guile-1.3.tar.gz -For getit, that's: prep.ai.mit.edu:/pub/gnu/guile-1.3.tar.gz - -The mailing list `guile@sourceware.cygnus.com' carries discussions, -questions, and often answers, about Guile. To subscribe, send mail to -guile-subscribe@sourceware.cygnus.com. Of course, please send bug -reports (and fixes!) to bug-guile@gnu.org. Note that one address is -@sourceware.cygnus.com, and the other is at @gnu.org. +This is version 2.0 of Guile, Project GNU's extension language library. +Guile is an implementation of the Scheme programming language, packaged +as a library that can be linked into applications to give them their own +extension language. Guile supports other languages as well, giving +users of Guile-based applications a choice of languages. + +Please send bug reports to bug-guile@gnu.org. + +See the LICENSE file for the specific terms that apply to Guile. Note +that for any copyright year range specified as YYYY-ZZZZ in this +package, the range specifies every single year in that closed interval. + + +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 depends on the following external libraries. +- libgmp +- libiconv +- libintl +- libltdl +- libunistring +- libgc +- libffi +It will also use the libreadline library if it is available. + +There is a corresponding `--with-XXX-prefix' option for each of these +libraries (except for libgc and libffi which use `pkg-config', see +below) that you can use when invoking ./configure, if you have these +libraries installed in a location other than the standard places (/usr +and /usr/local). + +These options are provided by the Gnulib `havelib' module, and details +of how they work are documented in `Searching for Libraries' in the +Gnulib manual (http://www.gnu.org/software/gnulib/manual). The extent +to which they work on a given OS depends on whether that OS supports +encoding full library path names in executables (aka `rpath'). Also +note that using these options, and hence hardcoding full library path +names (where that is supported), makes it impossible to later move the +built executables and libraries to an installation location other than +the one that was specified at build time. + +Another possible approach is to set CPPFLAGS and LDFLAGS on the +configure command-line, so that they include -I options for all the +non-standard places where you have installed header files and -L +options for all the non-standard places where you have installed +libraries. This will allow configure and make to find those headers +and libraries during the build. E.g.: + + ../configure [...] CPPFLAGS='-I/my/include' LDFLAGS='-L/my/lib' + +The locations found will not be hardcoded into the build executables and +libraries, so with this approach you will probably also need to set +LD_LIBRARY_PATH correspondingly, to allow Guile to find the necessary +libraries again at runtime. + + +Required External Packages ================================================ + +Guile requires the following external packages: + + - GNU MP, at least version 4.2 + + GNU MP is used for bignum arithmetic. It is available from + http://gmplib.org/ . + + - libltdl from GNU Libtool, at least version 1.5.6 + + libltdl is used for loading extensions at run-time. It is + available from http://www.gnu.org/software/libtool/ . + + - GNU libunistring, at least version 0.9.3 + + libunistring is used for Unicode string operations, such as the + `utf*->string' procedures. It is available from + http://www.gnu.org/software/libunistring/ . + + - libgc, at least version 7.0 + + libgc (aka. the Boehm-Demers-Weiser garbage collector) is the + conservative garbage collector used by Guile. It is available + from http://www.hboehm.info/gc/ . + + - libffi + + libffi provides a "foreign function interface", used by the + `(system foreign)' module. It is available from + http://sourceware.org/libffi/ . + + - pkg-config + + Guile's ./configure script uses pkg-config to discover the correct + compile and link options for libgc and libffi. For this to work, + the `PKG_CONFIG_PATH' environment variable must be set to point to + the places where libgc's and libffi's `.pc' files can be found: + + PKG_CONFIG_PATH=/path/to/libgc/lib/pkgconfig:/path/to/libffi/lib/pkgconfig + + Alternatively, when pkg-config is not installed, you can work around + this by setting some variables as part of the configure + command-line: + + - PKG_CONFIG=true + + - BDW_GC_CFLAGS= + + - BDW_GC_LIBS= + + Note that because you're bypassing all pkg-config checks, you will + also have to specify libffi flags as well: + + - LIBFFI_CFLAGS= + + - LIBFFI_LIBS= + + +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. + + 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. + + Additionally, if your toolchain is new enough, you will receive + warnings at link time if you have a Guile extension that uses + deprecated functions provided by Guile. + +--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 2.0.x, the build process produces a library, libguile-2.0, +along with Guile "object files" containing bytecode to be interpreted by +Guile's virtual machine. The bytecode format depends on the endianness +and word size of the host CPU. + +Thus, when cross building Guile, you first need to configure, build and +install it for your build host. + +Then, you may configure Guile for cross building: + + ./configure --host=i686-pc-cygwin --disable-shared + +A C compiler for the build system is required. 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, which defaults to whatever `guile' executable +is found in $PATH. It must have the exact same version has the Guile +that you intend to cross-build. + + +Using Guile Without Installing It ========================================= + +The "meta/" subdirectory of the Guile sources contains a script called +"guile" that can be used to run the Guile that has just been built. Note +that this is not the same "guile" as the one that is installed; this +"guile" is a wrapper script that sets up the environment appropriately, +then invokes the Guile binary. + +You may also build external packages against an uninstalled Guile build +tree. The "uninstalled-env" script in the "meta/" subdirectory will set +up an environment with a path including "meta/", a modified dynamic +linker path, a modified PKG_CONFIG_PATH, etc. + +For example, you can enter this environment via invoking + + meta/uninstalled-env bash + +Within that shell, other packages should be able to build against +uninstalled Guile. + + +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 ================================================== + +The Guile Reference Manual (guile.info) is the primary documentation for +Guile. 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.LESSER, which contains the terms of the GNU Lesser General Public 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). + +Git Repository Access ================================================ + +Guile's source code is stored in a Git repository at Savannah. Anyone +can access it using `git-clone' from one of the following URLs: + + git://git.sv.gnu.org/guile.git + http://git.sv.gnu.org/r/guile.git + +Developers with a Savannah SSH account can also access it from: + + ssh://git.sv.gnu.org/srv/git/guile.git + +The repository can also be browsed on-line at the following address: + + http://git.sv.gnu.org/gitweb/?p=guile.git + +For more information on Git, please see: + + http://git.or.cz/ + +Please send problem reports to .