-!!! 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.7 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.8.0.
+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.
+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 ===========================================
in the INSTALL file. Guile specific information and configure options
can be found below, including instructions for installing SLIB.
-Guile can 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 <readline/readline.h>,
-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.
+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 =====================================
treatment. If you can send us fixes for these problems, we'd be
grateful.
-SunOS 4.1: Guile's shared library support seems to be confused, but
- hey; shared libraries are confusing. You may need to configure
- Guile with a command like:
- ./configure --disable-shared
- For more information on `--disable-shared', see below, "Flags
- Accepted by Configure".
-
-HP/UX: GCC 2.7.2 (and maybe other versions) have trouble creating
- shared libraries if they depend on any non-shared libraries. GCC
- seems to have other problems as well. To work around this, we
- suggest you configure Guile to use the system's C compiler:
- CC=cc ./configure
-
-NetBSD: Perry Metzger says, "Guile will build under NetBSD only using
- gmake -- the native make will not work. (gmake is in our package
- system, so this will not be a problem when we packagize 1.3.)"
-
+ <none yet listed>
Guile specific flags Accepted by Configure =================================
your system and set things up appropriately. However, there are a few
switches specific to Guile you may find useful in some circumstances.
---with-threads --- Build with thread support
-
- Build a Guile executable and library that supports cooperative
- threading. If you use this switch, Guile will also build and
- install the QuickThreads non-preemptive threading library,
- libqthreads, which you will need to link into your programs after
- libguile. When you use `guile-config', you will pick up all
- neccessary linker flags automatically.
-
- Cooperative threads are not yet thoroughly tested; once they are,
- they will be enabled by default. The interaction with blocking I/O
- is pretty ad hoc at the moment. In our experience, bugs in the
- thread support do not affect you if you don't actually use threads.
+--without-threads --- Build without thread support
---with-modules --- Specify statically linked `modules'
+ Build a Guile executable and library that supports multi-threading.
- Guile can dynamically load `plugin modules' during runtime, using
- facilities provided by libtool. Not all platforms support this,
- however. On these platforms, you can statically link the plugin
- modules into libguile when Guile itself is built. XXX - how does
- one specify the modules?
+ 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 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.
+ 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
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_NEWCELL(), and also
- registers an extra primitive, the setter
+ 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
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_must_malloc/realloc/free.
-
- Checks that
-
- 1. objects freed by scm_must_free has been mallocated by scm_must_malloc
- 2. objects reallocated by scm_must_realloc has been allocated by
- scm_must_malloc
- 3. reallocated objects are reallocated with the same what string
+ Include code for debugging of calls to scm_malloc, scm_realloc, etc.
- But, most importantly, it records the number of allocated objects of
- each kind. This is useful when searching for memory leaks.
+ 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-arrays --- omit array and uniform array support
--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.
+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.
-When cross building guile, you first need to configure, build and
-install guile for your build host.
+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, eg:
+Then, you may configure Guile for cross building:
./configure --host=i686-pc-cygwin --disable-shared
-Two special options for cross building are available:
+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:
---with-cc-for-build --- native C compiler, to be used during build
- defaults to: `PATH=/usr/bin:$PATH cc'
+ ./configure --host=m68k-unknown-linux-gnu CC_FOR_BUILD=/my/local/gcc
---with-guile-for-build --- native Guile executable, to be used during build
- defaults to: `guile', assuming you just
- installed this guile natively.
+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 =========================================
-If you want to run Guile without installing it, set the environment
-variable `GUILE_LOAD_PATH' to a colon-separated list of directories,
-including the directory containing this INSTALL file. If you used a
-separate build directory, you'll need to include the build directory
-in the path as well.
-
-For example, suppose the Guile distribution unpacked into a directory
-called `/home/jimb/guile-snap' (so the full name of this INSTALL file
-would be `/home/jimb/guile-snap/INSTALL'). Then you might say, if
-you're using Bash or any other Bourne shell variant,
-
- export GUILE_LOAD_PATH=/home/jimb/guile-snap
+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.
-or if you're using CSH or one of its variants:
+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.
- setenv GUILE_LOAD_PATH /home/jimb/guile-snap
+For example, you can enter this environment via invoking
-You will additionally need to set your `LTDL_LIBRARY_PATH' environment
-variable to the directory in which the compiled SRFI support modules
-are created if you want to use the modules for SRFI-4, SRFI-13 or
-SRFI-14 support. Similar to the example above, this will be,
+ meta/uninstalled-env bash
- export LTDL_LIBRARY_PATH=/home/jimb/guile-snap/srfi/.libs
-
-or if you're using CSH or one of its variants:
-
- setenv LTDL_LIBRARY_PATH /home/jimb/guile-snap/srfi/.libs
+Within that shell, other packages should be able to build against
+uninstalled Guile.
Installing SLIB ===========================================================
(require 'primes)
(prime? 7)
-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.
+Guile Documentation ==================================================
-The incomplete Guile reference manual is available at
+The Guile Reference Manual (guile.info) is the primary documentation for
+Guile. A copy of the R5RS Scheme specification is included too
+(r5rs.info).
- ftp://ftp.red-bean.com/pub/guile/snapshots/guile-doc-snap.tar.gz
+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.
-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 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
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.
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
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.
+ GNU readline library.
+
libguile-srfi-*.a --- various SRFI support libraries
Header files, in ${prefix}/include:
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 ===============================
+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:
-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.
+ git://git.sv.gnu.org/guile.git
+ http://git.sv.gnu.org/r/guile.git
-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
+Developers with a Savannah SSH account can also access it from:
- <http://mail.gnu.org/mailman/listinfo/guile-cvs>
+ ssh://git.sv.gnu.org/srv/git/guile.git
+The repository can also be browsed on-line at the following address:
-Obtaining Guile ======================================================
+ http://git.sv.gnu.org/gitweb/?p=guile.git
-The latest official Guile release is available via anonymous FTP from
+For more information on Git, please see:
-ftp://ftp.gnu.org/pub/gnu/guile/guile-1.4.tar.gz
+ http://git.or.cz/
-The mailing list `guile-user@gnu.org' carries discussions, questions,
-and often answers, about Guile. To subscribe, use the Mailman mailing
-list interface at <http://mail.gnu.org/mailman/listinfo/guile-user>
-Of course, please send bug reports (and fixes!) to bug-guile@gnu.org.
+Please send problem reports to <bug-guile@gnu.org>.
HCoop / bpt / guile.git / blobdiff