X-Git-Url: https://git.hcoop.net/bpt/guile.git/blobdiff_plain/1028fcb2cfd266885b0faebcbbd580dea7341c2c..HEAD:/README diff --git a/README b/README index 30b72bc23..92d786c06 100644 --- a/README +++ b/README @@ -1,24 +1,14 @@ -!!! 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 -this message. !!! [fixme: zonk on release] - -This is a 1.7 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.5.* 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 be version 1.8.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,23 +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 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 , -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= + + - 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 ===================================== @@ -53,23 +124,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. -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.)" - + Guile specific flags Accepted by Configure ================================= @@ -77,36 +132,22 @@ 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. ---with-threads --- Build with 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. +--without-threads --- Build without thread support - 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. + Build a Guile executable and library that supports multi-threading. ---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 Guile may contain features that are `deprecated'. When a feature is - deprecated, it means that it is still there and fully functional, - but that there is a better way of achieving the same thing, and we'd - rather have you use this better way. This allows us to eventually - remove the old implementation and helps to keep Guile reasonably - clean of historic baggage. + deprecated, it means that it is still there, but that there is a + better way of achieving the same thing, and we'd rather have you use + this better way. This allows us to eventually remove the old + implementation and helps to keep Guile reasonably clean of historic + baggage. See the file NEWS for a list of features that are currently deprecated. Each entry will also tell you what you should replace @@ -152,17 +193,25 @@ switches specific to Guile you may find useful in some circumstances. 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. + + 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. Normally, both static and shared libraries will be built if your system supports them. - --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 @@ -176,28 +225,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. - --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. - --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 @@ -205,56 +244,49 @@ 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 ========================================= -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. - -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, +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. - export GUILE_LOAD_PATH=/home/jimb/guile-snap +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. -or if you're using CSH or one of its variants: +For example, you can enter this environment via invoking - setenv GUILE_LOAD_PATH /home/jimb/guile-snap + meta/uninstalled-env bash -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 =========================================================== @@ -289,13 +321,12 @@ Example: (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.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 @@ -317,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. @@ -334,8 +366,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-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 @@ -343,12 +373,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. - 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 - 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: @@ -389,37 +416,30 @@ libguile: 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). -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: - + 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 -Of course, please send bug reports (and fixes!) to bug-guile@gnu.org. +Please send problem reports to .