X-Git-Url: http://git.hcoop.net/bpt/guile.git/blobdiff_plain/0b6d8fdc28ed8af56e93157179c305fef037e0a0..HEAD:/README diff --git a/README b/README index 4e295f805..92d786c06 100644 --- 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. -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 =========================================== @@ -27,39 +17,104 @@ 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. -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 , 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.1 + - GNU MP, at least version 4.2 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, 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= + + - BDW_GC_LIBS= + + Note that because you're bypassing all pkg-config checks, you will + also have to specify libffi flags as well: + + - LIBFFI_CFLAGS= + + - LIBFFI_LIBS= Special Instructions For Some Systems ===================================== @@ -94,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. - 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. @@ -147,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. ---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. @@ -200,25 +244,28 @@ switches specific to Guile you may find useful in some circumstances. 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 ========================================= @@ -229,10 +276,10 @@ 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. -You may also build 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. +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. For example, you can enter this environment via invoking @@ -277,11 +324,9 @@ Example: 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 @@ -303,6 +348,7 @@ About This Distribution ============================================== 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.