temporarily disable elisp exception tests

[bpt/guile.git] / README

diff --git a/README b/README
index 4950229..92d786c 100644 (file)
--- a/README
+++ b/README
@@ -1,24 +1,14 @@
-!!! 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.
 
 
 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 ===========================================
 
 
 Additional INSTALL instructions ===========================================


@@ -27,46 +17,105 @@ 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.
 
 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 ================================================
 
 Guile requires the following external packages:
 
 
 
 Required External Packages ================================================
 
 Guile requires the following external packages:
 

-  - GNU MP, at least version 4.1
+  - GNU MP, at least version 4.2

 
     GNU MP is used for bignum arithmetic.  It is available from
 
     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
 
     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
+  - 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/ .
 
 
     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 =====================================
 
 
 Special Instructions For Some Systems =====================================
 


@@ -100,10 +149,6 @@ switches specific to Guile you may find useful in some circumstances.
   implementation and helps to keep Guile reasonably clean of historic
   baggage.
 
   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.
   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.


@@ -153,16 +198,9 @@ switches specific to Guile you may find useful in some circumstances.
   'warn-deprecated) to enable and disable the detailed messaged at run
   time.
 
   '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.
 
 --disable-shared  ---  Do not build shared libraries.
 --disable-static  ---  Do not build static libraries.


@@ -206,25 +244,28 @@ switches specific to Guile you may find useful in some circumstances.
 
 Cross building Guile  =====================================================
 
 
 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
 
 
     ./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
 
     ./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 =========================================
 
 
 Using Guile Without Installing It =========================================


@@ -283,11 +324,9 @@ Example:
 
 Guile Documentation ==================================================
 
 
 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
 
 Info format versions of this documentation are installed as part of
 the normal build process.  The texinfo sources are under the doc


@@ -309,6 +348,7 @@ About This Distribution ==============================================
 Interesting files include:
 
 - LICENSE, which contains the exact terms of the Guile license.
 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.
 - 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.