X-Git-Url: http://git.hcoop.net/bpt/guile.git/blobdiff_plain/e42573315bd70d514b92458a7644057cd3ac5757..HEAD:/README diff --git a/README b/README index c4f24f88e..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 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. -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 =========================================== @@ -34,11 +24,14 @@ Guile depends on the following external libraries. - 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). +- 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 @@ -50,23 +43,26 @@ 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 +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. 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. +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://gmplib.org/ . @@ -76,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/ . - - 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 @@ -86,7 +82,39 @@ 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 - from http://www.hpl.hp.com/personal/Hans_Boehm/gc/ . + 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 ===================================== @@ -121,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. @@ -174,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. @@ -227,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 ========================================= @@ -304,10 +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. 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