X-Git-Url: http://git.hcoop.net/bpt/guile.git/blobdiff_plain/c7bb9a973aa63984020c75bd8d1c602c32138336..262098e092252c5e7ff70ab24f109c194c2002cd:/README diff --git a/README b/README dissimilarity index 85% index 866b71f91..0598f6ef3 100644 --- a/README +++ b/README @@ -1,153 +1,183 @@ -This is a nightly snapshot of Guile, 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. - -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. - -Nightly snapshots of the Guile development sources are available via -anonymous FTP from ftp.red-bean.com, as /pub/guile/guile-snap.tar.gz. - -Via the web, that's: ftp://ftp.red-bean.com/pub/guile/guile-snap.tar.gz -For getit, that's: ftp.red-bean.com:/pub/guile/guile-snap.tar.gz - - -The latest official Guile release is available via anonymous FTP from -prep.ai.mit.edu, as /pub/gnu/guile-1.1.tar.gz. - -Via the web, that's: ftp://prep.ai.mit.edu/pub/gnu/guile-1.1.tar.gz -For getit, that's: prep.ai.mit.edu:/pub/gnu/guile-1.1.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@prep.ai.mit.edu. - - -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. -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. -libqt.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. - - -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. - -qt: A cooperative threads package from Washington University, - 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. - -(The present release doesn't include any documentation; the Guile -manual is incomplete, and is currently being revised.) - - -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.12 --- 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.1p --- 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://ftp.cygnus.com/pub/tromey". - - 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 0.9h --- a system for managing the zillion hairy options needed - on various systems to produce shared libraries. Available in - "ftp://alpha.gnu.ai.mit.edu/gnu". - -You are lost in a little maze of automatically generated files, all -different. -> - - -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 seriously tuned performance and added features. He -designed many hairy but beautiful parts of the tag system and -evaluator. - -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. + +This is a 1.5 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.6.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. + +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. + +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. + +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. + +Automake macros, in ${prefix}/share/aclocal: + +guile.m4 + +Documentation in Info format, in ${prefix}/info: + +data-rep.info --- an essay on how to write C code that works with + Guile Scheme values. + +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.