elisp @@ macro

[bpt/guile.git] / README

diff --git a/README b/README
index f216d7d..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 2.0.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 ===========================================


@@ -35,11 +25,13 @@ Guile depends on the following external libraries.
 - libunistring
 - libgc
 - libffi
 - libunistring
 - libgc
 - libffi

-It will also use the libreadline library if it is available.  For each
-of these there is a corresponding --with-XXX-prefix option 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).
+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
 
 These options are provided by the Gnulib `havelib' module, and details
 of how they work are documented in `Searching for Libraries' in the


@@ -70,7 +62,7 @@ Required External Packages ================================================
 
 Guile requires the following 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
     http://gmplib.org/ .
 
     GNU MP is used for bignum arithmetic.  It is available from
     http://gmplib.org/ .


@@ -80,7 +72,7 @@ Guile requires the following external packages:
     libltdl is used for loading extensions at run-time.  It is
     available from http://www.gnu.org/software/libtool/ .
 
     libltdl is used for loading extensions at run-time.  It is
     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
 
     libunistring is used for Unicode string operations, such as the
     `utf*->string' procedures.  It is available from


@@ -90,7 +82,7 @@ Guile requires the following external packages:
 
     libgc (aka. the Boehm-Demers-Weiser garbage collector) is the
     conservative garbage collector used by Guile.  It is available
 
     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/ .
+    from http://www.hboehm.info/gc/ .

 
   - libffi
 
 
   - libffi
 


@@ -101,10 +93,15 @@ Guile requires the following external packages:
   - pkg-config
 
     Guile's ./configure script uses pkg-config to discover the correct
   - pkg-config
 
     Guile's ./configure script uses pkg-config to discover the correct

-    compile and link options for libgc.  If you don't have pkg-config
-    installed, or you have a version of libgc that doesn't provide a
-    .pc file, you can work around this by setting some variables as
-    part of the configure command-line:
+    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
 
 
     - PKG_CONFIG=true
 


@@ -112,6 +109,13 @@ Guile requires the following external packages:
 
     - BDW_GC_LIBS=<linker flags for picking up the libgc library>
 
 
     - 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 =====================================
 


@@ -240,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 =========================================


@@ -317,10 +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.  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