X-Git-Url: https://git.hcoop.net/bpt/guile.git/blobdiff_plain/3cef6a30c1bdf33a861f0f39d8f35f181a940205..HEAD:/README diff --git a/README b/README dissimilarity index 98% index 99f2897ca..92d786c06 100644 --- a/README +++ b/README @@ -1,100 +1,445 @@ -Installation ------------- - -1. Install the latest Guile from CVS. - -2. Install slib. - -3. Install Guile VM: - - % configure - % make install - % ln -s module/{system,language} /usr/local/share/guile/site/ - -4. Add the following lines to your ~/.guile: - - (cond ((string=? (car (command-line)) "guile-vm") - (use-modules (system repl repl)) - (start-repl 'gscheme) - (quit))) - -Example Session ---------------- - - % guile-vm - Guile Scheme interpreter 0.4 on Guile 1.4.1 - Copyright (C) 2001 Free Software Foundation, Inc. - - Enter `,help' for help. - gscheme@guile> (+ 1 2) - $1 = 3 - gscheme@guile> ,c -c (+ 1 2) ;; Compile into GLIL - (@asm (0 0 0 0) - (const 1) - (const 2) - (add 2) - (return 0)) - gscheme@guile> ,c (+ 1 2) ;; Compile into bootcode - Disassembly of bootcode: - - Compiled for Guile VM 0.4 - - nlocs = 0 nexts = 0 - - 0 make-int8:1 ;; 1 - 1 make-int8 2 ;; 2 - 3 add - 4 return - - gscheme@guile> (define (add x y) (+ x y)) - gscheme@guile> (add 1 2) - $2 = 3 - gscheme@guile> ,x add ;; Disassemble - Disassembly of #: - - nargs = 2 nrest = 0 nlocs = 0 nexts = 0 - - Bytecode: - - 0 local-ref 0 - 2 local-ref 1 - 4 add - 5 return - - gscheme@guile> - -Write Modules -------------- - - ---- fib.scm --------------------------- - (define-module (fib) - :use-module (system vm load) - :export (fib)) - - (load/compile "fib.gs") - ---------------------------------------- - - ---- fib.gs ---------------------------- - (define (fib n) - (if (< n 2) - 1 - (+ (fib (- n 1)) (fib (- n 2))))) - ---------------------------------------- - -Now, expressions in fib.gsm are automatically compiled and -executed by the Guile VM: - - % guile - guile> (use-modules (fib)) - guile> (time (fib 30)) - clock utime stime cutime cstime gctime - 2.80 2.79 0.00 0.00 0.00 0.00 - $1 = 1346269 - guile> (define (fib n) (if (< n 2) 1 (+ (fib (- n 1)) (fib (- n 2))))) - guile> (time (fib 30)) - clock utime stime cutime cstime gctime - 26.05 25.01 0.17 0.00 0.00 14.33 - $2 = 1346269 - -If you don't want to compile your code (e.g., for debugging purpose), -just change `load/compile' to `load'. +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 .