-Installation
-------------
-
-1. Install the latest Guile from CVS.
-
-2. Install Guile VM:
-
- % configure
- % make install
- % ln -s module/{system,language} /usr/local/share/guile/site/
-
-3. Add the following lines to your ~/.guile:
-
- (cond ((string=? (car (command-line)) "guile-vm")
- (use-modules (system repl repl))
- (start-repl 'scheme)
- (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 #<program add>:
-
- 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=<compile flags for picking up libgc headers>
+
+ - BDW_GC_LIBS=<linker flags for picking up the libgc library>
+
+ Note that because you're bypassing all pkg-config checks, you will
+ also have to specify libffi flags as well:
+
+ - LIBFFI_CFLAGS=<compile flags for picking up libffi headers>
+
+ - LIBFFI_LIBS=<linker flags for picking up the libffi library>
+
+
+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.
+
+ <none yet listed>
+
+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/<version>:
+
+ 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 <bug-guile@gnu.org>.
HCoop / bpt / guile.git / blobdiff