X-Git-Url: http://git.hcoop.net/bpt/guile.git/blobdiff_plain/ada238b7da034fc2778bd7d84ba779809dd888cf..08b98c54cbfc5643674b46dd62cc42a90a004199:/README diff --git a/README b/README dissimilarity index 80% index b76e46bd9..6151d0d8c 100644 --- a/README +++ b/README @@ -1,162 +1,248 @@ -This is release 1.3 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. - -Please send bug reports to bug-guile@gnu.org. - -About This Distribution ============================================== - -Building and installing this distribution gives you: -guile --- a stand-alone interpreter for Guile, usually installed in - /usr/local/bin. With no arguments, this is a simple - interactive Scheme interpreter. It can also be used as an - interpreter for script files; see the NEWS file for details. -guile-config --- a Guile script which provides the information necessary - to link your programs against the Guile library. -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. -libguile.a --- an object library containing the Guile interpreter, - usually installed in /usr/local/lib. 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. -, , --- header files for - libguile.a, usually installed in /usr/local/include. -ice-9, ice-9/*.scm --- run-time support for Guile: the module - system, read-eval-print loop, some R4RS code and other - infrastructure. Usually installed in - /usr/local/share/guile/. -data-rep.info --- An essay on how to write C code that works with - Guile Scheme values. - -Interesting files include: -- INSTALL, which contains instructions on building and installing Guile. -- NEWS, which describes user-visible changes since the last release of Guile. -- COPYING, which describes the terms under which you may redistribute - Guile, and explains that there is no warranty. - -The Guile source tree is laid out as follows: - -libguile: - The Guile Scheme interpreter --- both the object library - for you to link with your programs, and the executable you can run. -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. -doc: Some preliminary documentation for Guile. The real Guile - manual is incomplete, and is currently being revised. -doc/example-smob: Sample code, discussed in the preliminary - documentation above, for a program that extends Guile with a - new data type, and functions that operate on it. - - -Anonymous CVS Access and FTP snapshots =============================== - -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. - -If you would like to receive mail when people commit changes to the -Guile CVS repository, you can subscribe to guile-cvs@egcs.cygnus.com -by sending a message to guile-cvs-subscribe@egcs.cygnus.com. Even -better, you can get daily digests of these commit messages by sending -a message to guile-cvs-digest-subscribe@egcs.cygnus.com. - -If you want to subscribe an e-mail address other than the one that -appears in your From: header, say foo@bar.com, send a mail note to -guile-cvs-subscribe-foo=bar.com@egcs.cygnus.com. - - -Hacking It Yourself ================================================== - -As distributed, Guile needs only an ANSI C compiler and a Unix system -to compile. However, Guile's makefiles, configuration scripts, and a -few other files are automatically generated, not written by hand. If -you want to make changes to the system (which we encourage!) you will -find it helpful to have the tools we use to develop Guile. They -are the following: - -Autoconf 2.13 --- a system for automatically generating `configure' - scripts from templates which list the non-portable features a - program would like to use. Available in - "ftp://prep.ai.mit.edu/pub/gnu". - -Automake 1.4 --- a system for automatically generating Makefiles that - conform to the (rather Byzantine) GNU coding standards. The - nice thing is that it takes care of hairy targets like 'make - dist' and 'make distclean', and automatically generates - Makefile dependencies. Automake is available in - "ftp://prep.ai.mit.edu/pub/gnu". - - Before using automake, you may need to copy `threads.m4' and - `guile.m4' from the top directory of the Guile core disty to - `/usr/local/share/aclocal. - -libtool 1.2 --- a system for managing the zillion hairy options needed - on various systems to produce shared libraries. Available in - "ftp://prep.ai.mit.edu/pub/gnu". - -You are lost in a little maze of automatically generated files, all -different. -> - - -Obtaining Guile ====================================================== - -The latest official Guile release is available via anonymous FTP from -prep.ai.mit.edu, as /pub/gnu/guile-1.3.tar.gz. - -Via the web, that's: ftp://prep.ai.mit.edu/pub/gnu/guile-1.3.tar.gz -For getit, that's: prep.ai.mit.edu:/pub/gnu/guile-1.3.tar.gz - -The mailing list `guile@cygnus.com' carries discussions, questions, -and often answers, about Guile. To subscribe, send mail to -guile-request@cygnus.com. Of course, please send bug reports (and -fixes!) to bug-guile@gnu.org. Note that one address is @cygnus.com, -and the other is at @gnu.org. - - -Authors And Contributors ============================================= - -Many people have generously contributed to Guile. However, any errors -are the responsibility of the primary Guile maintainer, Jim Blandy. - -Mikael Djurfeldt designed and implemented: -* the source-level debugging support (although the debugger's user - interface is not yet complete) -* stack overflow detection, -* the GDB patches to support debugging mixed Scheme/C code, -* the original implementation of weak hash tables, -* enhancements to the `threads' interface (based on Anthony Green's - work), and -* detection of circular references during printing. - -Mark Galassi contributed the Guile high-level functions (gh_*), and -wrote the guile-programmer and guile-user manuals. (These are in the -process of revision.) - -Anthony Green wrote the original version of `threads', the interface -between Guile and qt. - -Gary Houston wrote much of the Unix system call support, including the -socket support, and did a lot of work on the error handling code. - -Tom Lord librarified SCM, yielding Guile. He wrote Guile's operating -system, Ice-9, and connected Guile to Tcl/Tk and the `rx' regular -expression matcher. - -Aubrey Jaffer is the author of SCM upon which Guile is based. Guile -started from SCM version 4e1 in November -94 and is still largely -composed of the original SCM code. - -George Carrette wrote SIOD, a stand-alone scheme interpreter. -Although most of this code as been rewritten or replaced over time, -the garbage collector from SIOD is still an important part of Guile. +!!! 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. + +Please send bug reports to bug-guile@gnu.org. + +Guile Documentation ================================================== + +The doc directory contains a few articles on specific topics and some +examples, including data-rep.texi which describes the internal +representation of data types in Guile. The example-smob directory +contains example source code for the "Defining New Types (Smobs)" chapter. + +The incomplete Guile reference manual is available at + + ftp://ftp.red-bean.com/pub/guile/snapshots/guile-doc-snap.tar.gz + +Neil Jerram is working on the new reference manual, which will be +distributed with guile-core. The new manual will be synchronized with +the docstrings in the sources. Until then, please be aware that the +docstrings are likely to be more up-to-date than the old reference +manual (use `(help)' or see libguile/guile-procedures.txt which is +generated by the build process). + +The Guile WWW page is at + + http://www.gnu.org/software/guile/guile.html + +It contains a link to the Guile FAQ. + +Guile License ================================================== + +The license of Guile consists of the GNU GPL plus a special statement +giving blanket permission to link with non-free software. This is the +license statement as found in any individual file that it applies to: + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2, or (at your option) + any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this software; see the file COPYING. If not, write to + the Free Software Foundation, Inc., 59 Temple Place, Suite 330, + Boston, MA 02111-1307 USA + + As a special exception, the Free Software Foundation gives permission + for additional uses of the text contained in its release of GUILE. + + The exception is that, if you link the GUILE library with other files + to produce an executable, this does not by itself cause the + resulting executable to be covered by the GNU General Public License. + Your use of that executable is in no way restricted on account of + linking the GUILE library code into it. + + This exception does not however invalidate any other reasons why + the executable file might be covered by the GNU General Public License. + + This exception applies only to the code released by the + Free Software Foundation under the name GUILE. If you copy + code from other Free Software Foundation releases into a copy of + GUILE, as the General Public License permits, the exception does + not apply to the code that you add in this way. To avoid misleading + anyone as to the status of such modified files, you must delete + this exception notice from them. + + If you write modifications of your own for GUILE, it is your choice + whether to permit this exception to apply to your modifications. + If you do not wish that, delete this exception notice. + +Handling of Deprecated Features ====================================== + +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. + +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. + +To give you some help with this process, and to encourage (OK, nudge) +people to switch to the newer methods, Guile can emit warnings or +errors when you use a deprecated feature. There is quite a range of +possibilities, from being completely silent to giving errors at link +time. What exactly happens is determined both by the value of the +`--enable-deprecated' configuration option when Guile was built, and +by the GUILE_WARN_DEPRECATED environment variable. + +It works like this: + + When Guile has been configured with `--enable-deprecated=no' (or, + equivalently, with `--disable-deprecated') then all deprecated + features are omitted from Guile. You will get "undefined + reference", "variable unbound" or similar errors when you try to use + them. + + When `--enable-deprecated=LEVEL' has been specified (for LEVEL not + "no"), LEVEL will be used as the default value of the environment + variable GUILE_WARN_DEPRECATED. A value of "yes" is changed to + "summary" and "shutup" is changed to "no", however. + + When GUILE_WARN_DEPRECATED has the value "no", nothing special will + happen when a deprecated feature is used. + + When GUILE_WARN_DEPRECATED has the value "summary", and a deprecated + feature has been used, Guile will print this message at exit: + + Some deprecated features have been used. Set the environment + variable GUILE_WARN_DEPRECATED to "detailed" and rerun the program + to get more information. Set it to "no" to suppress this message. + + When GUILE_WARN_DEPRECATED has the value "detailed", a detailed + warning is emitted immediatly for the first use of a deprecated + feature. + +The default is `--enable-deprecated=yes'. + +About This Distribution ============================================== + +Interesting files include: + +- INSTALL, which contains instructions on building and installing Guile. +- NEWS, which describes user-visible changes since the last release of Guile. + +Files are usually installed according to the prefix specified to +configure, /usr/local by default. Building and installing gives you: + +Executables, in ${prefix}/bin: + + guile --- a stand-alone interpreter for Guile. With no arguments, this + is a simple interactive Scheme interpreter. It can also be used + as an interpreter for script files; see the NEWS file for details. + guile-config --- a Guile script which provides the information necessary + to link your programs against the Guile library. + 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 + to or instead of these static libraries: + + 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. + libguile-srfi-*.a --- various SRFI support libraries + +Header files, in ${prefix}/include: + + libguile.h, guile/gh.h, libguile/*.h --- for libguile. + guile-readline/readline.h --- for guile-readline. + +Support files, in ${prefix}/share/guile/: + + ice-9/* --- run-time support for Guile: the module system, + read-eval-print loop, some R4RS code and other infrastructure. + oop/* --- the Guile Object-Oriented Programming System (GOOPS) + scripts/* --- executable modules, i.e., scheme programs that can be both + called as an executable from the shell, and loaded and used as a + module from scheme code. See scripts/README for more info. + srfi/* --- SRFI support modules. See srfi/README for more info. + +Automake macros, in ${prefix}/share/aclocal: + + guile.m4 + +Documentation in Info format, in ${prefix}/info: + + guile --- Guile reference manual. + + guile-tut --- Guile tutorial. + + GOOPS --- GOOPS reference manual. + + r5rs --- Revised(5) Report on the Algorithmic Language Scheme. + + +The Guile source tree is laid out as follows: + +libguile: + The Guile Scheme interpreter --- both the object library + for you to link with your programs, and the executable you can run. +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 =============================== + +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. + +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 + + + + +Obtaining Guile ====================================================== + +The latest official Guile release is available via anonymous FTP from + +ftp://ftp.gnu.org/pub/gnu/guile/guile-1.4.tar.gz + +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.