@setfilename user
@comment From automake's version.texi someday:
@set EDITION 1.0
-@set UPDATED 21 March 2017
+@set UPDATED 8 April 2017
@set SCMVERS 9.2.7
@settitle MIT/GNU Scheme Pucked User Manual
@comment %**end of header
@contents
@ifnottex
-@node Top, Introduction, (dir), (dir)
+@node Top
@top MIT/GNU Scheme Pucked User Manual
@insertcopying
@menu
* Introduction::
-* Changes::
-* Installation::
* Running Scheme::
* Using Scheme::
* Compiling Programs::
* Profiling::
* GNU Emacs Interface::
* Edwin::
+* Release Notes::
+* Installation::
* GNU Free Documentation License::
* Environment-variable Index::
* Option Index::
* Concept Index::
@end menu
-@node Introduction, Installation, Top, Top
+@node Introduction
@unnumbered Introduction
This document describes how to install and use MIT/GNU Scheme Pucked,
rudimentary descriptions of how to interact with the evaluator, compile
and debug programs, and use the editor.
-This experimental version is basically a snapshot of the development
-branch on Savannah with a selection of plugins. Differences between
-this ``pucked'' version and the development branch have been kept to a
-minimum. At the moment they are all about replacing microcode modules
-with plugins and extending Edwin with a Gtk screen. User visible
-effects of these changes are detailed in a following chapter.
-@xref{Changes}.
+This experimental version is a snapshot of the @code{master} branch in
+the MIT/GNU Scheme project source repository on Savannah, with
+additional plugins. The differences between this ``pucked'' version
+and @code{master} have been kept to a minimum. At the moment they are
+focused on replacing the microcode modules with plugins. A complete
+list of user-visible changes is provided in @ref{Release Notes}.
@cindex Web site
The primary distribution site for this software is
@example
@uref{http://birchwood-abbey.net/~matt/Scheme/}
@end example
-The release notes are online at the following url.
-@example
-@uref{http://birchwood-abbey.net/~matt/Scheme/release.html}.
-@end example
@cindex bugs, reporting
@cindex reporting bugs
(@pxref{Basics of Starting Scheme}), so Puck knows what versions you
are using.
-@section The Plugins
-
-This Scheme comes with several plugins. Many wrap a C library like
-@code{libgdbm} and only work on systems where that library is
-installed along with a dynamic loader by which to link to it. At the
-moment this means they are supported only on GNU/Linux systems.
-
-Some of the plugins are simple conversions of MIT/GNU Scheme's old
-microcode modules. They are already available as sample code in the
-project repository on Savannah. In this experimental version of
-MIT/GNU Scheme they have actually replaced the microcode modules.
-And a couple are plugin-able versions of Edwin and IMAIL
-@raggedright
-@multitable @columnfractions .15 .30 .55
-@headitem Option name @tab Dependencies @tab Description
-@item @code{blowfish}
-@tab @code{libssl}
-@tab Replaces the (runtime blowfish) package.
-@item @code{gdbm}
-@tab @code{libgdbm}
-@tab Replaces the (runtime gdbm) package.
-@item @code{mcrypt}
-@tab @code{libmcrypt}
-@tab Autoloaded by the (runtime crypto) package.
-@item @code{md5}
-@tab @code{libssl}
-@tab Autoloaded by the (runtime crypto) package.
-@item @code{mhash}
-@tab @code{libmhash}
-@tab Autoloaded by the (runtime crypto) package.
-@item @code{edwin}
-@tab @code{blowfish}, @code{md5}, @code{gdbm}
-@tab The original Edwin and its tty screen.
-@item @code{imail}
-@tab @code{edwin}
-@tab The original IMAIL.
-@item @code{x11}
-@tab @code{libX11}
-@tab Replaces the (runtime x-graphics) package and
-primitives of the X11 microcode module.
-@item @code{x11-screen}
-@tab @code{x11}, @code{edwin}
-@tab The original X11 screen type.
-@end multitable
-@end raggedright
-@sp 1
-Several of the plugins are experimental wrappers for GNOME3 and OpenGL
-libraries. Their source code is available from Birchwood Abbey.
-@raggedright
-@multitable @columnfractions .15 .30 .55
-@headitem Option name @tab Dependencies @tab Description
-@item @code{glib}
-@tab @code{libglib2}
-@tab GLib and GIO wrapper.
-@item @code{pango}
-@tab @code{glib}, @code{libglib2}
-@tab Pango wrapper.
-@item @code{cairo}
-@tab @code{pango}, @code{libcairo2}
-@tab Cairo wrapper.
-@item @code{gtk}
-@tab @code{cairo}, @code{libgtk-3}, @code{libgdk-pixbuf2}
-@tab Gtk+3 wrapper.
-@item @code{gtk-screen}
-@tab @code{gtk}
-@tab A Gtk screen for Edwin.
-@item @code{gl}
-@tab @code{gtk}, @code{libGLU1}
-@tab OpenGL Utilities wrapper.
-@item @code{planetarium}
-@tab @code{gtk}, @code{gl} optional
-@tab Just a tellurion at the moment.
-@end multitable
-@end raggedright
-@sp 1
-Instructions for installing Scheme and its 'mental plugins on a GNU or
-at least Unix-like system can be found in a following chapter.
-@xref{Installation}.
-
-@node Changes
-@chapter Changes
-
-This experimental version of MIT/GNU Scheme was given a new project
-name, MIT/GNU Scheme Pucked, with a new command name,
-@code{mit-scheme-pucked}, so that it can be installed alongside the
-official release. While it comes with an assortment of plugins and a
-strange name, the core of the system is largely unchanged. However
-the core is the @emph{bleeding edge core}. The head of the project's
-development branch on Savannah is merged in frequently. Thus it
-includes changes proposed for the next official release.
-
-@section Proposed Changes
-
-@itemize @bullet
-@item
-Most of the bindings that we would fluid bind with @code{fluid-let},
-e.g. @code{*parser-radix*}, are deprecated. Parameters, found in
-corresponding bindings (e.g. @code{param:parser-radix}), should be
-used instead. @footnote{Parameters will be more easily implemented in
-SMPing (Symmetrically Multi-Processing) worlds.} For example, rather
-than fluid binding @code{*parser-radix*} with @code{fluid-let}
-@example
-(fluid-let ((*parser-radix* 16))
- ...)
-@end example
-@noindent
-you should parameterize @code{param:parser-radix}
-@example
-(parameterize ((param:parser-radix 16))
- ...)
-@end example
-
-@item
-New unicode support means your old code can generate ``legacy
-strings'' suitable only for ``legacy ports''. Most string operations
-can handle legacy @emph{or} Unicode strings, but new procedures may
-only handle Unicode strings, and several old procedures are marked as
-``deprecated.''
-
-@item
-CREF now supports deprecated bindings. It will list references to
-them in your packaging construction reports (@file{.crf} files).
-@end itemize
-
-The proposed changes to the core system are intended to produce a new
-release compatible with the current release. The new release will
-support both parameters and fluid bound bindings, both legacy and
-Unicode strings. It should thus be possible to run mixtures of old
-and new code, allowing you to replace references to deprecated
-bindings in stages.
-@cindex cond-expand feature
-@cindex feature, cond-expand
-And you can use the @code{cond-expand} feature @code{pucked} to keep
-experimental replacements out of stable worlds.
-
-@section Experimental Changes
-
-The experimental code in this ``pucked'' version is almost entirely
-contained in the plugins. The core was changed only to replace the
-microcode modules and hook the Gtk screen into Edwin. Neither change
-should be apparent to the casual user. And in this world Edwin is a
-plugin; its changes should not be counted as changes to the core.
-
-If your shtick does not hack Edwin and you previously said
-@example
- $ mit-scheme --load my-shtick
-@end example
-@noindent
-you should be able to say
-@example
- $ mit-scheme-pucked --load my-shtick
-@end example
-@noindent
-and be no worse off.
-
-@noindent
-Users @emph{may} need to make the following changes to their shtick.
-
-@itemize @bullet
-@item
-The Edwin subsystem is a plugin; it is no longer included in the
-default band, @file{all.com}. However that band still handles the
-@code{--edit} command line option and provides an @code{edit}
-procedure. Either method of launching Edwin autoloads it with an
-appropriate screen type. If you are launching Edwin some other way,
-you will probably need to load a screen option first, e.g.@:
-@code{x11-screen}.
-
-@item
-The @code{(runtime gdbm)} and @code{(runtime x-graphics)} packages
-were removed. All of their bindings can now be found in the
-@code{(gdbm)} and @code{(x11 graphics)} packages. Thus @code{(runtime
-gdbm)} should be replaced with @code{(gdbm)} in package descriptions,
-and a @code{(global-definitions gdbm/)} line added. A similar
-change is needed if you are using @code{(runtime x-graphics)}.
-
-One original binding cannot be found in the new packages:
-@code{gdbm-available?}. Generally, @code{-available?} procedures are
-not supported. Plugins are unknown (cannot provide such procedures)
-until @emph{after} they successfully load (at which point such
-procedures are moot). Thus something like
-@code{(gdbm-available?)} should be replaced with
-@code{(plugin-available? "gdbm")}.
-
-@item
-The @code{(runtime postgresql)} package was removed but has not yet
-been replaced with a corresponding plugin. If you were using it, let
-Puck know.
-
-@item
-The @code{(runtime crypto)} and @code{(runtime blowfish)} packages are
-provided but deprecated. Their bindings are unassigned until
-corresponding plugins are loaded. When a band is restored these
-bindings are unassigned again. Thus a restored thread using them will
-quickly signal an error and can be aborted or restarted as
-appropriate. Four bindings, @code{blowfish-available?},
-@code{mcrypt-available?}, @code{md5-available?} and
-@code{mhash-available?}, are assigned procedures that autoload the
-appropriate options. A restarted thread is assumed to begin again
-with a call to one of these.
-
-@item
-Edwin has had a number of screen procedures turned into SOS generic
-procedures, to support the experimental Gtk screen type. Such changes
-are transparent except that loading Edwin now loads SOS.
-
-@end itemize
-
-@noindent
-Users may also want to add the following to their shtick.
-
-@itemize @bullet
-@item
-Scheme's Debian packaging includes a @file{.menu} file in
-@url{freedesktop.org} format. In the right place it makes this Scheme
-available through any @file{.menu} aware application launcher. The
-lucky user can install the @code{x11-screen} package and find a launch
-button, a picture of a lambda holding a fountain pen.
-
-@item
-The installation process includes HTML documentation by default. In
-the right place these files are available in your web browser, whether
-online or offline, using a file URL like the following Ubuntu locator.
-@example
- @url{file:///usr/share/doc/mit-scheme-pucked/html/index.html}
-@end example
-HTML documentation for installed plugins is found in the same location.
-
-@item
-Lucky users can install a Planetarium package and see some simple
-Scheme-generated graphics.
-
-@item
-And users who are @emph{really} lucky can install the Gtk Screen
-package and try out a graphical Edwin.
-@end itemize
-
-@node Installation
-@chapter Installation
-
-Debian packages are the simplest way to install. The package
-manager's dependency handling will arrange to install other necessary
-plugins and external libraries. To get a system as much like the
-original MIT/GNU Scheme as possible, able to run IMAIL in a basic X11
-screen, you will want to install the
-@code{mit-scheme-pucked-x11-screen} and @code{mit-scheme-pucked-imail}
-packages. They will require other packages to be installed first.
-
-Until the Debian packages become available in a public package
-archive, you will need to download @file{.deb} files from the website
-and use the @code{dpkg} command to install them. Instructions on the
-website should make plain what files you need. Install each in order
-with a command like this:
-@example
- sudo dpkg --install mit-scheme-pucked-9.2.7_1.deb
-@end example
-
-If you cannot install Debian packages, you can install binary tarballs
-on almost any Unix-like system. Installation involves compiling some
-C code, so your system will need a C compiler and developer packages
-for the libraries your plugins use. Installing plugins requires
-Scheme to be installed first, so you must begin by downloading and
-installing the binary for the core Scheme system.
-
-Follow the instructions on the website to download the appropriate
-core binary tarball. Its binary files contain Scheme code compiled
-for a particular computer architecture. The @samp{x86-64} and
-@samp{i386} binaries contain native instructions for
-Intel@registeredsymbol{}64 and IA-32 architecture machines. The
-@samp{svm1-32} and @samp{svm1-64} binaries contain Scheme Virtual
-Machine v1 opcodes. Machines of @emph{any} architecture can use these
-binaries by running the included virtual machine, though the virtual
-machine is 3-4 times slower than the native machine.
-
-To compile the C code take the following steps:
-@enumerate
-@item
-Unpack the tar file, e.g.@:
-@file{mit-scheme-pucked-9.2.7-i386.tar.gz}, to create the build
-directory, e.g.@:
-@file{mit-scheme-pucked-9.2.7}. For example,
-@example
-tar xzf mit-scheme-pucked-9.2.7-i386.tar.gz
-@end example
-will create a new directory @file{mit-scheme-pucked-9.2.7}.
-@item
-Move into the @file{src} subdirectory of the new directory:
-@example
-cd mit-scheme-pucked-9.2.7/src
-@end example
-@item
-Configure the software:
-@example
-./configure
-@end example
-
-By default, the software will be installed in @file{/usr/local}, in
-the subdirectories @file{bin} and @file{lib}. If you want it
-installed somewhere else, for example @file{/opt/mit-scheme-pucked}, pass the
-@option{--prefix} option to the configure script, as in the
-command line below.
-@example
-./configure --prefix=/opt/mit-scheme-pucked
-@end example
-
-The configure script accepts all the normal arguments for such
-scripts, and additionally accepts some that are specific to MIT/GNU
-Scheme. To see all the possible arguments and their meanings, run the
-command @code{./configure --help}.
-
-@item
-Build the software:
-
-@example
-make compile-microcode
-@end example
-
-@item
-Install the software:
-
-@example
-make install
-@end example
-
-Depending on configuration options and file-system permissions, you
-may need super-user privileges to do the installation step.
-@end enumerate
-
-@emph{After} you have installed Scheme, you can install the plugins.
-These are configured, built and installed in the customary GNU way.
-
-@example
-tar xzf mit-scheme-pucked-gtk-0.5-i386.tar.gz
-cd mit-scheme-pucked-gtk-0.5
-./configure
-make tags all check
-make install
-@end example
-
-The @code{make install} command will attempt to create a subdirectory
-in the first directory on the host Scheme's library path. If that
-directory is not writable by you, super-user privileges may be
-required.
-
-You can put a writable directory at the front of your host Scheme's
-library path by setting the @code{MITSCHEME_LIBRARY_PATH} environment
-variable
-@example
-export MITSCHEME_LIBRARY_PATH=~/pucked:/opt/mit-scheme-pucked
-@end example
-@noindent
-or including the @code{--library} option on the command line.
-@example
-mit-scheme-pucked --library ~/pucked:/opt/mit-scheme-pucked
-@end example
-
-A few of the included plugins wrap popular Unix libraries. To compile
-and link them you often need ``developers' packages'' installed first.
-The following table lists the included plugins and an example
-developers' package name (and shared library name). The package names
-can vary quite a bit among Unix distributions; the library names less
-so. Please see the @file{README} file in each plugin's directory
-for more information.
-@raggedright
-@multitable @columnfractions .2 .5
-@headitem Option name @tab Developer Package
-@item @code{blowfish}
-@tab @code{libssl-dev}
-@item @code{gdbm}
-@tab @code{libgdbm-dev}
-@item @code{mcrypt}
-@tab @code{libmcrypt-dev}
-@item @code{md5}
-@tab @code{libssl-dev}
-@item @code{mhash}
-@tab @code{libmhash-dev}
-@item @code{x11}
-@tab @code{libx11-dev}
-@item @code{glib}
-@tab @code{libglib2.0-dev}
-@item @code{pango}
-@tab @code{libpango1.0-dev}
-@item @code{cairo}
-@tab @code{libcairo2-dev}
-@item @code{gtk}
-@tab @code{libgtk-3-dev}
-@item @code{gl}
-@tab @code{libglu1-mesa-dev}
-@end multitable
-@end raggedright
-
-@sp 1
-After installing the software and any options, you can delete the
-build directory:
-
-@example
-cd ../
-rm -rf mit-scheme-pucked-gtk-0.5
-@end example
-
-@node Running Scheme, Using Scheme, Installation, Top
+@node Running Scheme
@chapter Running Scheme
This chapter describes how to run MIT/GNU Scheme Pucked. It also
-describes how you can customize the behavior of Scheme
-using command-line options and environment variables.
+describes how you can customize the behavior of Scheme using
+command-line options and environment variables. It assumes the
+program is installed and ready to run as described in
+@ref{Installation}.
@menu
* Basics of Starting Scheme::
* Leaving Scheme::
@end menu
-@node Basics of Starting Scheme, Customizing Scheme, Running Scheme, Running Scheme
+@node Basics of Starting Scheme
@section Basics of Starting Scheme
-MIT/GNU Scheme Pucked is invoked by typing
+The Debian packages of MIT/GNU Scheme Pucked should make the program
+available to launch in a terminal or graphical window. Depending on
+your desktop, you might select from a menu of ``applications'' or
+``programs.'' You might also search, e.g. for ``scheme'', in Ubuntu's
+Unity or another program launcher.
+
+If Scheme does not seem to be available through your launcher, you
+should still be able to run it with a shell (terminal) command line.
+Simply enter the command
@example
-mit-scheme-pucked
+mit-scheme-pucked --edit
@end example
@noindent
-in the shell. Scheme will load itself and print something like this:
+and Scheme will load and print something like this:
@smallexample
MIT/GNU Scheme Pucked running under GNU/Linux
LIAR/x86-64 4.118
@end smallexample
+It will open a graphical window if it can, else it will prompt for
+input in the terminal.
+
@noindent
-This information, which can be printed again by evaluating
+The version information shown above can be printed again by
+evaluating this expression.
@findex identify-world
@example
(identify-world)
@cindex runtime system, version
@cindex version numbers
@noindent
-tells you the following version information. @samp{Release} is the
+@samp{Release} is the
release number for the entire Scheme system. This number is changed
each time a new version of Scheme is released. @samp{Microcode} is the
version number for the part of the system that is written in C.
@samp{Edwin} is the Emacs-like text editor. There are other
subsystems you can load that will add themselves to this list.
-@node Customizing Scheme, Memory Usage, Basics of Starting Scheme, Running Scheme
+@node Customizing Scheme
@section Customizing Scheme
You can customize your setup by using a variety of tools:
to create icons that invoke Scheme with different parameters.
@end itemize
-@node Memory Usage, Command-Line Options, Customizing Scheme, Running Scheme
+@node Memory Usage
@section Memory Usage
Some of the parameters that can be customized determine how much memory
The Scheme expression @samp{(print-gc-statistics)} shows how much heap
and constant space is available (@pxref{Garbage Collection}).
-@node Command-Line Options, Custom Command-line Options, Memory Usage, Running Scheme
+@node Command-Line Options
@section Command-Line Options
Scheme accepts the command-line options detailed in the following
This option causes Edwin to start immediately when Scheme is started.
@end table
-@node Custom Command-line Options, Environment Variables, Command-Line Options, Running Scheme
+@node Custom Command-line Options
@section Custom Command-line Options
MIT/GNU Scheme provides a mechanism for you to define your own
delayed actions.
@end deffn
-@node Environment Variables, Leaving Scheme, Custom Command-line Options, Running Scheme
+@node Environment Variables
@section Environment Variables
Scheme refers to many environment variables. This section lists these
* Edwin Environment Variables::
@end menu
-@node Microcode Environment Variables, Runtime Environment Variables, Environment Variables, Environment Variables
-@subsection Environment Variables for the Microcode
+@node Microcode Environment Variables
+@subsection Microcode Environment Variables
These environment variables are referred to by the microcode (the
executable C program called @command{mit-scheme-pucked}).
@option{--stack}. The default value is @samp{128}.
@end table
-@node Runtime Environment Variables, Edwin Environment Variables, Microcode Environment Variables, Environment Variables
-@subsection Environment Variables for the Runtime System
+@node Runtime Environment Variables
+@subsection Runtime Environment Variables
These environment variables are referred to by the runtime system.
the library path.
@end table
-@node Edwin Environment Variables, , Runtime Environment Variables, Environment Variables
-@subsection Environment Variables for Edwin
+@node Edwin Environment Variables
+@subsection Edwin Environment Variables
These environment variables are referred to by Edwin.
for systems that don't support @samp{TIOCGWINSZ}.
@end table
-@node Leaving Scheme, , Environment Variables, Running Scheme
+@node Leaving Scheme
@section Leaving Scheme
There are several ways that you can leave Scheme: there are two Scheme
window, it terminates Scheme as well.
@end itemize
-@node Using Scheme, Compiling Programs, Running Scheme, Top
+@node Using Scheme
@chapter Using Scheme
This chapter describes how to use Scheme to evaluate expressions and
describe how to use the compiler, and how to debug your programs.
@menu
-* REPL::
+* The Read-Eval-Print Loop::
* Loading Files::
* World Images::
* Garbage Collection::
@end menu
-@node REPL, Loading Files, Using Scheme, Using Scheme
+@node The Read-Eval-Print Loop
@section The Read-Eval-Print Loop
@cindex REPL
* The Current REPL Environment::
@end menu
-@node The Prompt and Level Number, Interrupting, REPL, REPL
+@node The Prompt and Level Number
@subsection The Prompt and Level Number
@cindex prompt, REPL
@acronym{REPL}. If you abort out of it, the context of the error will
be destroyed, and you may not be able to find out what happened.
-@node Interrupting, Restarting, The Prompt and Level Number, REPL
+@node Interrupting
@subsection Interrupting
@kindex C-g
documented here.
@end table
-@node Restarting, The Current REPL Environment, Interrupting, REPL
+@node Restarting
@subsection Restarting
Another way to exit a @acronym{REPL} is to use the @code{restart}
@end example
@end deffn
-@node The Current REPL Environment, , Restarting, REPL
+@node The Current REPL Environment
@subsection The Current REPL Environment
@cindex current REPL environment
returned.
@end deffn
-@node Loading Files, World Images, REPL, Using Scheme
+@node Loading Files
@section Loading Files
To load files of Scheme code, use the procedure @code{load}:
executed in order from left to right.
@end deffn
-@node World Images, Garbage Collection, Loading Files, Using Scheme
+@node World Images
@section World Images
@cindex world image
The argument to @code{disk-restore} may be omitted, in which case it
defaults to the filename from which the current world was last restored.
-@node Garbage Collection, , World Images, Using Scheme
+@node Garbage Collection
@section Garbage Collection
This section describes procedures that control garbage collection.
notification is turned on, turns it off; otherwise turns it on.
@end deffn
-@node Compiling Programs, Debugging, Using Scheme, Top
+@node Compiling Programs
@chapter Compiling Programs
Note: the procedures described in this section are only available when
* Efficiency Tips::
@end menu
-@node Compilation Procedures, Declarations, Compiling Programs, Compiling Programs
+@node Compilation Procedures
@section Compilation Procedures
@deffn procedure cf filename [destination]
@deffn procedure sf filename [destination]
@code{sf} is the program that transforms a source-code file into binary
-SCode form; it is used on machines that do not support native-code
-compilation. It performs numerous optimizations that can make your
+SCode form. It performs numerous optimizations that can make your
programs run considerably faster than unoptimized interpreted code.
Also, the binary files that it generates load very quickly compared to
source-code files.
has its normal name but is put in that directory instead.
@end deffn
-@node Declarations, Efficiency Tips, Compilation Procedures, Compiling Programs
+@node Declarations
@section Declarations
@cindex declarations
* Reduction of Operators::
@end menu
-@node Standard Names, In-line Coding, Declarations, Declarations
+@node Standard Names
@subsection Standard Names
Normally, all files have a line
@end group
@end example
-@node In-line Coding, Replacement of Operators, Standard Names, Declarations
+@node In-line Coding
@subsection In-line Coding
Another useful facility is the ability to in-line code procedure
@end group
@end example
-@node Replacement of Operators, Reduction of Operators, In-line Coding, Declarations
-@subsection Operator Replacement
+@node Replacement of Operators
+@subsection Replacement of Operator
The @code{replace-operator} declaration is provided to inform the
compiler that certain operators may be replaced by other operators
@end itemize
@end deffn
-@node Reduction of Operators, , Replacement of Operators, Declarations
-@subsection Operator Reduction
+@node Reduction of Operators
+@subsection Reduction of Operators
@findex reduce-operator
The @code{reduce-operator} declaration is provided to inform the
@end itemize
@end deffn
-@node Efficiency Tips, , Declarations, Compiling Programs
+@node Efficiency Tips
@section Efficiency Tips
How you write your programs can have a large impact on how efficiently
* Flonum arithmetic::
@end menu
-@node Coding style, Global variables, Efficiency Tips, Efficiency Tips
+@node Coding style
@subsection Coding style
Scheme is a rich language, in which there are usually several ways to
portability and avoids the implementation inefficiencies described in
this section.
-@node Global variables, Type and range checking, Coding style, Efficiency Tips
+@node Global variables
@subsection Global variables
@cindex variable caches
@c
@c In all versions, top level declarations affect the whole source file.
-@node Type and range checking, Fixnum arithmetic, Global variables, Efficiency Tips
+@node Type and range checking
@subsection Type and range checking
@cindex type checking
valid.
@end deffn
-@node Fixnum arithmetic, Flonum arithmetic, Type and range checking, Efficiency Tips
+@node Fixnum arithmetic
@subsection Fixnum arithmetic
The usual arithmetic operations like @code{+} and @code{<} are called
A @dfn{fixnum} is an exact integer that is small enough to fit in a
machine word. In MIT/GNU Scheme, fixnums are 26 bits on 32-bit
machines, and 58 bits on 64-bit machines; it is reasonable to assume
-that fixnums are at least 24 bits. Fixnums are signed; they are encoded
-using 2's complement.
+that fixnums are at least 24 bits. Fixnums are signed and they are
+encoded using 2's complement.
All exact integers that are small enough to be encoded as fixnums are
always encoded as fixnums---in other words, any exact integer that is
A fruitful area for inserting fixnum operations is in the index
operations in tight loops.
-@node Flonum arithmetic, , Fixnum arithmetic, Efficiency Tips
+@node Flonum arithmetic
@subsection Flonum arithmetic
@c
@c !INCOMPLETE
For example, when called with a flonum, both @code{sqrt} and @code{asin}
can return a complex number (e.g@: with argument @code{-1.5}).
-@node Debugging, Profiling, Compiling Programs, Top
+@node Debugging
@chapter Debugging
Parts of this chapter are adapted from @cite{Don't Panic: A 6.001 User's
* Advising Procedures::
@end menu
-@node Subproblems and Reductions, Command-Line Debugger, Debugging, Debugging
+@node Subproblems and Reductions
@section Subproblems and Reductions
@cindex subproblem
for subproblem levels and reduction numbers is to experiment with the
debugging tools, especially @code{debug}.
-@node Command-Line Debugger, Debugging Aids, Subproblems and Reductions, Debugging
+@node Command-Line Debugger
@section The Command-Line Debugger
@cindex debugger
command prints a brief summary of the debugger's commands.
@end table
-@node Debugging Aids, Advising Procedures, Command-Line Debugger, Debugging
+@node Debugging Aids
@section Debugging Aids
This section describes additional commands that are useful for
@end example
@end deffn
-@node Advising Procedures, , Debugging Aids, Debugging
+@node Advising Procedures
@section Advising Procedures
Giving advice to procedures is a powerful debugging technique.
@var{procedure} is not given, the default is all advised procedures.
@end deffn
-@node Profiling, GNU Emacs Interface, Debugging, Top
+@node Profiling
@chapter Profiling
MIT/GNU Scheme provides a simple-minded statistical profiler called
the system.
@end defvr
-@node GNU Emacs Interface, Edwin, Profiling, Top
+@node GNU Emacs Interface
@chapter GNU Emacs Interface
There is an interface library, called @file{xscheme}, distributed with
Like evaluating @samp{(continue)}. (@code{xscheme-send-proceed})
@end table
-@node Edwin, GNU Free Documentation License, GNU Emacs Interface, Top
+@node Edwin
@chapter Edwin
This chapter describes how to start Edwin, the MIT/GNU Scheme text
* Last Resorts::
@end menu
-@node Starting Edwin, Leaving Edwin, Edwin, Edwin
+@node Starting Edwin
@section Starting Edwin
To use Edwin, start Scheme with the following command-line options:
Creates an X window containing Gtk widgets, mostly Scheme
canvases. This requires the @env{DISPLAY} environment variable to
have been set to the appropriate value before Scheme was started, and
-the @code{gtk-screen} option to have been loaded.
+the @code{gtk-screen} plugin to have been loaded.
@item (x)
Creates an X window and uses it as Edwin's main window.
@end table
@end defvr
-@node Leaving Edwin, Edwin Scheme Mode, Starting Edwin, Edwin
+@node Leaving Edwin
@section Leaving Edwin
Once Edwin has been entered, it can be exited in the following ways:
Emacs.
@end table
-@node Edwin Scheme Mode, Edwin Scheme Evaluation, Leaving Edwin, Edwin
-@section Scheme Mode
+@node Edwin Scheme Mode
+@section Edwin Scheme Mode
As you might expect, Edwin has special support for editing and
evaluating Scheme code. This section describes @dfn{Scheme Mode}, the
point, so in this example, the buffer would contain @samp{(quotient n d}
after running @kbd{C-u M-A}.
-@node Edwin Scheme Evaluation, Edwin REPL Mode, Edwin Scheme Mode, Edwin
-@section Evaluation
+@node Edwin Scheme Evaluation
+@section Edwin Scheme Evaluation
Scheme mode also provides commands for evaluating Scheme expressions.
The simplest evaluation command is @kbd{C-x C-e}, which evaluates the
buffer when the evaluation finishes; and you abort the evaluation using
@kbd{C-g}.
-@node Edwin REPL Mode, Edwin Debugger, Edwin Scheme Evaluation, Edwin
-@section REPL Mode
+@node Edwin REPL Mode
+@section Edwin REPL Mode
Edwin provides a special mechanism for interacting with Scheme
read-eval-print loops: @acronym{REPL} buffers. A @acronym{REPL} buffer
Your @acronym{REPL} buffer remains in the error state, allowing you to
examine it further if you wish.
-@node Edwin Debugger, Last Resorts, Edwin REPL Mode, Edwin
-@section The Edwin Debugger
+@node Edwin Debugger
+@section Edwin Debugger
The Edwin debugger is similar to the command-line debugger, except that
it takes advantage of multiple windows and Edwin's command structure to
using @kbd{M-x rename-buffer}: once it has been renamed, it will not be
automatically deleted.
-@node Last Resorts, , Edwin Debugger, Edwin
+@node Last Resorts
@section Last Resorts
When Scheme exits abnormally it tries to save any unsaved Edwin buffers.
state that prevents Edwin from running.
@end deffn
-@node GNU Free Documentation License, Environment-variable Index, Edwin, Top
+@c A full @node spec is needed here to avoid a bogus warning?
+@node Release Notes, Installation, Edwin, Top
+@chapter Release Notes
+
+This experimental version of MIT/GNU Scheme got a new project name,
+MIT/GNU Scheme Pucked, and a new command name,
+@code{mit-scheme-pucked}, so that it can be installed alongside the
+stable release. While it comes with an assortment of plugins and a
+strange name, the core of the system is largely unchanged. Note that
+the core is the @emph{bleeding edge core}. The head of the project's
+development branch on Savannah is merged in frequently. Thus it
+includes changes proposed for the next stable release.
+
+@unnumbered Proposed Changes
+
+@itemize @bullet
+@item
+Most of the bindings that we would fluid bind with @code{fluid-let},
+e.g. @code{*parser-radix*}, are deprecated. Parameters, found in
+corresponding bindings (e.g. @code{param:parser-radix}), should be
+used instead. @footnote{Parameters will be more easily implemented in
+SMPing (Symmetrically Multi-Processing) worlds.} For example, rather
+than fluid binding @code{*parser-radix*} with @code{fluid-let}
+@example
+(fluid-let ((*parser-radix* 16))
+ ...)
+@end example
+@noindent
+you should parameterize @code{param:parser-radix}
+@example
+(parameterize ((param:parser-radix 16))
+ ...)
+@end example
+
+@item
+CREF now supports deprecated bindings. It will list references to
+them in your packaging construction reports (@file{.crf} files).
+
+@item
+New unicode support means your old code can generate ``legacy
+strings'' suitable only for ``legacy ports''. Most string operations
+can handle legacy @emph{or} Unicode strings, but new procedures may
+only handle Unicode strings, and several old procedures are marked as
+``deprecated.''
+@end itemize
+
+The proposed changes to the core system are intended to produce a new
+release compatible with the current release. The new release will
+support both parameters and fluid bound bindings, both legacy and
+Unicode strings. It should thus be possible to run mixtures of old
+and new code, allowing you to replace references to deprecated
+bindings in stages.
+@cindex cond-expand feature
+@cindex feature, cond-expand
+And you can use the @code{cond-expand} feature @code{pucked} to keep
+your adaptations to this experiment out of your stable worlds.
+
+@unnumbered Experimental Changes
+
+The experimental code in this ``pucked'' version is almost entirely
+contained in the plugins. The core was changed only to replace the
+microcode modules and hook the Gtk screen into Edwin. Neither change
+should be apparent to the casual user.
+
+If your code does not hack Edwin and you previously said
+@example
+ $ mit-scheme --load my-code
+@end example
+@noindent
+you should be able to say
+@example
+ $ mit-scheme-pucked --load my-code
+@end example
+@noindent
+and be no worse off.
+
+@noindent
+Users @emph{may} need to make the following changes to their code.
+
+@itemize @bullet
+@item
+The Edwin subsystem is a plugin; it is no longer included in the
+default band @file{all.com}. However that band still handles the
+@code{--edit} command line option and provides an @code{edit}
+procedure. Either method of launching Edwin autoloads it with an
+appropriate screen type. If you are launching Edwin some other way,
+you will probably need to load a screen plugin first, e.g.@:
+@code{x11-screen}.
+
+@item
+The @code{(runtime gdbm)} and @code{(runtime x-graphics)} packages
+were removed. All of their bindings can now be found in the
+@code{(gdbm)} and @code{(x11 graphics)} packages. Thus @code{(runtime
+gdbm)} should be replaced with @code{(gdbm)} in package descriptions,
+and a @code{(global-definitions gdbm/)} line added. Similar
+changes are needed if you are using @code{(runtime x-graphics)}.
+
+One original binding cannot be found in the new packages:
+@code{gdbm-available?}. Generally, @code{-available?} procedures are
+not supported. Plugins are unknown (cannot provide such procedures)
+until @emph{after} they successfully load (at which point such
+procedures are moot). Thus something like
+@code{(gdbm-available?)} should be replaced with
+@code{(plugin-available? "gdbm")}.
+
+@item
+The @code{(runtime postgresql)} package was removed but has not yet
+been replaced with a corresponding plugin. If you were using it, let
+Puck know.
+
+@item
+The @code{(runtime crypto)} and @code{(runtime blowfish)} packages are
+provided but deprecated. Their bindings are unassigned until
+corresponding plugins are loaded. When a band is restored these
+bindings are unassigned again. Thus a restored thread using them will
+quickly signal an error and can be aborted or restarted as
+appropriate. Four bindings, @code{blowfish-available?},
+@code{mcrypt-available?}, @code{md5-available?} and
+@code{mhash-available?}, are assigned procedures that autoload the
+appropriate options. A restarted thread is assumed to begin again
+with a call to one of these.
+
+@item
+Edwin has had a number of screen procedures turned into SOS generic
+procedures, to support the experimental Gtk screen type. Such changes
+are transparent except that loading Edwin now loads SOS.
+@end itemize
+
+@noindent
+Users may also want to use the following enhancements in their code.
+
+@itemize @bullet
+@item
+The Debian packaging includes a @file{.menu} file in
+@url{freedesktop.org} format. In the right place it makes this Scheme
+available through an icon (a lambda holding a fountain pen) in a
+@file{.menu} aware application launcher.
+
+@item
+The installation process includes HTML documentation by default. In
+the right place these files are available in your web browser, whether
+online or offline, using a file URL like the following Ubuntu locator.
+@example
+@url{file:///usr/share/doc/mit-scheme-pucked/html/index.html}
+@end example
+HTML documentation for installed plugins is found in the same location.
+
+@item
+The @code{mit-scheme-pucked-planetarium} plugin can draw a simple
+tellurion, but that's about all.
+
+@item
+The @code{mit-scheme-pucked-gtk-screen} plugin allows Edwin to display
+text using Pango.
+@end itemize
+
+@c A full @node spec is needed here to avoid a bogus warning.
+@node Installation, GNU Free Documentation License, Release Notes, Top
+@chapter Installation
+
+MIT/GNU Scheme Pucked and its plugins are now available as packages
+for recent versions of Ubuntu on Intel@registeredsymbol{}64 and IA-32
+architecture machines. If
+@uref{http://birchwood-abbey.net/~matt/Scheme/} has links to packages
+for your Ubuntu, you can use your Ubuntu package manager to add,
+remove and update Scheme and its plugins. @xref{Ubuntu Installation}.
+
+Scheme is also available as ``binary'' archives that can be unpacked,
+compiled and installed on non-Ubuntu, even non-GNU/Linux operating
+systems, if they are sufficiently Unix-like. Installation requires
+something resembling the customary GNU tool chain. The Scheme
+interpreter will be built and installed much like any other (GNU) C
+program on your system. Detailed instructions for installing Scheme
+this way can be found below. @xref{Unix Installation}.
+
+@menu
+* Ubuntu Installation::
+* Unix Installation::
+@end menu
+
+@node Ubuntu Installation
+@section Ubuntu Installation
+
+Using an Ubuntu package manager, you can add Birchwood Abbey to your
+list of package sources and install or update Scheme and its plugins
+just like other packages.
+
+You should begin by installing the GPG key used to sign the packages.
+It is available from this web page:
+@example
+@url{https://savannah.gnu.org/users/mhb}
+@end example
+Click the ``Download GPG Key'' link on that page and save the
+@file{mhb-key.gpg} file. You might install it with this command:
+@example
+sudo apt-key add ~/Downloads/mhb-key.gpg
+@end example
+
+Next add the repository to your list of package sources.
+On Ubuntu 16.10 (Yakkety Yak) you would use this command:
+@example
+sudo add-apt-repository -s "deb http://birchwood-abbey.net/ubuntu/ yakkety main"
+@end example
+or by editing files in @file{/etc/apt/}.
+
+Finally, use your package manager to update its list of available
+packages and then choose the Scheme plugins you would like to install.
+Scheme itself will be automatically selected because all of the
+plugins depend on it. You might choose the
+@code{mit-scheme-pucked-x11-screen} plugin because it depends on
+Scheme and Edwin and makes Scheme a graphical X11 application like the
+original MIT/GNU Scheme. You could do this with Apt by entering the
+following commands.
+@example
+sudo apt-get update
+sudo apt-get install mit-scheme-pucked-x11-screen
+@end example
+
+You can download the package files and install them by hand. Links to
+the available package files are listed on the project home page.
+@example
+@uref{http://birchwood-abbey.net/~matt/Scheme/}
+@end example
+You will need to know your Ubuntu version (e.g. 16.10) and Debian
+machine architecture (e.g. amd64), then click on the corresponding
+link. You will need to do this for your chosen plugin, all of the
+plugins it requires, and Scheme itself (the @code{mit-scheme-pucked}
+package).
+
+For example if you want Edwin to display in an X11 window, you will
+want to install the @code{x11-screen} plugin, which requires the
+@code{edwin} plugin, which requires several more. Each entry on the
+project home page lists the package files available for a plugin
+@emph{and} all of its required plugins.
+
+After you have downloaded all required files, you might want to verify
+that each is authentic. If you saved the GPG key in
+@file{~/Downloads/mhb-key.gpg}, you can add it to your keyring like
+this:
+@example
+gpg --import ~/Downloads/mhb-key.gpg
+@end example
+Then verify the signature on e.g. the @code{mit-scheme-pucked} package
+file like this:
+@example
+gpg --verify ~/Downloads/mit-scheme-pucked_9.2.7-1_amd64.deb ???
+@end example
+
+After you have downloaded and verified all of the required files, you
+can install them, required packages first, starting with
+@code{mit-scheme-pucked} and finishing with
+@code{mit-scheme-pucked-x11-screen}.
+@verbatim
+P=~/Downloads/mit-scheme-pucked
+sudo dpkg --install ${P}_9.2.7-1_amd64.deb
+sudo dpkg --install ${P}-md5_0.2.1-1_amd64.deb
+sudo dpkg --install ${P}-gdbm_0.2.1-1_amd64.deb
+sudo dpkg --install ${P}-blowfish_0.2.1-1_amd64.deb
+sudo dpkg --install ${P}-edwin_3.116.1-1_amd64.deb
+sudo dpkg --install ${P}-x11_0.2.1-1_amd64.deb
+sudo dpkg --install ${P}-x11-screen_0.2.1-1_amd64.deb
+@end verbatim
+
+@node Unix Installation
+@section Unix Installation
+
+MIT/GNU Scheme Pucked can be built and installed on a wide variety of
+Unix-like operating systems using a ``binary distribution'' and
+developer tools like those in the GNU tool chain: a bourne-like shell,
+a @code{make} command, a C compiler and linker. The Scheme
+interpreter is built from C code and installed much like any other GNU
+C program.
+
+These are @emph{binary} distributions because they contain pre-compiled
+Scheme code in binary files. This code cannot be compiled during the
+install because there is no Scheme compiler to do the work until
+@emph{after} Scheme is installed.
+
+First download the appropriate binary distribution. To do this you
+will need to know the name of your Scheme architecture. If your
+computer has an older Intel IA-32 (32 bit) CPU, your architecture is
+named @code{i386}. If it has a newer Intel64 CPU (64 bit, e.g. a Core
+or an i3 or i5 or i7), it is named @code{x86-64}. The binary archives
+contain machine instructions for one of these, or for 32 and 64 bit
+virtual machines named @code{svm1-32} and @code{svm1-64}. The virtual
+machines are part of the Scheme interpreter and are about 6 times
+slower than the native machine.
+
+Click on the name of your Scheme machine architecture in the list of
+binaries for the core system. Save the file, which should be named
+something like @file{mit-scheme-pucked-9.2.7-amd64.tar.gz}.
+
+Compile the Scheme interpreter using the following steps:
+@enumerate
+@item
+Unpack the archive to create your build directory, e.g.@:
+@file{mit-scheme-pucked-9.2.7}. For example,
+@example
+tar xzf mit-scheme-pucked-9.2.7-i386.tar.gz
+@end example
+will create a new directory @file{mit-scheme-pucked-9.2.7}.
+@item
+Move into the @file{src} subdirectory of the new directory:
+@example
+cd mit-scheme-pucked-9.2.7/src
+@end example
+@item
+Configure the software:
+@example
+./configure
+@end example
+
+By default, the software will be installed in @file{/usr/local}, in
+the subdirectories @file{bin} and @file{lib}. If you want it
+installed somewhere else, for example @file{/opt/mit-scheme-pucked}, pass the
+@option{--prefix} option to the configure script, as in the
+command line below.
+@example
+./configure --prefix=/opt/mit-scheme-pucked
+@end example
+
+The configure script accepts all the normal arguments for such
+scripts, and additionally accepts some that are specific to MIT/GNU
+Scheme. To see all the possible arguments and their meanings, run the
+command @code{./configure --help}.
+
+@item
+Build the software:
+
+@example
+make compile-microcode
+@end example
+
+@item
+Install the software:
+
+@example
+make install
+@end example
+
+Depending on configuration options and file-system permissions, you
+may need super-user privileges to do the installation step.
+@end enumerate
+
+@unnumbered Plugin Selection and Installation
+
+The project home page lists the available plugins with short
+descriptions to help you choose from among them. Click on the
+source archive link for each plugin you would like to use. Also
+download the source for any plugins your desired plugins require. You
+will need to build and install each required plugin before the plugins
+that require it.
+
+If you are looking for the same functionality as in the stable MIT/GNU
+Scheme you will want all of the plugins listed in the ``Former
+Microcode Modules'' section of the home page. Your desired plugins
+are: blowfish, edwin, gdbm, imail, mcrypt, md5, mhash, x11, and
+x11-screen.
+
+The plugins are not distributed in binary form (except as Ubuntu
+packages). With the core Scheme system installed, their Scheme code
+can be compiled along with their C code.
+
+The plugins are all built by scripts and makefiles created by GNU
+automake (and autoconf). Thus make targets like @code{dist} and
+@code{install-html} and @code{uninstall} are defined.
+
+Installation is per the GNU custom, not unlike the core
+installation. For the Gtk+ plugin:
+@example
+tar xzf mit-scheme-pucked-gtk-0.5-i386.tar.gz
+cd mit-scheme-pucked-gtk-0.5
+./configure
+make
+make check
+make install
+@end example
+
+The @code{install} target attempts to create a subdirectory in the
+first directory on the host Scheme's library path. If that directory
+is not writable by you, super-user privileges may be required.
+
+You can put a writable directory at the front of your host Scheme's
+library path by setting the @code{MITSCHEME_LIBRARY_PATH} environment
+variable
+@example
+export MITSCHEME_LIBRARY_PATH=~/pucked:/opt/mit-scheme-pucked
+@end example
+@noindent
+or including the @code{--library} option on the command line.
+@example
+mit-scheme-pucked --library ~/pucked:/opt/mit-scheme-pucked
+@end example
+
+The build will fail if the required plugins (Cairo, Pango and GLib)
+are not installed first (and in the reverse order). It will also fail
+if the plugin is a wrapper for a C library that is not installed. The
+build needs the library header files. Often this means ``developer's
+packages'' must be installed. See the @file{README} file in each
+plugin's source archive for help in finding these files or packages.
+
+@c A full @node spec is needed here to avoid a bogus warning.
+@node GNU Free Documentation License, Environment-variable Index, Installation, Top
@appendix GNU Free Documentation License
@cindex FDL, GNU Free Documentation License
free software license, such as the GNU General Public License,
to permit their use in free software.
-@node Environment-variable Index, Option Index, GNU Free Documentation License, Top
+@node Environment-variable Index
@appendix Environment-variable Index
@printindex nv
-@node Option Index, Variable Index, Environment-variable Index, Top
+@node Option Index
@appendix Option Index
@printindex op
-@node Variable Index, Concept Index, Option Index, Top
+@node Variable Index
@appendix Variable Index
@printindex vr
-@node Concept Index, , Variable Index, Top
+@node Concept Index
@appendix Concept Index
@printindex cp
projects / mit-scheme.git / commitdiff