-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>