-!!! This is not a Guile release; it is a source tree retrieved via
-Git 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.
+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 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 <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 ================================================
- GNU MP, at least version 4.1
GNU MP is used for bignum arithmetic. It is available from
- http://swox.com/gmp
+ http://gmplib.org/ .
- - libltdl from libtool, at least from libtool version 1.5.6
+ - 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/
+ available from http://www.gnu.org/software/libtool/ .
- GNU libunistring
`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.hpl.hp.com/personal/Hans_Boehm/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 =====================================
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.
'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.
+ 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.
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
-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
+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, it defaults to just "guile".
+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 =========================================
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).
+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
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.