tree-il: Pass the environment to warning passes.

[bpt/guile.git] / README

diff --git a/README b/README
index 967a031..c4f24f8 100644 (file)
--- a/README
+++ b/README
@@ -1,20 +1,20 @@
 !!! This is not a Guile release; it is a source tree retrieved via
 !!! 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
+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 message. !!!  [fixme: zonk on release]
 

-This is a 1.7 development version of Guile, Project GNU's extension
+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.
 
 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
+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.
 
 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.
+The next stable release will likely be version 2.0.0.

 
 Please send bug reports to bug-guile@gnu.org.
 
 
 Please send bug reports to bug-guile@gnu.org.
 


@@ -27,23 +27,66 @@ 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 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
+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).
+
+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 before
+running configure, 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.  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.1
+
+    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
+
+    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.hpl.hp.com/personal/Hans_Boehm/gc/ .

 
 
 Special Instructions For Some Systems =====================================
 
 
 Special Instructions For Some Systems =====================================


@@ -53,23 +96,7 @@ 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.
 
 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 =================================
 
 
 Guile specific flags Accepted by Configure =================================
 


@@ -77,27 +104,13 @@ 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.
 
 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
+--without-threads  ---  Build without 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.
+  Build a Guile executable and library that supports multi-threading.

 
 

-  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.
-
---with-modules  ---  Specify statically linked `modules'
-
-  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
 
 
 --enable-deprecated=LEVEL
 


@@ -110,7 +123,7 @@ switches specific to Guile you may find useful in some circumstances.
 
   Deprecated features are considered harmful; using them is likely a
   bug.  See below for the related notion of `discouraged' features,
 
   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 favour.
+  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
 
   See the file NEWS for a list of features that are currently
   deprecated.  Each entry will also tell you what you should replace


@@ -156,6 +169,11 @@ switches specific to Guile you may find useful in some circumstances.
 
   The default is `--enable-deprecated=yes'.
 
 
   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.
+

 --disable-discouraged
 
   In addition to deprecated features, Guile can also contain things
 --disable-discouraged
 
   In addition to deprecated features, Guile can also contain things


@@ -173,11 +191,10 @@ switches specific to Guile you may find useful in some circumstances.
   Normally, both static and shared libraries will be built if your
   system supports them.
 
   Normally, both static and shared libraries will be built if your
   system supports them.
 

-

 --enable-debug-freelist  ---  Enable freelist debugging.
 
 --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
   `gc-set-debug-check-freelist!'.
 
   Configure with the --enable-debug-freelist option to enable the


@@ -191,28 +208,18 @@ switches specific to Guile you may find useful in some circumstances.
   down the interpreter dramatically, so the setter should be used to
   turn on this extra processing only when necessary.
 
   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.
 
 --enable-debug-malloc  ---  Enable malloc debugging.
 

-  Include code for debugging of calls to scm_must_malloc/realloc/free.
-
-  Checks that
+  Include code for debugging of calls to scm_malloc, scm_realloc, etc.

 
 

-  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
-
-  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.
 
 
   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
 --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
 --disable-posix       ---  omit posix interfaces
 --disable-networking  ---  omit networking interfaces
 --disable-regex       ---  omit regular expression interfaces


@@ -243,33 +250,23 @@ GUILE_FOR_BUILD variable, it defaults to just "guile".
 
 Using Guile Without Installing It =========================================
 
 
 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.
+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.

 
 

-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,
+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.

 
 

-  export GUILE_LOAD_PATH=/home/jimb/guile-snap
+For example, you can enter this environment via invoking

 
 

-or if you're using CSH or one of its variants:
+    meta/uninstalled-env bash

 
 

-  setenv GUILE_LOAD_PATH /home/jimb/guile-snap
-
-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,
-
-  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 ===========================================================
 
 
 Installing SLIB ===========================================================


@@ -304,13 +301,13 @@ Example:
   (require 'primes)
   (prime? 7)
 
   (require 'primes)
   (prime? 7)
 

+

 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 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).
+(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


@@ -332,6 +329,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.


@@ -349,8 +347,6 @@ Executables, in ${prefix}/bin:
  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-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
 
 Libraries, in ${prefix}/lib.  Depending on the platform and options
         given to configure, you may get shared libraries in addition


@@ -358,12 +354,9 @@ Libraries, in ${prefix}/lib.  Depending on the platform and options
 
  libguile.a --- an object library containing the Guile interpreter,
        You can use Guile in your own programs by linking against this.
 
  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
  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:
  libguile-srfi-*.a --- various SRFI support libraries
 
 Header files, in ${prefix}/include:


@@ -404,37 +397,30 @@ libguile:
 ice-9:  Guile's module system, initialization code, and other infrastructure.
 guile-config:
        Source for the guile-config script.
 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).
 
 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>.