X-Git-Url: https://git.hcoop.net/bpt/guile.git/blobdiff_plain/3623a1705c5f17ad197e8400944418340c32410e..9be8a338acf82d387846ea30819be75a9098048b:/README diff --git a/README b/README index 967a03161..256b7d0d6 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,99 @@ 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.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/ . + + - 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. If you don't have + pkg-config installed, or you have a version of libgc that doesn't + provide a .pc file, 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 +119,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,27 +127,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. ---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 @@ -108,10 +144,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 favour. - 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. @@ -156,16 +188,14 @@ switches specific to Guile you may find useful in some circumstances. The default is `--enable-deprecated=yes'. ---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. + 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. - 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. @@ -173,11 +203,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. - --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 @@ -191,28 +220,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 @@ -243,33 +262,23 @@ GUILE_FOR_BUILD variable, it defaults to just "guile". 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 =========================================================== @@ -304,13 +313,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 @@ -332,6 +340,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. @@ -349,8 +358,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 @@ -358,12 +365,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: @@ -404,37 +408,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 .