X-Git-Url: https://git.hcoop.net/bpt/guile.git/blobdiff_plain/8828ddcab9c5734b4ed1094e4bda76232aeae20a..19e34cd7d09d1b79725a0b09056eae675afd7081:/README diff --git a/README b/README dissimilarity index 89% index 0750b4095..6151d0d8c 100644 --- a/README +++ b/README @@ -1,62 +1,248 @@ -This is a nightly snapshot of Guile, the GNU extension language -library. Please send bug reports to bug-guile@prep.ai.mit.edu. - -IMPORTANT FACTS ABOUT SNAPSHOTS: - - Please keep in mind that these sources are strictly experimental; - they will usually not be well-tested, and may not even compile on - some systems. They may contain interfaces which will change. - They will usually not be of sufficient quality for use by people - not comfortable hacking the innards of Guile. Caveat! - - However, we're providing them anyway for several reasons. We'd like - to encourage people to get involved in developing Guile. People - willing to use the bleeding edge of development can get earlier access - to new, experimental features. Patches submitted relative to recent - snapshots will be easier for us to evaluate and install, since the - patch's original sources will be closer to what we're working with. - And it allows us to start testing features earlier. - -The Guile snapshots are available via anonymous FTP from -alpha.gnu.ai.mit.edu, as /gnu/guile-snap.tar.gz. - -Via the web, that's: ftp://alpha.gnu.ai.mit.edu/gnu/guile-snap.tar.gz -For getit, that's: alpha.gnu.ai.mit.edu:/gnu/guile-snap.tar.gz - -Guile is a portable, embeddable Scheme implementation written in C. -Guile provides a machine independent execution platform that can be -linked in as a library when building extensible programs. - -Guile is derived from SCM, by Aubrey Jaffer and others. Tom Lord -librarified SCM, yielding Guile. He wrote Guile's operating system, -Ice-9, connected Guile to Tcl/Tk and the `rx' regular expression -matcher, and took care of a lot of miscellany. - -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: - -doc: Documentation for Guile, in Texinfo form. -libguile: - The Guile Scheme interpreter, packaged as an object library - for you to link with your programs. -guile: An interactive front end for the Guile Scheme interpreter. -rx: A regular expression matching library, interfaced to Guile. -ice-9: Guile's module system, initialization code, and other infrastructure. -lang: A Guile module of tools for writing lexical analyzers and parsers. -ctax: A Guile module providing a C-like syntax for Scheme. -gtcltk-lib: - Glue code for talking to tcl/tk from Guile. The Tcl/Tk - developers have big plans for the next major release of Tcl/Tk - which will make possible a clean, direct interface between - Guile and Tk, so we're providing this very simple-minded - interface until that's ready. - -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@prep.ai.mit.edu. +!!! 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.