\input texinfo @c -*-texinfo-*-
@iftex
@finalout
@end iftex
@comment $Id: user.texinfo,v 1.94 2002/06/17 18:49:02 cph Exp $
@comment %**start of header (This is for running Texinfo on a region.)
@setfilename user.info
@settitle MIT Scheme User's Manual
@comment %**end of header (This is for running Texinfo on a region.)
@setchapternewpage odd
@syncodeindex vr cp
@syncodeindex fn cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp

@dircategory Programming Languages
@direntry
* MIT Scheme User: (mit-scheme-user).	MIT Scheme User's Manual
@end direntry

@ifinfo
This file documents the use of MIT Scheme.

Copyright @copyright{} 1991-2002 Massachusetts Institute of Technology

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU
Free Documentation License".
@end ifinfo

@titlepage
@title{MIT Scheme User's Manual}
@subtitle Edition 1.89
@subtitle for Scheme Release 7.7.1
@subtitle 17 June 2002
@author by Stephen Adams
@author Chris Hanson
@author and the MIT Scheme Team

@page

@vskip 0pt plus 1filll
Copyright @copyright{} 1991-2002 Massachusetts Institute of Technology

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU
Free Documentation License".
@end titlepage

@node Top, Introduction, (dir), (dir)

@ifinfo
Scheme is the UnCommon Lisp.  This Info file is the user's guide for the
MIT implementation of Scheme.  It describes how to install and run MIT
Scheme, how to execute and compile Scheme programs, and how to use
Scheme with Edwin and GNU Emacs.
@end ifinfo

@menu
* Introduction::                
* Installation::                
* Running Scheme::              
* Using Scheme::                
* Compiling Programs::          
* Debugging::                   
* GNU Emacs Interface::         
* Edwin::                       
* Release Notes::               
* GNU Free Documentation License::  
* Index::                       
@end menu

@node Introduction, Installation, Top, Top
@unnumbered Introduction

This document describes how to install and use MIT Scheme, the UnCommon
Lisp.  It gives installation instructions for all of the platforms that
we support; complete documentation of the command-line options and
environment variables that control how Scheme works; and rudimentary
descriptions of how to interact with the evaluator, compile and debug
programs, and use the editor.  The release notes are included as an
appendix.

@cindex Unix
@cindex OS/2
@cindex Windows
@cindex PC
This document discusses many operating-system specific features of the
MIT Scheme implementation.  In order to simplify the discussion, we
use abbreviations to refer to some operating systems.  When the text
uses the term @dfn{unix}, this means any of the unix systems that we
support, including GNU/Linux, *BSD, HP-UX, Ultrix, NeXT, and SunOS.
The term @dfn{OS/2} means the IBM OS/2 operating system, version 2.1
or later.  We use the term @dfn{Windows} to collectively refer to the
Microsoft Windows 32-bit operating systems: Windows 95, Windows 98,
Windows ME, Windows NT, Windows 2000, and Windows XP.  We use the term
@dfn{PC} to refer to any computer running OS/2 or Windows.  Thus we
consider a PC to be a system with a @sc{dos}-like file system, using
backslashes for directory separators, drive letters, @sc{cr-lf} line
termination, and (potentially) the hideous 8.3 short filenames.

@cindex Web site
@cindex FTP site
The primary distribution site for this software is

@example
@uref{http://www.swiss.ai.mit.edu/projects/scheme/}
@uref{ftp://ftp.swiss.ai.mit.edu/pub/mit-scheme/}
@end example

@noindent
Although our software is distributed from other sites and in other
media, the complete distribution and the most recent release is always
available at our site.

@cindex bugs, reporting
@cindex reporting bugs
To report bugs, send email to @samp{bug-cscheme@@zurich.ai.mit.edu}.
Please include the output of the @code{identify-world} procedure
(@pxref{Basics of Starting Scheme}), so we know what version of the
system you are using.

@node Installation, Running Scheme, Introduction, Top
@chapter Installation

This chapter describes how to install MIT Scheme release 7.7.  The
release is supported under several different operating systems: unix,
OS/2, and Windows.  Read the section detailing the installation for the
operating system that you are using.

@menu
* Unix Installation::           
* Windows Installation::        
* OS/2 Installation::           
* Optional Configuration::      
@end menu

@node Unix Installation, Windows Installation, Installation, Installation
@section Unix Installation

We will use as an example the installation for GNU/Linux.  The
installation for other unix systems is similar.

MIT Scheme is distributed as a compressed `tar' file.  The tar file
contains two directories, called @file{bin} and @file{lib}.  The
@file{bin} directory contains two executable files, @file{scheme} and
@file{bchscheme}.  The @file{lib} directory contains one subdirectory,
@file{lib/mit-scheme}, that Scheme uses while it is executing.

The goal of the installation is to put the executable files in a
directory where they will be executed as commands, and to put the
library files in some convenient place where Scheme can find them.

There are two ways to install this software: the conventional way in
@file{/usr/local}, and the alternative way, in locations of your
choice.  We encourage you to install this software in @file{/usr/local}
if possible.

To install the software in @file{/usr/local}, do the following

@example
@group
cd /usr/local
rm -f bin/scheme bin/bchscheme
rm -rf lib/mit-scheme
gzip -cd scheme-7.7.1-ix86-gnu-linux.tar.gz | tar xvf -
@end group
@end example

@noindent
After executing these commands, the executable files will be in
@file{/usr/local/bin}, and the library files will be in
@file{/usr/local/lib/mit-scheme}.  No further configuration is required.

To install the files in directories of your choice:

@itemize @bullet
@item
First unpack the distribution:

@example
mkdir temp
cd temp
gzip -cd scheme-7.7.1-ix86-gnu-linux.tar.gz | tar xvf -
@end example

@item
Next, move the contents of the @file{bin} directory to somewhere
convenient that is on your execution path.  For example, if you had a
directory @file{~/bin} on your path, you would do this:

@example
mv bin/* ~/bin/.
@end example

@item
Next, move or copy the @file{mit-scheme} directory somewhere
convenient.  For example, you could move it to your home directory:

@example
mv lib/mit-scheme ~/.
@end example

Note that if you have unpacked the distribution on a different drive
than the one you plan to store the @file{mit-scheme} directory on, you
must use the command @samp{cp -pr} rather than @samp{mv}.

@item
Next, you must tell Scheme where to find the @file{mit-scheme}
directory.  This can be done in one of two ways.  The first way is to
bind the environment variable @code{MITSCHEME_LIBRARY_PATH} to the full
path to the directory, e.g.@: in @code{bash} you would do

@example
export MITSCHEME_LIBRARY_PATH=~/mit-scheme
@end example

You should put this environment-variable binding in one of your shell
init files, e.g.@ for @code{bash} it might go in the @file{.bashrc} file.

The second way is to use a command-line argument when invoking Scheme,
e.g.@:

@example
scheme -library ~/mit-scheme
@end example

@item
You should now be able to run MIT Scheme.  @xref{Running Scheme}, for
more information.
@end itemize

@node Windows Installation, OS/2 Installation, Unix Installation, Installation
@section Windows Installation

This section describes how to install MIT Scheme on Windows 95,
Windows 98, Windows Me, Windows NT 4.0, Windows 2000, or Windows XP.
The software should also work on older versions of Windows NT, but we
haven't tested it there.

MIT Scheme is distributed as a self-installing executable.  Installation
of the software is straightforward.  Simply execute the downloaded file
and answer the installer's questions.  The installer will allow you to
choose the directory in which MIT Scheme is to be installed, and the
name of the folder in which the shortcuts are to be placed.

To uninstall the software, open up the @samp{Control Panel}, run
@samp{Add/Remove Programs}, and double-click on @samp{MIT Scheme 7.7}.

@node OS/2 Installation, Optional Configuration, Windows Installation, Installation
@section OS/2 Installation

This section describes how to install MIT Scheme on a machine running
OS/2 2.1 or later.  This release of MIT Scheme has been tested only on
OS/2 Warp 4.0.  It was compiled using IBM Visual Age C++ version 3.0 and
the OS/2 Toolkit version 4.0.

@menu
* OS/2 Installation Procedure::  
* Environment Variables for OS/2 Installation::  
@end menu

@node OS/2 Installation Procedure, Environment Variables for OS/2 Installation, OS/2 Installation, OS/2 Installation
@subsection OS/2 Installation Procedure

After unpacking the @sc{zip} file, @file{os2.zip}, you will have these
directories containing the following files:

@table @file
@item exe
The executable programs @file{scheme.exe} and @file{bchschem.exe}.

@item dll
The dynamic link libraries @file{blowfish.dll}, @file{gdbm.dll}, and
@file{md5.dll}.

@item doc
Documentation files in @sc{html}.

@item lib
A directory containing the data files needed by Scheme when it is
running.
@end table

Perform the following steps to install Scheme:

@enumerate
@item
Move the executable files @file{scheme.exe} and @file{bchschem.exe} from
@file{exe} to any directory that appears in your @code{PATH}
environment variable.  You may either add the @file{exe} directory to
your path by editing @file{config.sys} and rebooting, or you may move
the files in @file{exe} to an existing directory that is already on your
@code{PATH}.

Depending on your needs, you may want to keep only one of these files;
chances are you'll only be using one of them.  Of course, you may also
keep both programs around if you think you might use them both.
@xref{Memory Usage}, for more information about the tradeoffs between
these two programs.

@item
Move the dynamic link libraries from @file{dll} to any directory that
appears in your @code{LIBPATH} environment variable.  As above, you may
either add @file{dll} to your @code{LIBPATH}, or move the files in
@file{dll} to a directory that is already on your @code{LIBPATH}.

@item
You may move the @file{lib} directory anywhere you like.  You may
rename it to anything you like.  (Here at MIT, we use
@file{c:\scheme\lib}.)  After you have chosen where it will be located,
set the @code{MITSCHEME_LIBRARY_PATH} environment variable in
@file{config.sys} to be that location.

For example, if you decide to store the directory as @file{c:\schdata},
you would add the following to @file{config.sys}:

@example
SET MITSCHEME_LIBRARY_PATH=C:\SCHDATA
@end example

@noindent
(Remember that you must reboot OS/2 after editing @file{config.sys} in
order for the changes to take effect.)

You can override the setting of this environment variable with the
@code{-library} command-line option to Scheme, for example:

@example
scheme -library d:\myscm\mylib
@end example

@noindent
If you supply a @code{-library} option, it is not necessary to have the
environment variable defined.  For example, instead of editing
@file{config.sys}, you might create a @file{.cmd} file to invoke Scheme
and pass it the @code{-library} option automatically.

@item
@emph{Optional:} Move the @file{doc} directory anywhere you like, or
delete it if you do not want to keep the documentation.

@item
@emph{Optional:} Consider setting some of the environment variables
described below.
@end enumerate

@node Environment Variables for OS/2 Installation,  , OS/2 Installation Procedure, OS/2 Installation
@subsection Environment Variables

This section documents several of the environment variables that Scheme
uses, and gives an example for each one.  These are the environment
variables that must usually be defined when installing Scheme under
OS/2.  For complete documentation of all of the environment variables
used by Scheme, see @ref{Environment Variables}.

Note that environment variables are usually defined in the OS/2
@file{config.sys} file.  After editing the @file{config.sys} file, it is
necessary to reboot OS/2 before the changes will take effect.

@table @code
@item MITSCHEME_LIBRARY_PATH
@findex MITSCHEME_LIBRARY_PATH
says where to find Scheme's data files.  This is the only required
environment variable (but is not required when Scheme is invoked with
the @code{-library} command-line option).

@example
SET MITSCHEME_LIBRARY_PATH=C:\SCHEME\LIB
@end example

@item MITSCHEME_INF_DIRECTORY
@findex MITSCHEME_INF_DIRECTORY
tells Scheme where to find debugging information for the runtime system.
The default value for this environment variable is a subdirectory
@file{src} located in the directory specified by
@code{MITSCHEME_LIBRARY_PATH}.

@example
SET MITSCHEME_INF_DIRECTORY=C:\SCHEME\LIB\SRC
@end example

@item TMPDIR
@findex TMPDIR
tells Scheme the name of a directory where it can store temporary files.

@example
SET TMPDIR=C:\TMP
@end example

@item HOME
@findex HOME
tells Scheme where your ``home'' directory is located.  This is where
Scheme looks for init files, and it is also what the @file{~/} (or
@file{~\\}) filename prefix expands to.  If not specified, Scheme uses
the root directory of the current drive.

@example
SET HOME=C:\CPH
@end example

@item USER
@findex USER
tells Scheme your user name.  This is used for several purposes,
including the name that will be used as your email address.

@example
SET USER=cph
@end example

@item SHELL
@findex SHELL
tells Edwin what shell program to use in shell buffers and for running
shell commands.  If not specified, this defaults to the standard OS/2
shell, @file{cmd.exe}.

@example
SET SHELL=C:\4OS2251\4OS2.EXE
@end example
@end table

@node Optional Configuration,  , OS/2 Installation, Installation
@section Optional Configuration

As distributed, Scheme contains several large files.  You might not need
all of them, so this section will tell you what each is for so that you
can decide if you want to delete some of them.  Also, we will discuss
the two different Scheme executables, which are each useful in different
situations; you should read this to decide which is right for you.

The Scheme runtime environment and associated tools are normally
stored in @dfn{bands}, which are large memory images stored in files
(@pxref{World Images}).  Scheme requires at least one band to work
properly.  The Scheme distribution includes two bands.  These bands
are stored in the @file{lib/mit-scheme} directory on unix systems, and
the @file{lib} directory on PC systems.

@table @file
@item runtime.com
The is the basic world image, and the smallest.  It contains just the
runtime files.  This is the band that is chosen when Scheme is invoked
with no special command-line options.

@item all.com
This contains the runtime files, the native-code compiler, and Edwin.
This band is chosen when either the @code{-compiler} or @code{-edwin}
command-line options are supplied.
@end table

Depending on your needs, you may not need both of these files.  For
example, if you always want the full development environment, you
might keep @file{all.com} and delete @file{runtime.com}.  Remember
that you must keep at least one of these files to use Scheme.

In addition to bands, Scheme is distributed with two executable
programs: @file{scheme} (called @file{scheme.exe} on PC systems), and
@file{bchscheme} (called @file{bchschem.exe} on PC systems).  Normally
you will need only one of these files.

The only difference between these two programs is in how they handle
garbage collection.  @file{scheme} allocates two memory heaps, and
copies objects between the heaps to preserve them.  This means that most
of the time the other heap is occupying valuable memory but doesn't hold
any interesting data.  @file{bchscheme} allocates only one memory heap,
creates a disk file during garbage collection, copies objects into the
file, then copies them back into memory.

These programs provide you with some important performance trade-offs.
If you have plenty of memory and want the best performance, use
@file{scheme}.  If you don't have enough memory, or if you want to use
less memory and will accept slower performance, use @file{bchscheme}.
One way to tell that you don't have enough memory is to run
@file{scheme} for a while and see if your machine is paging during
garbage collection.

You might consider trying to use @file{scheme} and letting the operating
system's paging handle the lack of @sc{ram}.  But usually you will find
that using @file{bchscheme} without paging is much faster than using
@file{scheme} with paging.  Of course, if you are using @file{bchscheme}
and you're still paging, the best solution is to install more @sc{ram}.

@node Running Scheme, Using Scheme, Installation, Top
@chapter Running Scheme

This chapter describes how to run MIT Scheme.  It also describes how you
can customize the behavior of MIT Scheme using command-line options and
environment variables.

@menu
* Basics of Starting Scheme::   
* Customizing Scheme::          
* Memory Usage::                
* Command-Line Options::        
* Custom Command-line Options::  
* Environment Variables::       
* Starting Scheme from Microsoft Windows::  
* Leaving Scheme::              
@end menu

@node Basics of Starting Scheme, Customizing Scheme, Running Scheme, Running Scheme
@section Basics of Starting Scheme

Under unix and OS/2, MIT Scheme is invoked by typing

@example
scheme
@end example

@noindent
at your operating system's command interpreter.  Under Windows, MIT
Scheme is invoked by double-clicking on a shortcut.  In either case,
Scheme will load itself and print something like this:

@example
@group
Scheme saved on Monday June 17, 2002 at 12:10:46 PM
  Release 7.7.1
  Microcode 14.9
  Runtime 15.1
@end group
@end example

@noindent
This information, which can be printed again by evaluating

@findex identify-world
@example
(identify-world)
@end example

@cindex release number
@cindex microcode, version
@cindex runtime system, version
@cindex version numbers
@noindent
tells you the following version information.  @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{Runtime} is the version number for the part of the system that is
written in Scheme.

@cindex subsystem versions
@cindex SF, version
@cindex compiler, version
@cindex Edwin, version
@cindex student package, version
@cindex compatibility package, version
Following this there may be additional version numbers for specific
subsystems.  @samp{SF} refers to the scode optimization program
@code{sf}, @samp{Liar} is the native-code compiler, 
@samp{Edwin} is the Emacs-like text editor,
and @samp{6.001} is the @sc{sicp} compatibility package.

@cindex compiler, starting
You can load the compiler by giving Scheme the @code{-compiler} option:

@example
scheme -compiler
@end example

@noindent
This option causes Scheme to use a larger constant space and heap, and
to load the world image containing the compiler.

@node Customizing Scheme, Memory Usage, Basics of Starting Scheme, Running Scheme
@section Customizing Scheme

You can customize your setup by using a variety of tools:

@itemize @bullet
@item
@cindex command-line options
@dfn{Command-line options}.
Many parameters, like memory usage and the location of libraries, may be
varied by command-line options.  @xref{Command-Line Options}.

@item
@cindex command scripts
@dfn{Command scripts or batch files}.
You might like to write scripts that invoke Scheme with your favorite
command-line options.  For example, you might not have enough memory to
run Edwin or the compiler with its default memory parameters (it will
print something like ``Not enough memory for this configuration'' and
halt when started), so you can write a shell script (unix), @file{.bat}
file (Windows), or @file{.cmd} file (OS/2) that will invoke Scheme with
the appropriate @code{-heap} and other parameters.

@item
@cindex init file
Scheme supports @dfn{init files}: an init file is a file containing
Scheme code that is loaded when Scheme is started, immediately after the
identification banner, and before the input prompt is printed.  This
file is stored in your home directory, which is normally specified by
the @code{HOME} environment variable.  Under unix, the file is called
@file{.scheme.init}; on the PC it is called @file{scheme.ini}.

In addition, when Edwin starts up, it loads a separate init file from
your home directory into the Edwin environment.  This file is called
@file{.edwin} under unix, and @file{edwin.ini} on the PC
(@pxref{Starting Edwin}).

You can use both of these files to define new procedures or commands, or
to change defaults in the system.

The @code{-no-init-file} command-line option causes Scheme to ignore
the@* @file{.scheme.init} file (@pxref{Command-Line Options}).

@item
@dfn{Environment variables}.  Most microcode parameters, and some
runtime system and Edwin parameters, can be specified by means of
environment variables.  @xref{Environment Variables}.

@item
@dfn{Icons}.
@cindex icons
Under OS/2 and Windows, and with some window managers under X11, it is
possible to create icons that invoke Scheme with different parameters.
@end itemize

@node Memory Usage, Command-Line Options, Customizing Scheme, Running Scheme
@section Memory Usage

Some of the parameters that can be customized determine how much memory
Scheme uses and how that memory is used.  This section describes how
Scheme's memory is organized and used; subsequent sections describe
command-line options and environment variables that you can use to
customize this usage for your needs.

Scheme uses four kinds of memory:
@cindex memory

@itemize @bullet
@item
@cindex stack space
A @dfn{stack} that is used for recursive procedure calls.

@item
@cindex heap space
A @dfn{heap} that is used for dynamically allocated objects, like
@samp{cons} cells and strings.  Storage used for objects in the heap
that become unreferenced is eventually reclaimed by @dfn{garbage
collection}.

@item
@cindex constant space
A @dfn{constant space} that is used for allocated objects, like the
heap.
Unlike the heap, storage used for objects in constant space is not
reclaimed by garbage collection.
Constant space is used for objects that are essentially permanent, like
procedures in the runtime system.

@item
Some extra storage that is used by the microcode (the part of the system
that is implemented in C).
@end itemize

@noindent
All kinds of memory except the last may be controlled either by
command-line options or by environment variables.

@findex scheme
@findex bchscheme
MIT Scheme uses a two-space copying garbage collector for reclaiming
storage in the heap.  There are two versions of Scheme which handle
garbage collection differently.  The standard Scheme, called
@file{scheme} under unix and @file{scheme.exe} on the PC, has two heaps,
one for each ``space''.  An alternative, called @file{bchscheme} under
unix and @file{bchschem.exe} on the PC, has one heap and uses a disk
file for the other ``space'', thus trading memory usage against garbage
collection speed (@pxref{Optional Configuration}).

The total storage required by @file{scheme} is:

@example
@var{stack} + (@var{constant} + 2*@var{heap}) + @var{extra}
@end example

@noindent
where @var{stack}, @var{constant} and @var{heap} are parameters that are
selected when @file{scheme} starts.  For @file{bchscheme}, which has
only one heap in memory, the equation is

@example
@var{stack} + (@var{constant} + @var{heap}) + @var{extra}
@end example

Once the storage is allocated for the constant space and the heap,
Scheme will dynamically adjust the proportion of the total that is used
for constant space; the stack and extra microcode storage is not
included in this adjustment.  Previous versions of MIT Scheme needed to
be told the amount of constant space that was required when loading
bands with the @code{-band} option.  Dynamic adjustment of the heap and
constant space avoids this problem.

If the size of the constant space is not specified, it is automatically
set to the correct size for the band being loaded.  Thus, in general it
is rarely necessary to explicitly set the size of the constant space.
Additionally, each band requires a small amount of heap space; this
amount is added to any specified heap size, so that the specified heap
size is the amount of free space available.

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
@section Command-Line Options

Scheme accepts the command-line options detailed in the following
sections.  The options may appear in any order, with the restriction
that the microcode options must appear before the runtime options, and
the runtime options must appear before any other arguments on the
command line.  Any arguments other than these options will generate a
warning message when Scheme starts.  If you want to define your own
command-line options, see @ref{Custom Command-line Options}.

These are the microcode options:

@table @code
@item -compiler
@findex -compiler
@findex MITSCHEME_COMPILER_BAND
This option specifies defaults appropriate for loading the compiler.  It
specifies the use of large sizes, exactly like @code{-large}; if the
@code{-band} option is also specified, that is the only effect of this
option.  Otherwise, the default band's filename is the value of the
environment variable @code{MITSCHEME_COMPILER_BAND}, if defined, or
@file{compiler.com}; the library directories are searched to locate this
file.

@item -edwin
@findex -edwin
@findex MITSCHEME_EDWIN_BAND
This option specifies defaults appropriate for loading the editor.  It
specifies the use of large sizes, exactly like @code{-large}; if the
@code{-band} option is also specified, that is the only effect of this
option.  Otherwise, the default band's filename is the value of the
environment variable @code{MITSCHEME_EDWIN_BAND}, if defined, or
@file{edwin.com}; the library directories are searched to locate this
file.

@item -compiler -edwin
@findex MITSCHEME_ALL_BAND
If both the @code{-compiler} and @code{-edwin} options are given, Scheme
will load an environment containing both the compiler and the editor.
The default band's filename is the value of the environment variable
@code{MITSCHEME_ALL_BAND}, if defined, or @file{all.com}; the library
directories are searched to locate this file.

@item -band @var{filename}
@findex -band
@findex MITSCHEME_BAND
@cindex world image
@cindex band
Specifies the initial world image file (@dfn{band}) to be loaded.
Searches for @var{filename} in the working directory and the library
directories, using the full pathname of the first readable file of that
name.  If @var{filename} is an absolute pathname (on unix, this means it
starts with @file{/}), then no search occurs --- @var{filename} is
tested for readability and then used directly.  If this option isn't
given, the filename is the value of the environment variable
@code{MITSCHEME_BAND}, or if that isn't defined, @file{runtime.com}; in
these cases the library directories are searched, but not the working
directory.

@item -large
@findex -large
Specifies that large heap, constant, and stack sizes should be used.
These are specified by the environment variables

@findex MITSCHEME_LARGE_HEAP
@findex MITSCHEME_LARGE_CONSTANT
@findex MITSCHEME_LARGE_STACK
@example
@group
MITSCHEME_LARGE_HEAP
MITSCHEME_LARGE_CONSTANT
MITSCHEME_LARGE_STACK
@end group
@end example

@noindent
If this option isn't given, the small sizes are used, specified by the
environment variables

@findex MITSCHEME_SMALL_HEAP
@findex MITSCHEME_SMALL_CONSTANT
@findex MITSCHEME_SMALL_STACK
@example
@group
MITSCHEME_SMALL_HEAP
MITSCHEME_SMALL_CONSTANT
MITSCHEME_SMALL_STACK
@end group
@end example

@noindent
There are reasonable built-in defaults for all of these environment
variables, should any of them be undefined.  Note that any or all of the
defaults can be individually overridden by the @code{-heap},
@code{-constant}, and @code{-stack} options.

@findex print-gc-statistics
Note: the Scheme expression @samp{(print-gc-statistics)} shows how much
heap and constant space is available and in use (@pxref{Garbage
Collection}).

@item -heap @var{blocks}
@findex -heap
Specifies the size of the heap in 1024-word blocks.  Overrides any
default.  Normally two such heaps are allocated; @file{bchscheme}
allocates only one, and uses a disk file for the other.

The size specified by this option is incremented by the amount of heap
space needed by the band being loaded.  Consequently, @code{-heap}
specifies how much free space will be available in the heap when Scheme
starts, independent of the amount of heap already consumed by the band.

@item -constant @var{blocks}
@findex -constant
Specifies the size of constant space in 1024-word blocks.  Overrides any
default.  Constant space holds the compiled code for the runtime system
and other subsystems.

@item -stack @var{blocks}
@findex -stack
Specifies the size of the stack in 1024-word blocks.  Overrides any
default.  This is Scheme's stack, @emph{not} the unix stack used by C
programs.

@item -option-summary
@findex -option-summary
Causes Scheme to write an option summary to standard error.  This shows
the values of all of the settable microcode option variables.

@item -emacs
@findex -emacs
Specifies that Scheme is running as a subprocess of GNU Emacs.  This
option is automatically supplied by GNU Emacs, and should not be given
under other circumstances.

@item -interactive
@findex -interactive
If this option isn't specified, and Scheme's standard @sc{i/o} is not a
terminal, Scheme will detach itself from its controlling terminal, which
prevents it from getting signals sent to the process group of that
terminal.  If this option is specified, Scheme will not detach itself
from the controlling terminal.

This detaching behavior is useful for running Scheme as a background
job.  For example, using @code{bash}, the following will run Scheme as a
background job, redirecting its input and output to files, and
preventing it from being killed by keyboard interrupts or by logging
out:

@example
scheme < /usr/cph/foo.in > /usr/cph/foo.out 2>&1 &
@end example

This option is ignored under non-unix operating systems.

@item -nocore
@findex -nocore
Specifies that Scheme should not generate a core dump under any
circumstances.  If this option is not given, and Scheme terminates
abnormally, you will be prompted to decide whether a core dump should be
generated.

This option is ignored under non-unix operating systems.

@item -library @var{path}
@findex -library
@findex MITSCHEME_LIBRARY_PATH
Sets the library search path to @var{path}.  This is a
list of directories that is searched to find various library files, such
as bands.  If this option is not given, the value of the environment
variable @code{MITSCHEME_LIBRARY_PATH} is used; if that isn't defined,
the default is used.

On unix, the elements of the list are separated by colons, and the
default value is @file{/usr/local/lib/mit-scheme}.  On PCs, the elements
of the list are separated by semicolons, and the default value is
@file{c:\scheme\lib}.

@item -utabmd @var{filename}
@findex -utabmd
@findex -utab
@findex MITSCHEME_UTABMD_FILE
Specifies that @var{filename} contains the microcode tables (the
microcode tables are information that informs the runtime system about
the microcode's structure).  @var{Filename} is searched for in the
working directory and the library directories.  If this option isn't
given, the filename is the value of the environment variable
@code{MITSCHEME_UTABMD_FILE}, or if that isn't defined,
@file{utabmd.bin}; in these cases the library directories are searched,
but not the working directory.

@code{-utab} is an alternate name for the @code{-utabmd} option; at most
one of these options may be given.

@item -fasl @var{filename}
@findex -fasl
Specifies that a @dfn{cold load} should be performed, using
@var{filename} as the initial file to be loaded.  If this option isn't
given, a normal load is performed instead.  This option may not be used
together with the @code{-compiler}, @code{-edwin}, or @code{-band}
options.  This option is useful only for maintenance and development of
the MIT Scheme runtime system.
@end table

@noindent
In addition to the above, @file{bchscheme} recognizes the following
command-line options, all of which specify parameters affecting how
@file{bchscheme} uses disk storage to do garbage collection:

@table @code
@item -gc-directory @var{directory}
@findex -gc-directory
@findex MITSCHEME_GC_DIRECTORY
Specifies that @var{directory} should be used to create files for
garbage collection.  If the option is not given, the value of
environment variable @code{MITSCHEME_GC_DIRECTORY} is used instead, and
if that is not defined, a standard temporary directory is used (see
@code{TMPDIR} in @pxref{Runtime Environment Variables}).

@item -gc-file @var{filename}
@findex -gc-file
@findex -gcfile
@findex MITSCHEME_GC_FILE
Specifies that @var{filename} should be used for garbage collection.  If
the option is not given, the value of environment variable
@code{MITSCHEME_GC_FILE} is used, and if this is not defined, a unique
filename is generated in the directory specified with
@code{-gc-directory}.

@code{-gcfile} is an alias for @code{-gc-file}; at most one of these
options should be specified.

@item -gc-keep
@findex -gc-keep
Specifies that the @sc{gc} file used for garbage collection should not be
deleted when Scheme terminates.
The @sc{gc} file is deleted only if the file was created
by this invocation of Scheme, and this option is not set.

@item -gc-start-position @var{number}
@findex -gc-start-position
@findex MITSCHEME_GC_START_POSITION
Specifies the first byte position in the @sc{gc} file at which the
Scheme process can write.  If not given, the value of the environment
variable @code{MITSCHEME_GC_START_POSITION} is used, and if that is not
defined, @samp{0} is used, meaning the beginning of the file.  The area
of the file used (and locked if possible) is the region between
@code{-gc-start-position} and @code{-gc-end-position}.

@item -gc-end-position @var{number}
@findex -gc-end-position
@findex MITSCHEME_GC_END_POSITION
Specifies the last byte position in the @sc{gc} file at which the Scheme
process can write.  If not given, the value of the environment variable
@code{MITSCHEME_GC_END_POSITION} is used, and if that is not defined,
the sum of the start position (as specified by
@code{-gc-start-position}) and the heap size is used.  The area of the
file used (and locked if possible) is the region between
@code{-gc-start-position} and @code{-gc-end-position}.

@item -gc-window-size @var{blocks}
@findex -gc-window-size
@findex MITSCHEME_GC_WINDOW_SIZE
Specifies the size of the windows into new space during garbage
collection.  If this option is not given, the value of environment
variable @code{MITSCHEME_GC_WINDOW_SIZE} is used instead, and if that
is not defined, the value @samp{16} is used.
@end table

@noindent
The following command-line options are only used by an experimental
version of@* @file{bchscheme} that uses unix System V-style shared
memory, and then only if the @file{gcdrone} program is installed in the
library directory.

@table @code
@item -gc-drone @var{program}
@findex -gc-drone
@findex MITSCHEME_GC_DRONE
Specifies that @var{program} should be used as the drone program for
overlapped @sc{i/o} during garbage collection.  If the option is not
given, the value of environment variable @code{MITSCHEME_GC_DRONE} is
used instead, and if that is not defined, @file{gcdrone} is used.

@item -gc-read-overlap @var{n}
@findex -gc-read-overlap
@findex MITSCHEME_GC_READ_OVERLAP
Specifies that Scheme should delegate at most @var{n} simultaneous disk
read operations during garbage collection.  If the option is not given,
the value of environment variable @code{MITSCHEME_GC_READ_OVERLAP} is
used instead, and if that is not defined, @samp{0} is used, disabling
overlapped reads.

@item -gc-write-overlap @var{n}
@findex -gc-write-overlap
@findex MITSCHEME_GC_WRITE_OVERLAP
Specifies that Scheme should delegate at most @var{n} simultaneous disk
write operations during garbage collection.  If the option is not given,
the value of environment variable @code{MITSCHEME_GC_WRITE_OVERLAP} is
used instead, and if that is not defined, @samp{0} is used, disabling
overlapped writes.
@end table

@noindent
The following options are runtime options.  They are processed after the
microcode options and after the image file is loaded.

@table @code
@item -no-init-file
@findex -no-init-file
This option causes Scheme to ignore the @file{~/.scheme.init} or
@file{scheme.ini} file, normally loaded automatically when Scheme starts
(if it exists).

@item -suspend-file
@findex -suspend-file
Under some circumstances Scheme can write out a file called
@file{scheme_suspend} in the user's home directory.@footnote{Under unix,
this file is written when Scheme is terminated by the @samp{SIGUSR1},
@samp{SIGHUP}, or @samp{SIGPWR} signals.  Under other operating systems,
this file is never written.} This file is a world image containing the
complete state of the Scheme process; restoring this file continues the
computation that Scheme was performing at the time the file was written.

Normally this file is never written, but the @code{-suspend-file} option
enables writing of this file.

@item -eval @var{expression} @dots{}
@findex -eval
This option causes Scheme to evaluate the @var{expression}s following it
on the command line, up to (but not including) the next option that
starts with a hyphen.  The expressions are evaluated in the
@code{user-initial-environment}.  Unless explicitly handled, errors
during evaluation are silently ignored.

@item -load @var{file} @dots{}
@findex -load
This option causes Scheme to load the @var{file}s (or lists of files)
following it on the command line, up to (but not including) the next
option that starts with a hyphen.  The files are loaded in the
@code{user-initial-environment}.  Unless explicitly handled, errors
during loading are silently ignored.
@end table

@noindent
The following option is supported only when Edwin is loaded.

@table @code
@item -edit
@findex -edit
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
@section Custom Command-line Options

MIT Scheme provides a mechanism for you to define your own command-line
options.  This is done by registering handlers to identify particular
named options and to process them when Scheme starts.  Unfortunately,
because of the way this mechanism is implemented, you must define the
options and then save a world image containing your definitions
(@pxref{World Images}).  Later, when you start Scheme using that world
image, your options will be recognized.

The following procedures define command-line parsers.  In each, the
argument @var{keyword} defines the option that will be recognized on the
command line.  The @var{keyword} must be a string starting with a hyphen
and containing at least one additional character.

@deffn {procedure+} simple-command-line-parser keyword thunk
Defines @var{keyword} to be a simple command-line option.  When this
keyword is seen on the command line, it causes @var{thunk} to be
executed.
@end deffn

@deffn {procedure+} argument-command-line-parser keyword multiple? procedure
Defines @var{keyword} to be a command-line option that is followed by
one or more command-line arguments.  @var{Procedure} is a procedure that
accepts one argument; when @var{keyword} is seen, it is called once for
each argument.

@var{Multiple?}, if true, says that @var{keyword} may be followed by
more than one argument on the command line.  In this case, procedure is
called once for each argument that follows @var{keyword} and does not
start with a hyphen.  If @var{multiple?} is @code{#f}, @var{procedure}
is called once, with the command-line argument following @var{keyword}.
In this case, it does not matter if the following argument starts with a
hyphen.
@end deffn

@deffn {procedure+} set-command-line-parser! keyword procedure
This low-level procedure defines @var{keyword} to be a command-line
option that is defined by @var{procedure}.  When @var{keyword} is seen,
@var{procedure} is called with all of the command-line arguments,
starting with @var{keyword}, as a single list argument.  @var{Procedure}
must return two values (using the @code{values} procedure): the unused
command-line arguments (as a list), and a thunk that is executed to
implement the behavior of the option.
@end deffn

@node Environment Variables, Starting Scheme from Microsoft Windows, Custom Command-line Options, Running Scheme
@section Environment Variables

Scheme refers to many environment variables.  This section lists these
variables and describes how each is used.  The environment variables are
organized according to the parts of MIT Scheme that they affect.

Environment variables that affect the microcode must be defined before
you start Scheme; under unix or Windows, others can be defined or
overwritten within Scheme by using the @code{set-environment-variable!}
procedure, e.g.@:

@example
(set-environment-variable! "EDWIN_FOREGROUND" "32")
@end example

@menu
* Microcode Environment Variables::  
* Bchscheme Environment Variables::  
* Runtime Environment Variables::  
* Edwin Environment Variables::  
* Windows Environment Variables::  
* OS/2 Environment Variables::  
@end menu

@node Microcode Environment Variables, Bchscheme Environment Variables, Environment Variables, Environment Variables
@subsection Environment Variables for the Microcode

These environment variables are referred to by the microcode (the
executable C programs called @file{scheme} and @file{bchscheme} under
unix, and @file{scheme.exe} and @file{bchschem.exe} on the PC).

@table @asis
@item @code{MITSCHEME_ALL_BAND} (default: @file{all.com} on the library path)
@findex MITSCHEME_ALL_BAND
The initial band to be loaded if both the @code{-compiler} and
@code{-edwin} options are given.  Overridden by @code{-band}.

@item @code{MITSCHEME_BAND} (default: @file{runtime.com} on the library path)
@findex MITSCHEME_BAND
The initial band to be loaded.  Overridden by @code{-band},
@code{-compiler}, or @code{-edwin}.

@item @code{MITSCHEME_COMPILER_BAND} (default: @file{compiler.com} on the library path)
@findex MITSCHEME_COMPILER_BAND
The initial band to be loaded if the @code{-compiler} option is given.
Overridden by @code{-band}.

@item @code{MITSCHEME_EDWIN_BAND} (default: @file{edwin.com} on the library path)
@findex MITSCHEME_EDWIN_BAND
The initial band to be loaded if the @code{-edwin} option is given.
Overridden by @code{-band}.

@item @code{MITSCHEME_LARGE_CONSTANT} (default: as needed)
@findex MITSCHEME_LARGE_CONSTANT
The size of constant space, in 1024-word blocks, if the @code{-large},
@code{-compiler}, or @code{-edwin} options are given.  Overridden by
@code{-constant}.  Note: the default is computed to be the correct size
for the band being loaded.

@item @code{MITSCHEME_LARGE_HEAP} (default: @samp{1000})
@findex MITSCHEME_LARGE_HEAP
The size of the heap, in 1024-word blocks, if the @code{-large},
@code{-compiler}, or @code{-edwin} options are given.  Overridden by
@code{-heap}.

@item @code{MITSCHEME_LARGE_STACK} (default: @samp{100})
@findex MITSCHEME_LARGE_STACK
The size of the stack, in 1024-word blocks, if the @code{-large},
@code{-compiler}, or @code{-edwin} options are given.  Overridden by
@code{-stack}.

@item @code{MITSCHEME_LIBRARY_PATH}
@findex MITSCHEME_LIBRARY_PATH
A list of directories.  These directories are searched,
left to right, to find bands and various other files.
On unix systems the list is colon-separated, with the default
@file{/usr/local/lib/mit-scheme}.
On PC systems the list is semicolon-separated with the default
@file{c:\scheme\lib}.

@item @code{MITSCHEME_SMALL_CONSTANT} (default: as needed)
@findex MITSCHEME_SMALL_CONSTANT
The size of constant space, in 1024-word blocks, if the size options are
not given.  Overridden by @code{-constant}, @code{-large},
@code{-compiler}, or @code{-edwin}.  Note: the default is computed to be
the correct size for the band being loaded.

@item @code{MITSCHEME_SMALL_HEAP} (default: @samp{250})
@findex MITSCHEME_SMALL_HEAP
The size of the heap, in 1024-word blocks, if the size options are not
given.  Overridden by @code{-heap}, @code{-large}, @code{-compiler}, or
@code{-edwin}.

@item @code{MITSCHEME_SMALL_STACK} (default: @samp{100})
@findex MITSCHEME_SMALL_STACK
The size of the stack, in 1024-word blocks, if the size options are not
given.  Overridden by @code{-stack}, @code{-large}, @code{-compiler}, or
@code{-edwin}.

@item @code{MITSCHEME_UTABMD_FILE} (default: @file{utabmd.bin} in the library path)
@findex MITSCHEME_UTABMD_FILE
The file containing the microcode tables.  Overridden by @code{-utabmd}
and @code{-utab}.
@end table

@node Bchscheme Environment Variables, Runtime Environment Variables, Microcode Environment Variables, Environment Variables
@subsection Environment Variables for @file{bchscheme}

These environment variables are referred to by @file{bchscheme}
(@emph{not} by @file{scheme}).

@table @asis
@item @code{MITSCHEME_GC_DIRECTORY}
@findex MITSCHEME_GC_DIRECTORY
The directory in which @sc{gc} files are written.  Overridden by
@code{-gc-directory}.  The default for this variable is the standard
temporary directory (see @code{TMPDIR} in @pxref{Runtime Environment
Variables}).

@item @code{MITSCHEME_GC_FILE} (default: @file{GCXXXXXX})
@findex MITSCHEME_GC_FILE
The name of the file to use for garbage collection.  If it ends in 6
@code{X}s, the @code{X}s are replaced by a letter and process id of the
scheme process, thus generating a unique name.  Overridden by
@code{-gc-file}.

@item @code{MITSCHEME_GC_START_POSITION} (default: @samp{0})
@findex MITSCHEME_GC_START_POSITION
The first position in the @sc{gc} file to use.  Overridden by
@code{-gc-start-position}.

@item @code{MITSCHEME_GC_END_POSITION} (default: @var{start-position}+@var{heap-size})
@findex MITSCHEME_GC_END_POSITION
The last position in the @sc{gc} file to use.  Overridden by
@code{-gc-end-position}.

@item @code{MITSCHEME_GC_WINDOW_SIZE} (default: @samp{16})
@findex MITSCHEME_GC_WINDOW_SIZE
The size in blocks of windows into new space (in the @sc{gc} file).@*
Overridden by @code{-gc-window-size}.
@end table

@noindent
The following environment variables are only used by an experimental
version of Bchscheme that uses unix System V-style shared memory, and
then only if the @file{gcdrone} program is installed:

@table @asis
@item @code{MITSCHEME_GC_DRONE} (default: @file{gcdrone})
@findex MITSCHEME_GC_DRONE
The program to use as the @sc{i/o} drone during garbage collection.@*
Overridden by @code{-gc-drone}.

@item @code{MITSCHEME_GC_READ_OVERLAP} (default: @samp{0})
@findex MITSCHEME_GC_READ_OVERLAP
The maximum number of simultaneous read operations.@*
Overridden by @code{-gc-read-overlap}.

@item @code{MITSCHEME_GC_WRITE_OVERLAP} (default: @samp{0})
@findex MITSCHEME_GC_WRITE_OVERLAP
The maximum number of simultaneous write operations.@*
Overridden by @code{-gc-write-overlap}.
@end table

@node Runtime Environment Variables, Edwin Environment Variables, Bchscheme Environment Variables, Environment Variables
@subsection Environment Variables for the Runtime System

These environment variables are referred to by the runtime system.

@table @asis
@item @code{HOME}
@findex HOME
Directory in which to look for init files.  E.g.@: @file{c:\users\joe}
or @file{/home/joe}.  This variable needs to be set on OS/2 and
Windows 9x.  Under Windows NT/2000/XP, the environment variables
@code{HOMEDRIVE} and @code{HOMEPATH}, set by the operating system, are
used instead.  Under unix, @code{HOME} is set by the login shell.

@item @code{TMPDIR}
@itemx @code{TEMP}
@itemx @code{TMP}
@findex TMPDIR
@findex TEMP
@findex TMP
Directory for various temporary files.  The variables are tried in the
given order.  If none of them is suitable, built-in defaults are used:
under unix, @file{/var/tmp}, @file{/usr/tmp}, @file{/tmp}; under OS/2
and Windows, @file{\temp}, @file{\tmp}, and @file{\} (all on the system
drive).

@item @code{MITSCHEME_INF_DIRECTORY} (default: @file{SRC} on the library path)
@findex MITSCHEME_INF_DIRECTORY
Directory containing the debugging information files for the Scheme
system.  Should contain subdirectories corresponding to the
subdirectories in the source tree.  For example, if its value is
@file{f:\random}, runtime system debugging files will be expected in
@file{f:\random\runtime}, while Edwin debugging files will be expected
in @file{f:\random\edwin}.

@item @code{MITSCHEME_LOAD_OPTIONS} (default: @file{optiondb.scm} on the library path)
@findex MITSCHEME_LOAD_OPTIONS
Specifies the location of the options database file used by the
@code{load-option} procedure.
@end table

@node Edwin Environment Variables, Windows Environment Variables, Runtime Environment Variables, Environment Variables
@subsection Environment Variables for Edwin

These environment variables are referred to by Edwin.

@table @asis
@item @code{EDWIN_BINARY_DIRECTORY} (default: @file{edwin/autoload} on the library path)
@findex EDWIN_BINARY_DIRECTORY
Directory where Edwin expects to find files providing autoloaded
facilities.

@item @code{EDWIN_INFO_DIRECTORY} (default: @file{edwin/info} on the library path)
@findex EDWIN_INFO_DIRECTORY
Directory where Edwin expects to find files for the `info' documentation
subsystem.

@item @code{EDWIN_ETC_DIRECTORY} (default: @file{edwin/etc} on the library path)
@findex EDWIN_ETC_DIRECTORY
Directory where Edwin expects to find utility programs and documentation
strings.

@item @code{ESHELL}
@findex ESHELL
Filename of the shell program to use in shell buffers.  If not defined,
the @code{SHELL} environment variable is used instead.

@item @code{SHELL} (default: @file{/bin/sh} (unix), @file{cmd.exe} (PC))
@findex SHELL
Filename of the shell program to use in shell buffers and when executing
shell commands.  Used to initialize the @code{shell-path-name} editor
variable.

@item @code{PATH}
@findex PATH
Used to initialize the @code{exec-path} editor variable, which is
subsequently used for finding programs to be run as subprocesses.

@item @code{DISPLAY}
@findex DISPLAY
Used when Edwin runs under unix and uses X11.
Specifies the display on which Edwin will create windows.

@item @code{TERM}
@findex TERM
Used when Edwin runs under unix on a terminal.
Terminal type.

@item @code{LINES} (default: auto-sense)
@findex LINES
Used when Edwin runs under unix on a terminal.
Number of text lines on the screen, for systems that don't support
@samp{TIOCGWINSZ}.

@item @code{COLUMNS} (default: auto-sense)
@findex COLUMNS
Used when Edwin runs under unix on a terminal.
Number of text columns on the screen, for systems that don't support
@samp{TIOCGWINSZ}.
@end table

@node Windows Environment Variables, OS/2 Environment Variables, Edwin Environment Variables, Environment Variables
@subsection Environment Variables for Microsoft Windows

These environment variables are specific to the Microsoft Windows
implementation.

@table @asis
@item @code{MITSCHEME_FONT} (default: determined by operating system)
@findex MITSCHEME_FONT
@cindex fonts
A string specifying a font name and characteristics, for example
@samp{Courier New 16 bold}.  Allowed characteristics are @var{integer},
specifying the font size in points, and the following style modifiers:
@samp{bold}, @samp{italic}, @samp{regular}, @samp{underline} and
@samp{strikeout}.  You should specify only fixed-width fonts as
variable-width fonts are not drawn correctly.

Once in Edwin, the font can be changed with the @code{set-font} and
@code{set-default-font} commands.

@item @code{MITSCHEME_GEOMETRY} (default: @samp{-1,-1,-1,-1})
@findex MITSCHEME_GEOMETRY
@cindex window position
Four integers separated by commas or spaces that specify the placement
and size of the MIT Scheme window as a
@var{left},@var{top},@var{width},@var{height} quadruple.  The units are
screen pixels, and @samp{-1} means allow the system to choose this
parameter.  E.g.@: @samp{-1,-1,500,300} places a 500 by 300 pixel window
at some system-determined position on the screen.  The width and height
include the window border and title.

@item @code{MITSCHEME_FOREGROUND} (default: according to desktop color scheme)
@findex MITSCHEME_FOREGROUND
@cindex window color
A value specifying the window
text color.  The color is specified as hex blue, green and red values
(@emph{not} RGB): e.g.@: @code{0xff0000} for blue.

@item @code{MITSCHEME_BACKGROUND} (default: according to desktop color scheme)
@findex MITSCHEME_BACKGROUND
A value specifying the window background color.  See
@code{MITSCHEME_FOREGROUND}.

@item @code{HOMEDRIVE}
@itemx @code{HOMEPATH}
@findex HOMEDRIVE
@findex HOMEPATH
These variables are used together to indicate the user's home
directory.  This is the preferred way to specify the home directory.

@item @code{USERNAME}
@itemx @code{USER}
@findex USERNAME
@findex USER
Specifies the login name of the user running Scheme.  This is used for
several different purposes.  @code{USERNAME} is preferred; @code{USER}
is used if @code{USERNAME} is not defined.  If neither of these
variables is defined, an error is signalled when the username is
required.

@item @code{USERDIR}
@findex USERDIR
Specifies a directory that contains the home directories of users.  One
of the places in which Scheme looks for the user's home directory, by
searching for a subdirectory with the user's login name.
@c
@c @item @code{MITSCHEME_TRAP_ALT_TAB} (default: @samp{false})
@c @itemx @code{MITSCHEME_TRAP_ALT_ESCAPE} (default: @samp{false})
@c @findex MITSCHEME_TRAP_ALT_TAB
@c @findex MITSCHEME_TRAP_ALT_ESCAPE
@c Boolean option specifying the handling of system command accelerators.
@c These options do not actually work.
@end table

@node OS/2 Environment Variables,  , Windows Environment Variables, Environment Variables
@subsection Environment Variables for OS/2

These environment variables are specific to the OS/2 implementation.

@table @code
@item USER
@findex USER
Specifies the login name of the user running Scheme.  This is used for
several different purposes.  If this variable is undefined, an error is
signalled when the username is required.

@item USERDIR
@findex USERDIR
Specifies a directory that contains the home directories of users.  One
of the places in which Scheme looks for the user's home directory, by
searching for a subdirectory with the user's login name.  This variable
is used only when @code{HOME} is not defined; we recommend using
@code{HOME} rather than @code{USERDIR}.

@item COMSPEC
@findex COMSPEC
Specifies the command shell.  This is set in all versions of OS/2 (and
is required for proper operation of the operating system).  Scheme uses
this to determine the user's shell if the environment variable
@code{SHELL} is not defined.
@end table

@node Starting Scheme from Microsoft Windows, Leaving Scheme, Environment Variables, Running Scheme
@section Starting Scheme from Microsoft Windows

The Microsoft Windows version of MIT Scheme runs as a graphics-based
application.  Scheme is normally started using shortcuts; the
installer automatically generates several different predefined
shortcuts for your convenience.

The rest of this section gives some tips on how to set up shortcuts
that run Scheme.  If you are unfamiliar with this concept you should
read about it in the system help.

@itemize @bullet
@item
Under Windows NT, Windows 2000, or Windows XP, shortcuts can be
@emph{common} or @emph{personal}.  When setting common shortcuts it is
important to make the shortcut properties independent of the vagaries
of the environment of the user who is running them.

@item
Give the shortcut an accurate @var{Description}.

@item
Include absolute pathnames to @file{scheme.exe} and @file{bchscheme.exe}
in the shortcut @var{Command line}.

@item
If you specify the @code{-library} command-line option then you do not
have to worry about the @code{MITSCHEME_LIBRARY_PATH} environment
variable.

@item
Set the shortcut's @var{Working Directory} to something sensible.  On
Windows NT/2000/XP you can use @samp{%HOMEDRIVE%%HOMEPATH%} to make
Scheme start up in the user's home directory.  On Windows 9x/ME you can
use @samp{%HOME%} to achieve the same effect, provided that you have
set the @code{HOME} environment variable as we recommend.

@item
There are several icons available in the Scheme executable --- choose
one that best represents the options given on the command line.

@item
Specifying a band that contains Edwin is not sufficient to invoke the
editor.  You also have to put @code{-edit} at the end of the command
line.
@end itemize

@node Leaving Scheme,  , Starting Scheme from Microsoft Windows, Running Scheme
@section Leaving Scheme

There are several ways that you can leave Scheme: there are two Scheme
procedures that you can call; there are several Edwin commands that you
can execute; and there are are graphical-interface buttons (and their
associated keyboard accelerators) that you can activate.

@itemize @bullet
@item
@emph{Two Scheme procedures that you can call.}  The first is to
evaluate

@findex exit
@example
(exit)
@end example

@noindent
which will halt the Scheme system, after first requesting confirmation.
Any information that was in the environment is lost, so this should not
be done lightly.

The second procedure suspends Scheme; when this is done you may later
restart where you left off.  Unfortunately this is not possible in all
operating systems; currently it works under unix versions that support
job control (i.e.@: all of the unix versions for which we distribute
Scheme).  To suspend Scheme, evaluate

@findex quit
@example
(quit)
@end example

@noindent
If your system supports suspension, this will cause Scheme to stop, and
you will be returned to the shell.  Scheme remains stopped, and can be
continued using the job-control commands of your shell.  If your system
doesn't support suspension, this procedure does nothing.  (Calling the
@code{quit} procedure is analogous to typing @kbd{C-z}, but it allows
Scheme to respond by typing a prompt when it is unsuspended.)

@item
@emph{Several Edwin commands that you can execute,} including
@code{save-buffers-kill-scheme}, normally bound to @kbd{C-x C-c}, and
@code{suspend-scheme}, normally bound to @kbd{C-x C-z}.  These two
commands correspond to the procedures @code{exit} and @code{quit},
respectively.

@item
@emph{Graphical-interface buttons that you can activate.}  Under OS/2
and Windows, closing the console window (Scheme's main window) causes
Scheme to be terminated.  Under any operating system, closing an Edwin
window causes that window to go away, and if it is the only Edwin
window, it terminates Scheme as well.

Under OS/2, there are two distinct ways to close the console window.
The first is to use any of the usual window-closing methods, such as the
@samp{Close} system-menu item or double-clicking on the system-menu
icon.  When this is done, you will be presented with a dialog that gives
you the option to close the window with or without termating Scheme.
The second way is to select the @samp{Exit} item from the @samp{File}
menu, which terminates Scheme immediately with no dialog.
@end itemize

@node Using Scheme, Compiling Programs, Running Scheme, Top
@chapter Using Scheme

This chapter describes how to use Scheme to evaluate expressions and
load programs.  It also describes how to save custom ``world images'',
and how to control the garbage collector.  Subsequent chapters will
describe how to use the compiler, and how to debug your programs.

@menu
* REPL::                        
* Loading Files::               
* World Images::                
* Garbage Collection::          
@end menu

@node REPL, Loading Files, Using Scheme, Using Scheme
@section The Read-Eval-Print Loop

@cindex REPL
When you first start up Scheme from the command line, you will be typing
at a program called the @dfn{Read-Eval-Print Loop} (abbreviated
@dfn{REPL}).  It displays a prompt at the left hand side of the screen
whenever it is waiting for input.  You then type an expression
(terminating it with @key{RET}).  Scheme evaluates the expression,
prints the result, and gives you another prompt.

@menu
* The Prompt and Level Number::  
* Interrupting::                
* Restarting::                  
* The Current REPL Environment::  
@end menu

@node The Prompt and Level Number, Interrupting, REPL, REPL
@subsection The Prompt and Level Number

@cindex prompt, REPL
The @sc{repl} @dfn{prompt} normally has the form

@example
1 ]=>
@end example

@cindex level number, REPL
@noindent
The @samp{1} in the prompt is a @dfn{level number}, which is always a
positive integer.  This number is incremented under certain
circumstances, the most common being an error.  For example, here is
what you will see if you type @kbd{f o o @key{RET}} after starting
Scheme:

@example
@group
;Unbound variable: foo
;To continue, call RESTART with an option number:
; (RESTART 3) => Specify a value to use instead of foo.
; (RESTART 2) => Define foo to a given value.
; (RESTART 1) => Return to read-eval-print level 1.

2 error> 
@end group
@end example

@noindent
In this case, the level number has been incremented to @samp{2}, which
indicates that a new @sc{repl} has been started (also the prompt string
has been changed to remind you that the @sc{repl} was started because of
an error).  The @samp{2} means that this new @sc{repl} is ``over'' the
old one.  The original @sc{repl} still exists, and is waiting for you to
return to it, for example, by entering @code{(restart 1)}.  Furthermore,
if an error occurs while you are in this @sc{repl}, yet another
@sc{repl} will be started, and the level number will be increased to
@samp{3}.  This can continue ad infinitum, but normally it is rare to
use more than a few levels.

The normal way to get out of an error @sc{repl} and back to the top
level @sc{repl} is to use the @kbd{C-g} interrupt.  This is a
single-keystroke command executed by holding down the @key{CTRL} key and
pressing the @key{G} key.  @kbd{C-g} always terminates whatever is
running and returns you to the top level @sc{repl} immediately.

Note: The appearance of the @samp{error>} prompt does not mean that
Scheme is in some weird inconsistent state that you should avoid.  It is
merely a reminder that your program was in error: an illegal operation
was attempted, but it was detected and avoided.  Often the best way to
find out what is in error is to do some poking around in the error
@sc{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
@subsection Interrupting

@kindex C-g
@kindex C-c
Scheme has several interrupt keys, which vary depending on the
underlying operating system: under unix, @kbd{C-g} and @kbd{C-c}; under
OS/2 and Windows, @kbd{C-g}, @kbd{C-b}, @kbd{C-x} and @kbd{C-u}.  The
@kbd{C-g} key stops any Scheme evaluation that is running and returns
you to the top level @sc{repl}.  @kbd{C-c} prompts you for another
character and performs some action based on that character.  It is not
necessary to type @key{RET} after @kbd{C-g} or @kbd{C-c}, nor is it
needed after the character that @kbd{C-c} will ask you for.

Here are the definitions of the more common interrupt keys; on unix,
type @kbd{C-c ?} for more possibilities.  Note that in any given
implementation, only a subset of the following keys is available.

@table @asis
@item @kbd{C-c C-c}
@itemx @kbd{C-g}
@kindex C-c C-c
@kindex C-g
Abort whatever Scheme evaluation is currently running and return to the
top-level @sc{repl}.  If no evaluation is running, this is equivalent to
evaluating

@findex cmdl-interrupt/abort-top-level
@example
(cmdl-interrupt/abort-top-level)
@end example

@item @kbd{C-c C-x}
@itemx @kbd{C-x}
@kindex C-c C-x
@kindex C-x
Abort whatever Scheme evaluation is currently running and return to the
``current'' @sc{repl}.  If no evaluation is running, this is equivalent
to evaluating

@findex cmdl-interrupt/abort-nearest
@example
(cmdl-interrupt/abort-nearest)
@end example

@item @kbd{C-c C-u}
@itemx @kbd{C-u}
@kindex C-c C-u
@kindex C-u
Abort whatever Scheme evaluation is running and go up one level.  If you
are already at level number 1, the evaluation is aborted, leaving you at
level 1.  If no evaluation is running, this is equivalent to evaluating

@findex cmdl-interrupt/abort-previous
@example
(cmdl-interrupt/abort-previous)
@end example

@item @kbd{C-c C-b}
@itemx @kbd{C-b}
@kindex C-c C-b
@kindex C-b
@cindex breakpoint
Suspend whatever Scheme evaluation is running and start a
@dfn{breakpoint} @sc{repl}.  The evaluation can be resumed by evaluating

@findex continue
@example
(continue)
@end example

@noindent
in that @sc{repl} at any time.

@item @kbd{C-c q}
@kindex C-c q
@findex exit
Similar to typing @code{(exit)} at the @sc{repl}, except that it works
even if Scheme is running an evaluation, and does not request
confirmation.

@item @kbd{C-c z}
@kindex C-c z
@findex quit
Similar to typing @code{(quit)} at the @sc{repl}, except that it works
even if Scheme is running an evaluation.

@item @kbd{C-c i}
@kindex C-c i
Ignore the interrupt.  Type this if you made a mistake and didn't
really mean to type @kbd{C-c}.

@item @kbd{C-c ?}
@kindex C-c ?
Print help information.  This will describe any other options not
documented here.
@end table

@node Restarting, The Current REPL Environment, Interrupting, REPL
@subsection Restarting

Another way to exit a @sc{repl} is to use the @code{restart} procedure:

@deffn {procedure+} restart [k]
@cindex REPL, restarting from
This procedure selects and invokes a @dfn{restart method}.  The list of
restart methods is different for each @sc{repl} and for each error; in
the case of an error @sc{repl}, this list is printed when the @sc{repl}
is started:

@example
@group
;Unbound variable: foo
;To continue, call RESTART with an option number:
; (RESTART 3) => Specify a value to use instead of foo.
; (RESTART 2) => Define foo to a given value.
; (RESTART 1) => Return to read-eval-print level 1.

2 error> 
@end group
@end example

If the @var{k} argument is given, it must be a positive integer index
into the list (in the example it must be between one and three
inclusive).  The integer @var{k} selects an item from the list and
invokes it.  If @var{k} is not given, @code{restart} prints the list and
prompts for the integer index:

@example
@group
2 error> (restart)
;Choose an option by number:
;  3: Specify a value to use instead of foo.
;  2: Define foo to a given value.
;  1: Return to read-eval-print level 1.

Option number:
@end group
@end example

The simplest restart methods just perform their actions.  For example:

@example
@group
2 error> (restart 1)
;Abort!

1 ]=>
@end group
@end example

Other methods will prompt for more input before continuing:

@example
@group
2 error> (restart)
;Choose an option by number:
;  3: Specify a value to use instead of foo.
;  2: Define foo to a given value.
;  1: Return to read-eval-print level 1.

Option number: 3

Value to use instead of foo: '(a b)
;Value: (a b)

1 ]=>
@end group
@end example
@end deffn

@node The Current REPL Environment,  , Restarting, REPL
@subsection The Current REPL Environment

@cindex current REPL environment
@findex user-initial-environment
@findex system-global-environment
Every @sc{repl} has a @dfn{current environment}, which is the place
where expressions are evaluated and definitions are stored.  When Scheme
is started, this environment is the value of the variable
@code{user-initial-environment}.  There are a number of other
environments in the system, for example
@code{system-global-environment}, where the runtime system's bindings
are stored.

You can get the current @sc{repl} environment by evaluating

@findex nearest-repl/environment
@example
(nearest-repl/environment)
@end example

There are several other ways to obtain environments.  For example, if
you have a procedure object, you can get a pointer to the environment in
which it was closed by evaluating

@findex procedure-environment
@example
(procedure-environment @var{procedure})
@end example

Here is the procedure that changes the @sc{repl}'s environment:

@deffn {procedure+} ge environment
Changes the current @sc{repl} environment to be @var{environment}
(@code{ge} stands for ``Goto Environment'').  @var{Environment} is
allowed to be a procedure as well as an environment object.  If it is a
procedure, then the closing environment of that procedure is used in its
place.
@end deffn

@deffn {procedure+} pe
This procedure is useful for finding out which environment you are in
(@code{pe} stands for ``Print Environment'').  If the current @sc{repl}
environment belongs to a package, then @code{pe} returns the package
name (a list of symbols).  If the current @sc{repl} environment does not
belong to a package then the environment is returned.
@end deffn

@node Loading Files, World Images, REPL, Using Scheme
@section Loading Files

To load files of Scheme code, use the procedure @code{load}:

@deffn {procedure} load filename [environment [syntax-table [purify?]]]
@var{Filename} may be a string naming a file, or a list of strings
naming multiple files.  @var{Environment}, if given, is the environment to
evaluate the file in; if not given the current @sc{repl} environment is
used.

@var{Syntax-table} is no longer used and if supplied will be ignored.

@findex purify
The optional argument @var{purify?} is a boolean that says whether to
move the contents of the file into constant space after it is loaded but
before it is evaluated.  This is performed by calling the procedure
@code{purify} (@pxref{Garbage Collection}).  If @var{purify?} is given
and true, this is done; otherwise it is not.

@findex pathname-type
@code{load} determines whether the file to be loaded is binary or source
code, and performs the appropriate action.  By convention, files of
source code have a pathname type of @code{"scm"}, and files of binary
SCode have pathname type @code{"bin"}.  Native-code binaries have
pathname type @code{"com"}.  (See the description of
@code{pathname-type} in @ref{Components of Pathnames, Pathname Type,
Components of Pathnames, scheme, MIT Scheme Reference Manual}.)
@end deffn

@defvr {variable+} load-noisily?
If @code{load-noisily?} is set to @code{#t}, @code{load} will print the
value of each expression in the file as it is evaluated.  Otherwise,
nothing is printed except for the value of the last expression in the
file.  (Note: the noisy loading feature is implemented for source-code
files only.)
@end defvr

@defvr {variable+} load/default-types
When load is given a pathname without a type, it uses the value of this
variable to determine what pathname types to look for and how to load
the file.  @code{load/default-types} is a list of associations that maps
pathname types (strings) to loader procedures.  @code{load} tries the
pathname types in the order that they appear in the list.  The initial
value of this variable has pathname types in this order:

@example
"com" "so" "sl" "bin" "scm"
@end example

This means that, for example, @code{(load "foo")} will try to load
@file{foo.com} first, and @file{foo.scm} only after looking for and
failing to find the other pathname types.
@end defvr

@cindex working directory
@findex pwd
@findex cd
All pathnames are interpreted relative to a working directory, which is
initialized when Scheme is started.  The working directory can be
obtained by calling the procedure @code{pwd} or modified by calling the
procedure @code{cd}; @pxref{Working Directory, , , scheme, MIT
Scheme Reference Manual}.  Files may be loaded when Scheme first starts;
see the @code{-load} command-line option for details.

@deffn {procedure+} load-option symbol [no-error?]
Loads the option specified by @var{symbol}; if already loaded, does
nothing.  Returns @var{symbol}; if there is no such option, an error is
signalled.  However, if @var{no-error?} is specified and true, no error
is signalled in this case, and @code{#f} is returned.

A number of built-in options are defined:

@table @code
@item compress
Support to compress and uncompress files.  Undocumented; see the source
file @file{runtime/cpress.scm}.  Used by the runtime system for
compression of compiled-code debugging information.

@item format
The @code{format} procedure.  @xref{Format, , , scheme, MIT Scheme
Reference Manual}.

@item gdbm
Support to access @code{gdbm} databases.  Undocumented; see the source
files @file{runtime/gdbm.scm} and @file{microcode/prgdbm.c}.

@item hash-table
The hash-table data type.  @xref{Hash Tables, , , scheme, MIT Scheme
Reference Manual}.

@item ordered-vector
Support to search and do completion on vectors of ordered elements.
Undocumented; see the source file @file{runtime/ordvec.scm}.

@item rb-tree
The red-black tree data type.  @xref{Red-Black Trees, , , scheme, MIT
Scheme Reference Manual}.

@item regular-expression
Support to search and match strings for regular expressions.
@xref{Regular Expressions, , , scheme, MIT Scheme Reference Manual}.

@item stepper
Support to step through the evaluation of Scheme expressions.
Undocumented; see the source file @file{runtime/ystep.scm}.  Used by the
Edwin command @kbd{step-expression}.

@item subprocess
Support to run other programs as subprocesses of the Scheme process.
Undocumented; see the source file @file{runtime/process.scm}.  Used
extensively by Edwin.

@item synchronous-subprocess
Support to run synchronous subprocesses.  @xref{Subprocesses, , ,
scheme, MIT Scheme Reference Manual}.

@item wt-tree
The weight-balanced tree data type.  @xref{Weight-Balanced Trees, , ,
scheme, MIT Scheme Reference Manual}.
@end table
@end deffn

In addition to the built-in options, you may define other options to be
loaded by @code{load-options} by modifying the file @file{optiondb.scm}
on the library path.  An example file is included with the distribution;
normally this file consists of a series of calls to the procedure
@code{define-load-option}, terminated by the expression

@example
(further-load-options standard-load-options)
@end example

@deffn {procedure+} define-load-option symbol thunk @dots{}
Each @var{thunk} must be a procedure of no arguments.  Defines the load
option named @var{symbol}.  When the procedure @code{load-option} is
called with @var{symbol} as an argument, the @var{thunk} arguments are
executed in order from left to right.
@end deffn

@node World Images, Garbage Collection, Loading Files, Using Scheme
@section World Images

@cindex world image
@cindex band
A @dfn{world image}, also called a @dfn{band}, is a file that contains a
complete Scheme system, perhaps additionally including user application
code.  Scheme provides a method for saving and restoring world images.
The method writes a file containing all of the Scheme code and data in
the running process.  The file @file{runtime.com} that is loaded by the
microcode is just such a band.  To make your own band, use the procedure
@code{disk-save}.

@deffn {procedure+} disk-save filename [identify]
Causes a band to be written to the file specified by @var{filename}.
The optional argument @var{identify} controls what happens when that
band is restored, as follows:

@table @asis
@item not specified
Start up in the top-level @sc{repl}, identifying the world in the normal
way.

@item a string
Do the same thing except print that string instead of @samp{Scheme} when
restarting.

@item the constant @code{#t}
Restart exactly where you were when the call to @code{disk-save} was
performed.  This is especially useful for saving your state when an
error has occurred and you are not in the top-level @sc{repl}.

@item the constant @code{#f}
Just like @code{#t}, except that the runtime system will not perform
normal restart initializations; in particular, it will not load your
init file.
@end table
@end deffn

@findex disk-restore
To restore a saved band, give the @code{-band} option when starting
Scheme.  Alternatively, evaluate @code{(disk-restore @var{filename})},
which will destroy the current world, replacing it with the saved world.
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
@section Garbage Collection

This section describes procedures that control garbage collection.
@xref{Memory Usage}, for a discussion of how MIT Scheme uses memory.

@deffn {procedure+} gc-flip [safety-margin]
Forces a garbage collection to occur.  Returns the number of words of
storage available after collection, an exact non-negative integer.

@var{Safety-margin} determines the number of words of storage available
to system tasks after the need for a garbage collection is detected and
before the garbage collector is started.  (An example of such a system
task is changing the run-light to show ``gc'' when scheme is running
under Emacs.)  @strong{Note well}: you should not specify
@var{safety-margin} unless you know what you are doing.  If you specify
a value that is too small, you can put Scheme in an unusable state.
@end deffn

@deffn {procedure+} purify object [pure-space? [queue?]]
Moves @var{object} from the heap into constant space.  Has no effect if
@var{object} is already stored in constant space.  @var{Object} is moved
in its entirety; if it is a compound object such as a list, a vector, or
a record, then all of the objects that @var{object} points to are also
moved to constant space.

There are three important effects associated with moving an object to
constant space.  The first and most important effect is that the object
takes up half as much space, because when in the heap, the system must
reserve space for the object in both the active heap and the inactive
heap; if the object is in constant space it is not copied and therefore
no extra space is required.  The second effect is that garbage
collection will take less time, because @var{object} will no longer be
copied.  The third effect is that the space allocated to @var{object} is
permanently allocated, because constant space is never cleaned; any
unreachable objects in constant space remain there until the Scheme
process is terminated.

The optional argument @var{pure-space?} is obsolete; it defaults to
@code{#t} and when explicitly specified should always be @code{#t}.

The optional argument @var{queue?}, if @code{#f}, specifies that
@var{object} should be moved to constant space immediately; otherwise
@var{object} is queued to be moved during the next garbage collection.
This argument defaults to @code{#t}.  The reason for queuing these
requests is that moving an object to constant space requires a garbage
collection to occur, a relatively slow process.  By queuing the
requests, this overhead is avoided, because moving an object during a
garbage collection has no effect on the time of the garbage collection.
Furthermore, if several requests are queued, they can all be processed
together in one garbage collection, while if done separately they would
each require their own garbage collection.
@end deffn

@deffn {procedure+} flush-purification-queue!
Forces any pending queued purification requests to be processed.  This
examines the @code{purify} queue, and if it contains any requests,
forces a garbage collection to process them.  If the queue is empty,
does nothing.
@end deffn

@deffn {procedure+} print-gc-statistics
Prints out information about memory allocation and the garbage
collector.  The information is printed to the current output port.
Shows how much space is ``in use'' and how much is ``free'', separately
for the heap and constant space.  The amounts are shown in words, and
also in 1024-word blocks; the block figures make it convenient to use
these numbers to adjust the arguments given to the @code{-heap} and
@code{-constant} command-line options.  Following the allocation
figures, information about the most recent 8 garbage collections is
shown, in the same format as a @sc{gc} notification.

Note that these numbers are accurate at the time that
@code{print-gc-statistics} is called.  In the case of the heap, the ``in
use'' figure shows how much memory has been used since the last garbage
collection, and includes all live objects as well as any uncollected
garbage that has accumulated since then.  The only accurate way to
determine the size of live storage is to subtract the value of
@samp{(gc-flip)} from the size of the heap.  The size of the heap can be
determined by adding the ``in use'' and ``free'' figures reported by
@code{print-gc-statistics}.
@end deffn

@example
@group
(print-gc-statistics)
constant in use:   534121 words =   521 blocks +  617 words
constant free:        128 words =     0 blocks +  128 words
heap in use:        34845 words =    34 blocks +   29 words
heap free:         205530 words =   200 blocks +  730 words
GC #1: took: 0.13 (81%) CPU time, 0.15 (1%) real time; free: 207210
;No value
@end group
@end example

@deffn {procedure+} set-gc-notification! [on?]
Controls whether the user is notified of garbage collections.  If
@var{on?} is true, notification is enabled; otherwise notification is
disabled.  If @var{on?} is not given, it defaults to @code{#t}.  When
Scheme starts, notification is disabled.

The notification appears as a single line like the following, showing
how many garbage collections have occurred, the time taken to perform the
garbage collection and the free storage remaining (in words) after
collection.

@example
GC #5: took: 0.50 (8%) CPU time, 0.70 (2%) real time; free: 364346
@end example

To operate comfortably, the amount of free storage after garbage
collection should be a substantial proportion of the heap size.  If the
CPU time percentage is consistently high (over 20%), you should consider
running with a larger heap.  A rough rule of thumb to halve the @sc{gc}
overhead is to take the amount of free storage, divide by 1000, and add
this figure to the current value used for the @code{-heap} command-line
option.  Unfortunately there is no way to adjust the heap size without
restarting Scheme.
@end deffn

@deffn {procedure+} toggle-gc-notification!
Toggles @sc{gc} notification on and off.  If @sc{gc} notification is
turned on, turns it off; otherwise turns it on.
@end deffn

@node Compiling Programs, Debugging, Using Scheme, Top
@chapter Compiling Programs

Note: the procedures described in this section are only available when
the @code{-compiler} command-line option is specified.

@menu
* Compilation Procedures::      
* Declarations::                
* Efficiency Tips::             
@end menu

@node Compilation Procedures, Declarations, Compiling Programs, Compiling Programs
@section Compilation Procedures

@deffn {procedure+} cf filename [destination]
This is the program that transforms a source-code file into native-code
binary form.  If @var{destination} is not given, as in

@example
(cf "foo")
@end example

@noindent
@code{cf} compiles the file @file{foo.scm}, producing the file
@file{foo.com} (incidentally it will also produce @file{foo.bin},
@file{foo.bci}, and possibly @file{foo.ext}).  If you later evaluate

@example
(load "foo")
@end example

@noindent
@file{foo.com} will be loaded rather than @file{foo.scm}.

If @var{destination} is given, it says where the output files should go.
If this argument is a directory, they go in that directory, e.g.@::

@example
(cf "foo" "../bar/")
@end example

@noindent
will take @file{foo.scm} and generate the file @file{../bar/foo.com}.
If @var{destination} is not a directory, it is the root name of the
output:

@example
(cf "foo" "bar")
@end example

@noindent
takes @file{foo.scm} and generates @file{bar.com}.
@end deffn

About the @file{.bci} files: these files contain the debugging
information that Scheme uses when you call @code{debug} to examine
compiled code.  When you load a @file{.com} file, Scheme remembers where
it was loaded from, and when the debugger (or @code{pp}) looks at the
compiled code from that file, it attempts to find the @file{.bci} file
in the same directory from which the @file{.com} file was loaded.  Thus
it is a good idea to leave these files together.

@file{.bci} files are stored in a compressed format.  The debugger has
to uncompress the files when it looks at them, and on a slow machine
this can take a noticeable time.  The system takes steps to reduce the
impact of this behavior: debugging information is cached in memory, and
uncompressed versions of @file{.bci} files are kept around.  The default
behavior is that a temporary file is created and the @file{.bci} file is
uncompressed into it.  The temporary file is kept around for a while
afterwards, and during that time if the uncompressed @file{.bci} file is
needed the temporary file is used.  Each such reference updates an
`access time' that is associated with the temporary file.  The garbage
collector checks the access times of all such temporary files, and
deletes any that have not been accessed in five minutes or more.  All of
the temporaries are deleted automatically when the Scheme process is
killed.

Two other behaviors are available.  One of them uncompresses the
@file{.bci} file each time it is referenced, and the other uncompresses
the @file{.bci} file and writes it back out as a @file{.bif} file.  The
@file{.bif} file remains after Scheme exits.  The time interval and the
behavior are controlled by the following variables.

@defvr {variable+} *save-uncompressed-files?*
This variable affects what happens when @file{.bci} files are
uncompressed.  It allows a trade-off between performance and disk space.
There are three possible values:

@table @code
@item #f
The uncompressed versions of @file{.bci} files are never saved.  Each
time the information is needed the @file{.bci} file is uncompressed.
This option requires the minimum amount of disk space and is the
slowest.

@item automatic
Uncompressed versions of @file{.bci} files are kept as temporary files.
The temporary files are deleted when Scheme exits, or if they have not
been used for a while.  This is the default.

@item #t
The @file{.bci} files are uncompressed to permanent @file{.bif} files.
These files remain on disk after Scheme exits, and are rather large -
about twice the size of the corresponding @file{.bci} files.  If you
choose this option and you are running out of disk space you may delete
the @file{.bif} files.  They will be regenerated as needed.
@end table
@end defvr

@defvr {variable+} *uncompressed-file-lifetime*
The minimum length of time that a temporary uncompressed version of
a @file{.bci} file will stay on disk after it is last used.
The time is in milliseconds; the default is @samp{300000} (five
minutes).
@end defvr

@defvr {variable+} load-debugging-info-on-demand?
If this variable is @file{#f}, then printing a compiled procedure
will print the procedure's name only if the debugging information for
that procedure is already loaded.  Otherwise, it will force
loading of the debugging information.
The default value is @code{#f}.
@end defvr

@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
programs run considerably faster than unoptimized interpreted code.
Also, the binary files that it generates load very quickly compared to
source-code files.

The simplest way to use @code{sf} is just to say:

@example
(sf @var{filename})
@end example

@noindent
This will cause your file to be transformed, and the resulting binary
file to be written out with the same name, but with pathname type
@code{"bin"}.  If you do not specify a pathname type on the input file,
@code{"scm"} is assumed.

Like @code{load}, the first argument to @code{sf} may be a list of
filenames rather than a single filename.

@code{sf} takes an optional second argument, which is the filename of
the output file.  If this argument is a directory, then the output file
has its normal name but is put in that directory instead.
@end deffn

@node Declarations, Efficiency Tips, Compilation Procedures, Compiling Programs
@section Declarations
@cindex declarations

Several declarations can be added to your programs to help @code{cf} and
@code{sf} make them more efficient.

@menu
* Standard Names::              
* In-line Coding::              
* Replacement of Operators::    
* Reduction of Operators::      
@end menu

@node Standard Names, In-line Coding, Declarations, Declarations
@subsection Standard Names

Normally, all files have a line

@findex usual-integrations
@example
(declare (usual-integrations))
@end example

@noindent
near their beginning, which tells the compiler that free variables whose
names are defined in @code{system-global-environment} will not be
shadowed by other definitions when the program is loaded.  If you
redefine some global name in your code, for example @code{car},
@code{cdr}, and @code{cons}, you should indicate it in the declaration:

@example
(declare (usual-integrations car cdr cons))
@end example

You can obtain an alphabetically-sorted list of the names that the
@code{usual-integrations} declaration affects by evaluating the
following expression:

@example
@group
(eval '(sort (append usual-integrations/constant-names
                     usual-integrations/expansion-names)
             (lambda (x y)
               (string<=? (symbol->string x)
                          (symbol->string y))))
      (->environment '(scode-optimizer)))
@end group
@end example

@node In-line Coding, Replacement of Operators, Standard Names, Declarations
@subsection In-line Coding

Another useful facility is the ability to in-line code procedure
definitions.  In fact, the compiler will perform full beta conversion,
with automatic renaming, if you request it.  Here are the relevant
declarations:

@deffn {declaration+} integrate name @dots{}
The variables @var{name}s must be defined in the same file as this
declaration.  Any reference to one of the named variables that appears
in the same block as the declaration, or one of its descendant blocks,
will be replaced by the corresponding binding's value expression.
@end deffn

@deffn {declaration+} integrate-operator name @dots{}
Similar to the @code{integrate} declaration, except that it only
substitutes for references that appear in the operator position of a
combination.  All other references are ignored.
@end deffn

@deffn {declaration+} integrate-external filename
Causes the compiler to use the top-level integrations provided by
@var{filename}.  @var{filename} should not specify a file type, and the
source-code file that it names must have been previously processed by
the compiler.

If @var{filename} is a relative filename (the normal case), it is
interpreted as being relative to the file in which the declaration
appears.  Thus if the declaration appears in file @file{/usr/cph/foo.scm},
then the compiler looks for a file called @file{/usr/cph/@var{filename}.ext}.

Note: When the compiler finds top-level integrations, it collects them
and outputs them into an auxiliary file with extension @file{.ext}.
This @file{.ext} file is what the @code{integrate-external} declaration
refers to.
@end deffn

@findex define-integrable
@findex define
Note that the most common use of this facility, in-line coding of
procedure definitions, requires a somewhat complicated use of these
declarations.  Because this is so common, there is a special form,
@code{define-integrable}, which is like @code{define} but performs the
appropriate declarations.  For example:

@example
@group
(define-integrable (foo-bar foo bar)
  (vector-ref (vector-ref foo bar) 3))
@end group
@end example

Here is how you do the same thing without this special form: there
should be an @code{integrate-operator} declaration for the procedure's
name, and (internal to the procedure's definition) an @code{integrate}
declaration for each of the procedure's parameters, like this:

@example
@group
(declare (integrate-operator foo-bar))

(define foo-bar
  (lambda (foo bar)
    (declare (integrate foo bar))
    (vector-ref (vector-ref foo bar) 3)))
@end group
@end example

The reason for this complication is as follows: the
@code{integrate-operator} declaration finds all the references to
@code{foo-bar} and replaces them with the lambda expression from the
definition.  Then, the @code{integrate} declarations take effect because
the combination in which the reference to @code{foo-bar} occurred
supplies code that is substituted throughout the body of the procedure
definition.  For example:

@example
(foo-bar (car baz) (cdr baz))
@end example

@noindent
First use the @code{integrate-operator} declaration:

@example
@group
((lambda (foo bar)
   (declare (integrate foo bar))
   (vector-ref (vector-ref foo bar) 3))
 (car baz)
 (cdr baz))
@end group
@end example

@noindent
Next use the internal @code{integrate} declaration:

@example
@group
((lambda (foo bar)
   (vector-ref (vector-ref (car baz) (cdr baz)) 3))
 (car baz)
 (cdr baz))
@end group
@end example

@noindent
Next notice that the variables @code{foo} and @code{bar} are not used,
and eliminate them:

@example
@group
((lambda ()
   (vector-ref (vector-ref (car baz) (cdr baz)) 3)))
@end group
@end example

@noindent
Finally, remove the @code{((lambda () @dots{}))} to produce

@example
(vector-ref (vector-ref (car baz) (cdr baz)) 3)
@end example

@subsubheading Useful tip
@cindex integrations, seeing effects of
To see the effect of integration declarations (and of macros) on a
source file, pretty-print the @file{.bin} file like this (be prepared
for a lot of output).

@example
@group
(sf "foo.scm")
(pp (fasload "foo.bin"))
@end group
@end example

@node Replacement of Operators, Reduction of Operators, In-line Coding, Declarations
@subsection Operator Replacement

The @code{replace-operator} declaration is provided to inform the
compiler that certain operators may be replaced by other operators
depending on the number of arguments.
For example:

@noindent
Declaration:

@example
(declare (replace-operator (map (2 map-2) (3 map-3))))
@end example

@noindent
Replacements:

@example
@group
(map @var{f} @var{x} @var{y} @var{z}) @expansion{} (map @var{f} @var{x} @var{y} @var{z})
(map @var{f} @var{x} @var{y}) @expansion{} (map-3 @var{f} @var{x} @var{y})
(map @var{f} @var{x}) @expansion{} (map-2 @var{f} @var{x})
(map @var{f}) @expansion{} (map @var{f})
(map) @expansion{} (map)
@end group
@end example

@noindent
Presumably @code{map-2} and @code{map-3} are efficient versions of
@code{map} that are written for exactly two and three arguments
respectively.  All the other cases are not expanded but are handled by the
original, general @code{map} procedure, which is less efficient because
it must handle a variable number of arguments.

@deffn {declaration+} replace-operator name ...

The syntax of this declaration is

@example
@group
(replace-operator
  (@var{name}
    (@var{nargs1} @var{value1})
    (@var{nargs2} @var{value2})
    ...))
@end group
@end example

where

@itemize @bullet
@item
@var{name} is a symbol.

@item
@var{nargs1}, @var{nargs2} etc.@: are non-negative integers, or one of the
following symbols:  @code{any}, @code{else} or @code{otherwise}.

@item
@var{value1}, @var{value2} etc.@: are simple
expressions in one of these forms:

@table @code
@item '@var{constant}
A constant.

@item @var{variable}
A variable.

@item (primitive @var{primitive-name} @r{[}@var{arity}@r{]})
The primitive procedure named @var{primitive-name}.  The optional
element @var{arity}, a non-negative integer, specifies the number of
arguments that the primitive accepts.

@item (global @var{var})
A global variable.
@end table
@end itemize

The meanings of these fields are:

@itemize @bullet
@item
@var{name} is the name of the operator to be reduced.  If is is not
shadowed (for example, by a let) then it may be replaced according to
the following rules.

@item
If the operator has @var{nargsN} arguments then it is replaced with a
call to @var{valueN} with the same arguments.

@item
If the number of arguments is not listed, and one of the @var{nargsN} is
@code{any}, @code{else} or @code{otherwise}, then the operation is
replaced with a call to the corresponding @var{valueN}.
Only one of the @var{nargsN} may be of this form.

@item
If the number of arguments is not listed and none of the @var{nargsN} is
@code{any}, @code{else} or @code{otherwise}, then the operation is not
replaced.
@end itemize
@end deffn

@node Reduction of Operators,  , Replacement of Operators, Declarations
@subsection Operator Reduction

@findex reduce-operator
The @code{reduce-operator} declaration is provided to inform the
compiler that certain names are n-ary versions of binary operators.
Here are some examples:

@noindent
Declaration:

@example
(declare (reduce-operator (cons* cons)))
@end example

@noindent
Replacements:

@example
@group
(cons* @var{x} @var{y} @var{z} @var{w}) @expansion{} (cons @var{x} (cons @var{y} (cons @var{z} @var{w}))),
(cons* @var{x} @var{y}) @expansion{} (cons @var{x} @var{y})
(cons* @var{x}) @expansion{} @var{x}
(cons*) @error{} too few arguments
@end group
@end example

@noindent
Declaration:

@example
(declare (reduce-operator (list cons (null-value '() any))))
@end example

@noindent
Replacements:

@example
@group
(list @var{x} @var{y} @var{z} @var{w}) @expansion{} (cons @var{x} (cons @var{y} (cons @var{z} (cons @var{w} '()))))
(list @var{x} @var{y}) @expansion{} (cons @var{x} (cons @var{y} '()))
(list @var{x}) @expansion{} (cons @var{x} '())
(list) @expansion{} '()
@end group
@end example

@noindent
Declaration:

@example
(declare (reduce-operator (- %- (null-value 0 single) (group left))))
@end example

@noindent
Replacements:

@example
@group
(- @var{x} @var{y} @var{z} @var{w}) @expansion{} (%- (%- (%- @var{x} @var{y}) @var{z}) @var{w})
(- @var{x} @var{y}) @expansion{} (%- @var{x} @var{y})
(- @var{x}) @expansion{} (%- 0 @var{x})
(-) @expansion{} 0
@end group
@end example

@noindent
Declaration:

@example
(declare (reduce-operator (+ %+ (null-value 0 none) (group right))))
@end example

@noindent
Replacements:

@example
@group
(+ @var{x} @var{y} @var{z} @var{w}) @expansion{} (%+ @var{x} (%+ @var{y} (%+ @var{z} @var{w})))
(+ @var{x} @var{y}) @expansion{} (%+ @var{x} @var{y})
(+ @var{x}) @expansion{} @var{x}
(+) @expansion{} 0
@end group
@end example

Note: This declaration does not cause an appropriate definition of
@code{%+} (in the last example) to appear in your code.  It merely
informs the compiler that certain optimizations can be performed on
calls to @code{+} by replacing them with calls to @code{%+}.  You should
provide a definition of @code{%+} as well, although it is not required.

@noindent
Declaration:

@example
@group
(declare (reduce-operator (apply (primitive cons)
                                 (group right)
                                 (wrapper (global apply) 1))))
@end group
@end example

@noindent
Replacements:

@example
@group
(apply @var{f} @var{x} @var{y} @var{z} @var{w})
   @expansion{} ((access apply ()) @var{f} (cons @var{x} (cons @var{y} (cons @var{z} @var{w}))))
(apply @var{f} @var{x} @var{y})
   @expansion{} ((access apply ()) @var{f} (cons @var{x} @var{y}))
(apply @var{f} @var{x}) @expansion{} (apply @var{f} @var{x})
(apply @var{f}) @expansion{} (apply @var{f})
(apply) @expansion{} (apply)
@end group
@end example

@deffn {declaration+} reduce-operator name ...
The general format of the declaration is (brackets denote optional
elements):

@example
@group
(reduce-operator
  (@var{name}
    @var{binop}
    @r{[}(group @var{ordering})@r{]}
    @r{[}(null-value @var{value} @var{null-option})@r{]}
    @r{[}(singleton @var{unop})@r{]}
    @r{[}(wrapper @var{wrap} @r{[}n@r{]})@r{]}
    @r{[}(maximum @var{m})@r{]}
  ))
@end group
@end example

@noindent
where

@itemize @bullet
@item
@var{n} and @var{m} are non-negative integers.

@item
@var{name} is a symbol.

@item
@var{binop}, @var{value}, @var{unop}, and @var{wrap} are simple
expressions in one of these forms:

@table @code
@item '@var{constant}
A constant.

@item @var{variable}
A variable.

@item (primitive @var{primitive-name} @r{[}@var{arity}@r{]})
The primitive procedure named @var{primitive-name}.  The optional
element @var{arity} specifies the number of arguments that the primitive
accepts.

@item (global @var{var})
A global variable.
@end table

@item
@var{null-option} is either @code{always}, @code{any}, @code{one},
@code{single}, @code{none}, or @code{empty}.

@item
@var{ordering} is either @code{left}, @code{right}, or
@code{associative}.
@end itemize

@noindent
The meaning of these fields is:

@itemize @bullet
@item
@var{name} is the name of the n-ary operation to be reduced.

@item
@var{binop} is the binary operation into which the n-ary operation is to
be reduced.

@item
The @code{group} option specifies whether @var{name} associates to the
right or left.

@item
The @code{null-value} option specifies a value to use in the following
cases:

@table @code
@item none
@itemx empty
When no arguments are supplied to @var{name}, @var{value} is returned.

@item one
@itemx single
When a single argument is provided to @var{name}, @var{value} becomes
the second argument to @var{binop}.

@item any
@itemx always
@var{binop} is used on the ``last'' argument, and @var{value} provides
the remaining argument to @var{binop}.
@end table

In the above options, when @var{value} is supplied to @var{binop}, it is
supplied on the left if grouping to the left, otherwise it is supplied
on the right.

@item
The @code{singleton} option specifies a function, @var{unop}, to be
invoked on the single argument given.  This option supersedes the
@code{null-value} option, which can only take the value @code{none}.

@item
The @code{wrapper} option specifies a function, @var{wrap}, to be
invoked on the result of the outermost call to @var{binop} after the
expansion.
If @var{n} is provided it must be a non-negative integer indicating a number
of arguments that are transferred verbatim from the original call to
the wrapper.  They are passed to the left of the reduction.

@item
The maximum option specifies that calls with more than @var{m} arguments
should not be reduced.
@end itemize
@end deffn

@node Efficiency Tips,  , Declarations, Compiling Programs
@section Efficiency Tips

How you write your programs can have a large impact on how efficiently the
compiled program runs.  The most important thing to do, after choosing
suitable data structures, is to put the following declaration near the
beginning of the file.

@example
(declare (usual-integrations))
@end example

Without this declaration the compiler cannot recognize any of the common
operators and compile them efficiently.

The @code{usual-integrations} declaration is usually sufficient to get
good quality compiled code.

If you really need to squeeze more performance out of your code then we
hope that you find the following grab-bag of tips, hints and
explanations useful.

@menu
* Coding style::                
* Global variables::            
* Fixnum arithmetic::           
* Flonum arithmetic::           
@end menu

@node Coding style, Global variables, Efficiency Tips, Efficiency Tips
@subsection Coding style

Scheme is a rich language, in which there are usually several ways to
say the same thing.  A @dfn{coding style} is a set of rules that a
programmer uses for choosing an expressive form to use in a given
situation.  Usually these rules are aesthetic, but sometimes there are
efficiency issues involved; this section describes a few choices that
have non-obvious efficiency consequences.

@subsubheading Better predicates

Consider the following implementation of @code{map} as might be found in
any introductory book on Scheme:

@example
@group
(define (map f lst)
  (if (null? lst)
      '()
      (cons (f (car lst)) (map f (cdr lst)))))
@end group
@end example

The problem with this definition is that at the points where @code{car}
and @code{cdr} are called we still do not know that @var{lst} is a pair.
The compiler must insert a type check, or if type checks are disabled,
the program might give wrong results.  Since one of the fundamental
properties of @code{map} is that it transforms lists, we should make the
relationship between the input pairs and the result pairs more apparent
in the code:

@example
@group
(define (map f lst)
  (cond ((pair? lst)
         (cons (f (car lst)) (map f (cdr lst))))
        ((null? lst)
         '())
        (else
         (error "Not a proper list:"  lst))))
@end group
@end example

Note also that the @code{pair?} case comes first because we expect that
@code{map} will be called on lists which have, on average, length
greater that one.

@subsubheading Internal procedures

Calls to internal procedures are faster than calls to global procedures.
There are two things that make internal procedures faster: First, the
procedure call is compiled to a direct jump to a known location, which
is more efficient that jumping `via' a global binding.
Second, there is a knock-on effect: since the compiler can see the
internal procedure, the compiler can analyze it and possibly produce
better code for other expressions in the body of the loop too:

@example
@group
(define (map f original-lst)
  (let walk ((lst original-lst))
    (cond ((pair? lst)
           (cons (f (car lst)) (walk (cdr lst))))
          ((null? lst)
           '())
          (else
           (error "Not a proper list:"  original-lst)))))
@end group
@end example

@subsubheading Internal defines

Internal definitions are a useful tool for structuring larger
procedures.  However, certain internal definitions can thwart compiler
optimizations.  Consider the following two procedures, where
@code{compute-100} is some unknown procedure that we just know returns
@samp{100}.

@example
@group
(define (f1)
  (define v 100)
  (lambda () v))

(define (f2)
  (define v (compute-100))
  (lambda () v))  
@end group
@end example

The procedure returned by @code{f1} will always give the same result and
the compiler can prove this.  The procedure returned by @code{f2} may
return different results, even if @code{f2} is only called once.
Because of this, the compiler has to allocate a memory cell to @code{v}.
How can the procedure return different results?

The fundamental reason is that the continuation may escape during the
evaluation of @code{(compute-100)}, allowing the rest of the body of
@code{f2} to be executed @emph{again}:

@example
@group
(define keep)

(define (compute-100)
  (call-with-current-continuation
   (lambda (k)
     (set! keep k)
     100)))

(define p (f2))

(p)                @result{} 100
(keep -999)        @result{} p     @emph{re-define v and p}
(p)                @result{} -999
@end group
@end example

To avoid the inefficiency introduced to handle the general case, the
compiler must prove that the continuation cannot possibly escape.  The
compiler knows that lambda expressions and constants do not let their
continuations escape, so order the internal definitions so that
definitions of the following forms come first:

@example
@group
(define x '@emph{something})
(define x (lambda (...) ...))
(define (f u v) ...)
@end group
@end example

Note: The @sc{ieee} Scheme standard permits @emph{only} lambda
expressions and constants as the value of internal defines.
Furthermore, all internal definitions must appear before any other
expressions in the body.  Following the standard simultaneously assures
portability and avoids the implementation inefficiencies described in
this section.

@node Global variables, Fixnum arithmetic, Coding style, Efficiency Tips
@subsection Global variables

@cindex variable caches
@cindex reference traps
Compiled code usually accesses variables in top-level first-class
environments via @emph{variable caches}.  Each compiled procedure has a
set of variable caches for the global variables that it uses.  There are
three kinds of variable cache - read caches for getting the value of a
variable (referencing the variable), write caches for changing the
value, and execute caches for calling the procedure assigned to that
variable.

Sometimes the variable caches contain special objects, called reference
traps, that indicate that the operation cannot proceed normally and
must either be completed by the system (in order to keep the caches
coherent) or must signal an error.  For example, the assignment

@example
(set! newline my-better-newline)
@end example

will cause the system to go to each compiled procedure that calls
@code{newline} and update its execute cache to call the new procedure.
Obviously you want to avoid updating hundreds of execute caches in a
critical loop.  Using @code{fluid-let} to temporarily redefine a
procedure has the same inefficiency (but twice!).

To behave correctly in all situations, each variable reference or
assignment must check for the reference traps.

Sometimes you can prove that the variable (a) will always be bound, (b)
will never be unassigned, and (c) there will never be any compiled calls
to that variable.  The compiler can't prove this because it assumes that
other independently compiled files might be loaded that invalidate these
assumptions.  If you know that these conditions hold, the following
declarations can speed up and reduce the size of a program that uses
global variables.

@deffn {declaration+} ignore-reference-traps variables
This declaration tells the compiler that it need not check for
reference-trap objects when referring to the given @var{variables}.
If any of the @var{variables} is unbound or unassigned then a variable
reference will yield a reference-trap object rather than signaling an
error.  This declaration is relatively safe: the worst that can happen
is that a reference-trap object finds its way into a data structure
(e.g.@: a list) or into interpreted code, in which case it will probably
cause some `unrelated' variable to mysteriously become unbound or
unassigned.
@end deffn

@deffn {declaration+} ignore-assignment-traps variables
This declaration tells the compiler that it need not check for
reference-trap objects when assigning to the given @var{variables}.  An
assignment to a variable that ignores assignment traps can cause a great
deal of trouble.  If there is a compiled procedure call anywhere in the
system to this variable, the execute caches will not be updated, causing
an inconsistency between the value used for the procedure call and the
value seen by reading the variable.  This mischief is compounded by the
fact that the assignment can cause other assignments that were compiled
with checks to behave this way too.
@end deffn

The @var{variables} are specified with expressions from the following
set language:

@deffn {variable-specification} set name ...
All of the explicitly listed names.
@end deffn

@deffn {variable-specification} all
@deffnx {variable-specification} none
@deffnx {variable-specification} free
@deffnx {variable-specification} bound
@deffnx {variable-specification} assigned
These expressions name sets of variables. @code{all} is the set of all
variables, @code{none} is the empty set, @code{free} is all of the
variables bound outside the current block, @code{bound} is all of the
variables bound in the current block and @code{assigned} is all of the
variables for which there exists an assignment (i.e.@: @code{set!}).
@end deffn

@deffn {variable-specification} union set1 set2
@deffnx {variable-specification} intersection set1 set2
@deffnx {variable-specification} difference set1 set2

For example, to ignore reference traps on all the variables except
@var{x}, @var{y} and any variable that is assigned to

@example
@group
(declare (ignore-reference-traps
          (difference all (union assigned (set x y)))))
@end group
@end example
@end deffn
@c
@c Note: The scoping of @code{ignore-reference-traps} and
@c @code{ignore-assignment-traps} differs between version of the compiler.
@c MIT Scheme version 8.0 (Liar
@c version 5.0) has true block scoping, thus the declaration takes effect
@c only within the procedure or @code{let} in which the declaration
@c occurs.  This makes it possible to control individual variable
@c references, for example:
@c 
@c @example
@c @group
@c (let ()
@c   (declare (ignore-reference-traps x))
@c   x)
@c @end group
@c @end example
@c 
@c In earlier versions, a declaration affects all uses of the variable.
@c 
@c In all versions, top level declarations affect the whole source file.

@node Fixnum arithmetic, Flonum arithmetic, Global variables, Efficiency Tips
@subsection Fixnum arithmetic

The usual arithmetic operations like @code{+} and @code{<} are called
generic arithmetic operations because they work for all (appropriate)
kinds of number.

@cindex fixnum (defn)
A @dfn{fixnum} is an exact integer that is small enough to fit in a
machine word.  In MIT Scheme, fixnums are 26 bits on 32-bit machines,
and 56 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.

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
not a fixnum is too big to be encoded as such.  For this reason, small
constants such as @code{0} or @code{1} are guaranteed to be fixnums.  In
addition, the lengths of and valid indexes into strings and vectors are
also always fixnums.

If you know that a value is always a small fixnum, you can substitute
the equivalent fixnum operation for the generic operation.  However,
care should be exercised: if used improperly, these operations can
return incorrect answers, or even malformed objects that confuse the
garbage collector.  For a listing of all fixnum operations, see
@ref{Fixnum Operations, , , scheme, MIT Scheme Reference Manual}.

A fruitful area for inserting fixnum operations is in the index
operations in tight loops.

@node Flonum arithmetic,  , Fixnum arithmetic, Efficiency Tips
@subsection Flonum arithmetic
@c
@c !INCOMPLETE

Getting efficient flonum arithmetic is much more complicated and harder
than getting efficient fixnum arithmetic.

@subsubheading Flonum consing

@cindex flonum consing
One of the main disadvantages of generic arithmetic is that not all
kinds of number fit in a machine register.
Flonums have to be @dfn{boxed} because a 64-bit @sc{ieee} floating-point
number (the representation that MIT Scheme uses) does not fit in a
regular machine word.
This is true even on 64-bit architectures because some extra bits are
needed to distinguish floating-point numbers from other objects like
pairs and strings.
Values are boxed by storing them in a small record in the heap.
Every floating-point value that you see at the @sc{repl} is boxed.
Floating-point values are unboxed only for short periods of time when
they are in the machine's floating-point unit and actual floating-point
operations are being performed.

Numerical calculations that happen to be using floating-point numbers
cause many temporary floating-point numbers to be allocated.  It is not
uncommon for numerical programs to spend over half of their time creating
and garbage collecting the boxed flonums.

Consider the following procedure for computing the distance of a point
(@var{x},@var{y}) from the origin.

@example
@group
(define (distance x y)
  (sqrt (+ (* x x) (* y y))))
@end group
@end example

The call @code{(distance 0.3 0.4)} returns a new, boxed flonum, 0.5.
The calculation also generates three intermediate boxed flonums.  This
next version works only for flonum inputs, generates only one boxed
flonum (the result) and runs eight times faster:

@example
@group
(define (flo:distance x y)
  (flo:sqrt (flo:+ (flo:* x x) (flo:* y y))))
@end group
@end example

Note that @code{flo:} operations are usually effective only within a
single arithmetic expression.  If the expression contains conditionals
or calls to procedures then the values tend to get boxed anyway.
@c
@c @subsubheading A safer alternative
@c 
@c An alternative to putting in @code{flo:} operations yourself is to let
@c the compiler try.
@c In the next definition of @code{distance}, the programmer explicitly
@c tests for flonum arguments and duplicates the expression.
@c 
@c The compiler compiles the expressions differently: for the first
@c expression it knows from the conditional that @var{x} and @var{y} are
@c flonums and will replace both @code{*} and the @code{+} operators with
@c flonum operators.
@c It doesn't replace the @code{sqrt} operator, though, as it doesn't know
@c that sums of squares of reals are non-negative.
@c 
@c This approach has the advantage of being completely safe, and
@c @code{distance} will still work for other kinds of number.
@c 
@c @example
@c @group
@c (define (distance x y)
@c   (if (and (flo:flonum? x) (flo:flonum? y))
@c       (sqrt (+ (* x x) (* y y)))
@c       (sqrt (+ (* x x) (* y y)))))
@c @end group
@c @end example
@c 
@c This approach is effective only for MIT Scheme version 8.0 and later.
@c Earlier versions do not do this kind of type analysis.

@subsubheading Flonum vectors

Flonum vectors are vectors that contain only floating-point values, in
much the same way as a string is a `vector' containing only character
values.

Flonum vectors have the advantages of compact storage (about half
that of a conventional vector of flonums) and judicious use of flonum
vectors can decrease flonum consing.

The disadvantages are that flonum vectors are incompatible with ordinary
vectors, and if not used carefully, can increase flonum consing.  Flonum
vectors are a pain to use because they require you to make a decision
about the representation and stick with it, and it might not be easy to
ascertain whether the advantages in one part of the program outweigh the
disadvantages in another.

The flonum vector operations are:

@deffn {procedure+} flo:vector-cons n
Create a flonum vector of length @var{n}.  The contents of the vector
are arbitrary and might not be valid floating-point numbers.  The
contents should not be used until initialized.
@end deffn

@deffn {procedure+} flo:vector-ref flonum-vector index
@deffnx {procedure+} flo:vector-set! flonum-vector index value
@deffnx {procedure+} flo:vector-length flonum-vector
These operations are analogous to the ordinary vector operations.
@end deffn

@subsubheading Examples

The following operation causes no flonum consing because the flonum is
loaded directly from the flonum vector into a floating-point machine
register, added, and stored again.  There is no need for a temporary
boxed flonum.

@example
(flo:vector-set! v 0 (flo:+ (flo:vector-ref v 0) 1.2))
@end example

In this next example, every time @code{g} is called, a new boxed flonum
has to be created so that a valid Scheme object can be returned.  If
@code{g} is called more often than the elements of @var{v} are changed
then an ordinary vector might be more efficient.

@example
@group
(define (g i)
  (flo:vector-ref v i))
@end group
@end example

@subsubheading Common pitfalls

Pitfall 1:
Make sure that your literals are floating-point constants:

@example
@group
(define (f1 a) (flo:+ a 1))
(define (f2 a) (flo:+ a 1.))
@end group
@end example

@code{f1} will most likely cause a hardware error, and certainly give
the wrong answer.  @code{f2} is correct.

Pitfall 2:
It is tempting to insert calls to @code{exact->inexact} to coerce values
into flonums.  This does not always work because complex numbers may be
exact or inexact too.  Also, the current implementation of
@code{exact->inexact} is slow.

Pitfall 3:
A great deal of care has to be taken with the standard math procedures.
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}).
@c
@c @node Miscellaneous,  , Flonum arithmetic, Efficiency Tips
@c @subsection Miscellaneous
@c 
@c @subsubheading @code{in-package} and declarations
@c 
@c Declarations from outside of an @code{in-package} form do not apply to
@c the body of the form.
@c This is because, in general, the new package (environment) could be any
@c package, including one that contains alternative definitions for the
@c standard procedures.
@c The declarations in the enclosing text might be meaningless in the
@c @code{in-package} body.
@c As the @code{usual-integrations} declaration is included in this rule,
@c it is usually a good idea to repeat the declaration e.g@:.
@c 
@c @example
@c @group
@c   ...
@c   (in-package some-environment
@c     (declare (usual-integrations))
@c     ...)
@c   ...
@c @end group
@c @end example

@node Debugging, GNU Emacs Interface, Compiling Programs, Top
@chapter Debugging

Parts of this chapter are adapted from @cite{Don't Panic: A 6.001 User's
Guide to the Chipmunk System}, by Arthur A. Gleckler.

@cindex bugs
@cindex debugging
Even computer software that has been carefully planned and well written
may not always work correctly.  Mysterious creatures called @dfn{bugs}
may creep in and wreak havoc, leaving the programmer to clean up the
mess.  Some have theorized that a program fails only because its author
made a mistake, but experienced computer programmers know that bugs are
always to blame.  This is why the task of fixing broken computer
software is called @dfn{debugging}.

It is impossible to prove the correctness of any non-trivial program;
hence the Cynic's First Law of Debugging:

@quotation
Programs don't become more reliable as they are debugged; the bugs just
get harder to find.
@end quotation

@cindex breakpoints
Scheme is equipped with a variety of special software for finding and
removing bugs.  The debugging tools include facilities for tracing a
program's use of specified procedures, for examining Scheme
environments, and for setting @dfn{breakpoints}, places where the
program will pause for inspection.

@cindex error
Many bugs are detected when programs try to do something that is
impossible, like adding a number to a symbol, or using a variable that
does not exist; this type of mistake is called an @dfn{error}.
Whenever an error occurs, Scheme prints an error message and starts a
new @sc{repl}.  For example, using a nonexistent variable @code{foo} will
cause Scheme to respond

@example
@group
1 ]=> foo

;Unbound variable: foo
;To continue, call RESTART with an option number:
; (RESTART 3) => Specify a value to use instead of foo.
; (RESTART 2) => Define foo to a given value.
; (RESTART 1) => Return to read-eval-print level 1.

2 error> 
@end group
@end example

Sometimes, a bug will never cause an error, but will still cause the
program to operate incorrectly.  For instance,

@example
(prime? 7)   @result{}   #f
@end example

In this situation, Scheme does not know that the program is misbehaving.
The programmer must notice the problem and, if necessary, start the
debugging tools manually.

There are several approaches to finding bugs in a Scheme program:

@itemize @bullet
@item
Inspect the original Scheme program.

@item
Use the debugging tools to follow your program's progress.

@item
Edit the program to insert checks and breakpoints.
@end itemize

@noindent
Only experience can teach how to debug programs, so be sure to
experiment with all these approaches while doing your own debugging.
Planning ahead is the best way to ward off bugs, but when bugs do
appear, be prepared to attack them with all the tools available.

@menu
* Subproblems and Reductions::  
* Command-Line Debugger::       
* Debugging Aids::              
* Advising Procedures::         
@end menu

@node Subproblems and Reductions, Command-Line Debugger, Debugging, Debugging
@section Subproblems and Reductions

@cindex subproblem
@cindex reduction
@cindex subexpression
Understanding the concepts of @dfn{reduction} and @dfn{subproblem} is
essential to good use of the debugging tools.  The Scheme interpreter
evaluates an expression by @dfn{reducing} it to a simpler expression.
In general, Scheme's evaluation rules designate that evaluation proceeds
from one expression to the next by either starting to work on a
@dfn{subexpression} of the given expression, or by reducing the entire
expression to a new (simpler, or reduced) form.  Thus, a history of the
successive forms processed during the evaluation of an expression will
show a sequence of subproblems, where each subproblem may consist of a
sequence of reductions.

For example, both @code{(+ 5 6)} and @code{(+ 7 9)} are subproblems of
the following combination:

@example
(* (+ 5 6) (+ 7 9))
@end example

@noindent
If @code{(prime? n)} is true, then @code{(cons 'prime n)} is a reduction
for the following expression:

@example
@group
(if (prime? n)
    (cons 'prime n)
    (cons 'not-prime n))
@end group
@end example

This is because the entire subproblem of the @code{if} expression can
be reduced to the problem @code{(cons 'prime n)}, once we know that
@code{(prime?  n)} is true; the @code{(cons 'not-prime n)} can be
ignored, because it will never be needed.  On the other hand, if
@code{(prime? n)} were false, then @code{(cons 'not-prime n)} would be
the reduction for the @code{if} expression.

The @emph{subproblem level} is a number representing how far back in the
history of the current computation a particular evaluation is.  Consider
@code{factorial}:

@example
@group
(define (factorial n)
  (if (< n 2)
      1
      (* n (factorial (- n 1)))))
@end group
@end example

@noindent
If we stop @code{factorial} in the middle of evaluating @code{(- n 1)},
the @code{(- n 1)} is at subproblem level 0.  Following the history of
the computation ``upwards,'' @code{(factorial (- n 1))} is at subproblem
level 1, and @code{(* n (factorial (- n 1)))} is at subproblem level 2.
These expressions all have @emph{reduction number} 0.  Continuing
upwards, the @code{if} expression has reduction number 1.

Moving backwards in the history of a computation, subproblem levels and
reduction numbers increase, starting from zero at the expression
currently being evaluated.  Reduction numbers increase until the next
subproblem, where they start over at zero.  The best way to get a feel
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
@section The Command-Line Debugger

@cindex debugger
@cindex continuation Browser
@cindex browser, Continuation
@findex debug
There are two debuggers available with MIT Scheme.  One of them runs
under Edwin, and is described in that section of this document
(@pxref{Edwin Debugger}).  The other is command-line oriented, does not
require Edwin, and is described here.

@cindex command-line debugger
The @dfn{command-line debugger}, called @code{debug}, is the tool you
should use when Scheme signals an error and you want to find out what
caused the error.  When Scheme signals an error, it records all the
information necessary to continue running the Scheme program that caused
the error; the debugger provides you with the means to inspect this
information.  For this reason, the debugger is sometimes called a
@dfn{continuation browser}.
 
Here is the transcript of a typical Scheme session, showing a user
evaluating the expression @code{(fib 10)}, Scheme responding with an
unbound variable error for the variable @code{fob}, and the user
starting the debugger:

@example
@group
1 ]=> (fib 10)

;Unbound variable: fob
;To continue, call RESTART with an option number:
; (RESTART 3) => Specify a value to use instead of fob.
; (RESTART 2) => Define fob to a given value.
; (RESTART 1) => Return to read-eval-print level 1.

2 error> (debug)

There are 6 subproblems on the stack.

Subproblem level: 0 (this is the lowest subproblem level)
Expression (from stack):
    fob
Environment created by the procedure: FIB
 applied to: (10)
The execution history for this subproblem contains 1 reduction.
You are now in the debugger.  Type q to quit, ? for commands.

3 debug> 
@end group
@end example

@noindent
@cindex execution history
This tells us that the error occurred while trying to evaluate the
expression @samp{fob} while running @samp{(fib 10)}.  It also tells us
this is subproblem level 0, the first of 6 subproblems that are
available for us to examine.  The expression shown is marked @samp{(from
stack)}, which tells us that this expression was reconstructed from the
interpreter's internal data structures.  Another source of information
is the @dfn{execution history}, which keeps a record of expressions
evaluated by the interpreter.  The debugger informs us that the
execution history has recorded some information for this subproblem,
specifically a description of one reduction.

What follows is a description of the commands available in the debugger.
To understand how the debugger works, you need to understand that the
debugger has an implicit state that is examined and modified by
commands.  The state consists of three pieces of information: a
@dfn{subproblem}, a @dfn{reduction}, and an @dfn{environment frame}.
Each of these parts of the implicit state is said to be @dfn{selected};
thus one refers to the @dfn{selected subproblem}, and so forth.  The
debugger provides commands that examine the selected state, and allow
you to select different states.

Here are the debugger commands.  Each of these commands consists of a
single letter, which is to be typed by itself at the debugger prompt.
It is not necessary to type @key{RET} after these commands.

@table @asis
@item Traversing subproblems
@cindex Debugger command u
@cindex Debugger command d
@cindex Debugger command g
@cindex Debugger command h
The debugger has several commands for traversing the structure of the
continuation.  It is useful to think of the continuation as a
two-dimensional structure: a backbone consisting of subproblems, and
associated ribs consisting of reductions.  The bottom of the backbone is
the most recent point in time; that is where the debugger is positioned
when it starts.  Each subproblem is numbered, with @code{0} representing
the most recent time point, and ascending integers numbering older time
points.  The @kbd{u} command moves up to older points in time, and the
@kbd{d} command moves down to newer points in time.  The @kbd{g}
command allows you to select a subproblem by number, and the @kbd{h}
command will show you a brief summary of all of the subproblems.

@item Traversing reductions
@cindex Debugger command r
@cindex Debugger command b
@cindex Debugger command f
If the subproblem description says that @samp{The execution history for
this subproblem contains @var{N} reductions}, then there is a ``rib'' of
reductions for this subproblem.  You can see a summary of the reductions
for this subproblem using the @kbd{r} command.  You can move to the next
reduction using the @kbd{b} command; this moves you to the next older
reduction.  The @kbd{f} command moves in the opposite direction, to
newer reductions.  If you are at the oldest reduction for a given
subproblem and use the @kbd{b} command, you will move to the next older
subproblem.  Likewise, if you are at the newest reduction and use
@kbd{f}, you'll move to the next newer subproblem.

@item Examining subproblems and reductions
@cindex Debugger command t
@cindex Debugger command l
The following commands will show you additional information about the
currently selected subproblem or reduction.  The @kbd{t} command will
reprint the standard description (in case it has scrolled off the
screen).  The @kbd{l} command will pretty-print (using @code{pp}) the
subproblem's expression.

@item Traversing environments
Nearly all subproblems and all reductions have associated environments.
Selecting a subproblem or reduction also selects the associated
environment.  However, environments are structured as a sequence of
frames, where each frame corresponds to a block of environment
variables, as bound by @code{lambda} or @code{let}.  These frames
collectively represent the block structure of a given environment.

@cindex Debugger command p
@cindex Debugger command s
Once an environment frame is selected by the debugger, it is possible to
select the parent frame of that frame (in other words, the enclosing
block) using the @kbd{p} command.  You can subsequently return to the
original child frame using the @kbd{s} command.  The @kbd{s} command
works because the @kbd{p} command keeps track of the frames that you
step through as you move up the environment hierarchy; the @kbd{s}
command just retraces the path of saved frames.  Note that selecting a
frame using @kbd{p} or @kbd{s} will print the bindings of the newly
selected frame.

@item Examining environments
@cindex Debugger command a
@cindex Debugger command c
@cindex Debugger command e
@cindex Debugger command o
@cindex Debugger command v
@cindex Debugger command w
The following commands allow you to examine the contents of the selected
frame.  The @kbd{c} command prints the bindings of the current frame.
The @kbd{a} command prints the bindings of the current frame and each
of its ancestor frames.  The @kbd{e} command enters a read-eval-print
loop in the selected environment frame; expressions typed at that
@sc{repl} will be evaluated in the selected environment.  To exit the
@sc{repl} and return to the debugger, evaluate @code{(abort->previous)}
or use @code{restart}.  The @kbd{v} command prompts for a single
expression and evaluates it in the selected environment.  The @kbd{w}
command invokes the environment inspector (@code{where}); quitting the
environment inspector returns to the debugger.  Finally, the @kbd{o}
command pretty-prints the procedure that was called to create the
selected environment frame.

@item Continuing the computation
@cindex Debugger command k
There are three commands that can be used to restart the computation
that you are examining.  The first is the @kbd{k} command, which shows
the currently active restarts, prompts you to select one, and passes
control to the it.  It is very similar to evaluating @samp{(restart)}.

The other two commands allow you to invoke internal continuations.  This
should not be done lightly; invoking an internal continuation can
violate assumptions that the programmer made and cause unexpected
results.  Each of these commands works in the same way: it prompts you
for an expression, which is evaluated in the selected environment to
produce a value.  The appropriate internal continuation is then invoked
with that value as its sole argument.  The two commands differ only in
which internal continuation is to be invoked.

@cindex Debugger command j
The @kbd{j} command invokes the continuation associated with
the selected subproblem.  What this means is as follows: when the
description of a subproblem is printed, it consists of two parts, and
``expression'' and a ``subproblem being executed''.  The latter is
usually marked in the former by the specific character sequence
@samp{###}.  The internal continuation of the subproblem is the code
that is waiting for the ``subproblem being executed'' to return a
value.  So, in effect, you are telling the program what the ``subproblem
being executed'' will evaluate to, and bypassing further execution of
that code.

@cindex Debugger command z
The @kbd{z} command is slightly different.  It instead invokes the
continuation that is waiting for the outer ``expression'' to finish.  In
other words, it is the same as invoking the @kbd{j} command in the next
frame up.  So you can think of this as an abbreviation for the @kbd{u}
command followed by the @kbd{j} command.

@item Wizard commands
@cindex Debugger command m
@cindex Debugger command x
@cindex Debugger command y
The @kbd{m}, @kbd{x}, and @kbd{y} commands are for Scheme wizards.  They
are used to debug the MIT Scheme implementation.  If you want to find
out what they do, read the source code.

@item Miscellaneous commands
@cindex Debugger command i
@cindex Debugger command q
@cindex Debugger command ?
The @kbd{i} command will reprint the error message for the error that
was in effect immediately before the debugger started.  The @kbd{q}
command quits the debugger, returning to the caller.  And the @kbd{?}
command prints a brief summary of the debugger's commands.
@end table

@node Debugging Aids, Advising Procedures, Command-Line Debugger, Debugging
@section Debugging Aids

This section describes additional commands that are useful for debugging.

@deffn {procedure+} bkpt datum argument @dots{}
Sets a breakpoint.  When the breakpoint is encountered, @var{datum} and
the @var{argument}s are typed (just as for @code{error}) and a
read-eval-print loop is entered.  The environment of the read-eval-print
loop is derived by examining the continuation of the call to
@code{bkpt}; if the call appears in a non-tail-recursive position, the
environment will be that of the call site.  To exit from the breakpoint
and proceed with the interrupted process, call the procedure
@code{continue}.  Sample usage:

@example
@group
1 ]=> (begin (write-line 'foo)
             (bkpt 'test-2 'test-3)
             (write-line 'bar)
             'done)

foo
 test-2 test-3
;To continue, call RESTART with an option number:
; (RESTART 2) => Return from BKPT.
; (RESTART 1) => Return to read-eval-print level 1.

2 bkpt> (+ 3 3)

;Value: 6

2 bkpt> (continue)

bar
;Value: done
@end group
@end example
@end deffn

@deffn {procedure+} pp object [output-port [as-code?]]
The @code{pp} procedure is described in @ref{Output Procedures, , ,
scheme, MIT Scheme Reference Manual}.  However, since this is a very
useful debugging tool, we also mention it here.  @code{pp} provides two
very useful functions:

@enumerate
@item
@code{pp} will print the source code of a given procedure.  Often, when
debugging, you will have a procedure object but will not know exactly
what procedure it is.  Printing the procedure using @code{pp} will show
you the source code, which greatly aids identification.

@item
@code{pp} will print the fields of a record structure.  If you have a
compound object pointer, print it using @code{pp} to see the component
fields, like this:

@example
@group
(pp (->pathname "~"))
@print{} #[pathname 14 "/usr/home/cph"]
@print{} (host #[host 15])
@print{} (device unspecific)
@print{} (directory (absolute "usr" "home"))
@print{} (name "cph")
@print{} (type ())
@print{} (version unspecific)
@end group
@end example

When combined with use of the @code{#@@} syntax, @code{pp} provides the
functionality of a simple object inspector.  For example, let's look at
the fields of the host object from the above example:

@example
@group
(pp #@@15)
@print{} #[host 15]
@print{} (type-index 0)
@print{} (name ())
@end group
@end example
@end enumerate
@end deffn

@deffn {procedure+} pa procedure
@code{pa} prints the arguments of @var{procedure}.  This can be used to
remind yourself, for example, of the correct order of the arguments to a
procedure.

@example
@group
for-all?
 @result{} #[compiled-procedure 40 ("boole" #x6) #xC #x20ECB0]

(pa for-all?)
@print{} (items predicate)

(pp for-all?)
@print{}(named-lambda (for-all? items predicate)
@print{}  (let loop ((items items))
@print{}    (or (null? items)
@print{}        (and (predicate (car items))
@print{}             (loop (cdr items))))))
@end group
@end example
@end deffn

@deffn {procedure+} where [obj]
@cindex environments, examining
@cindex inspecting environments
@cindex examining environments
The procedure @code{where} enters the environment examination system.
This allows environments and variable bindings to be examined and
modified.  @code{where} accepts one-letter commands.  The commands can
be found by typing @kbd{?} to the @samp{where>} prompt.  The optional
argument, @var{obj}, is an object with an associated environment: an
environment, a procedure, or a promise.  If @var{obj} is omitted, the
environment examined is the read-eval-print environment from which
@code{where} was called (or an error or breakpoint environment if called
from the debugger).  If a procedure is supplied, @code{where} lets the
user examine the closing environment of the procedure.  This is useful
for debugging procedure arguments and values.
@end deffn

@deffn {procedure+} apropos string [environment [search-parents?]]
@cindex finding procedures
@cindex procedures, finding
@cindex help
Search an environment for bound names containing @var{string} and print
out the matching bound names.  If @var{environment} is specified, it
must be an environment or package name, and it defaults to the current
@sc{repl} environment.  The flag @var{search-parents?} specifies whether
the environment's parents should be included in the search.  The default
is @code{#f} if @var{environment} is specified, and @code{#t} if
@var{environment} is not specified.

@example
(apropos "search")
@print{} #[package 47 (user)]
@print{} #[package 48 ()]
@print{} list-search-negative
@print{} list-search-positive
@print{} nt-fs-flag/case-sensitive-search
@print{} re-string-search-backward
@print{} re-string-search-forward
@print{} re-substring-search-backward
@print{} re-substring-search-forward
@print{} search-ordered-subvector
@print{} search-ordered-vector
@print{} search-protection-list
@print{} string-search-all
@print{} string-search-backward
@print{} string-search-forward
@print{} substring-search-all
@print{} substring-search-backward
@print{} substring-search-forward
@print{} vector-binary-search
@end example
@end deffn

@node Advising Procedures,  , Debugging Aids, Debugging
@section Advising Procedures

Giving advice to procedures is a powerful debugging technique.
@code{trace} and @code{break} are useful examples of advice-giving
procedures.
Note that the advice system only works for interpreted procedures.

@deffn {procedure+} trace-entry procedure
Causes an informative message to be printed whenever
@var{procedure} is entered.  The message is of the form

@example
@group
[Entering #[compound-procedure 1 foo]
    Args: @var{val1}
          @var{val2}
          ...]
@end group
@end example

where @var{val1}, @var{val2} etc.@: are the evaluated arguments supplied
to the procedure.

@example
(trace-entry fib)
(fib 3)
@print{} [Entering #[compound-procedure 19 fib]
@print{}     Args: 3]
@print{} [Entering #[compound-procedure 19 fib]
@print{}     Args: 1]
@print{} [Entering #[compound-procedure 19 fib]
@print{}     Args: 2]
@result{} 3
@end example
@end deffn

@deffn {procedure+} trace-exit procedure
Causes an informative message to be printed when @var{procedure}
terminates.  The message contains the procedure, its argument values,
and the value returned by the procedure.

@example
(trace-exit fib)
(fib 3)
@print{} [1
@print{}       <== #[compound-procedure 19 fib]
@print{}     Args: 1]
@print{} [2
@print{}       <== #[compound-procedure 19 fib]
@print{}     Args: 2]
@print{} [3
@print{}       <== #[compound-procedure 19 fib]
@print{}     Args: 3]
@result{} 3
@end example
@end deffn

@deffn {procedure+} trace-both procedure
@deffnx {procedure+} trace procedure
Equivalent to calling both @code{trace-entry} and @code{trace-exit} on
@var{procedure}.  @code{trace} is the same as @code{trace-both}.

@example
(trace-both fib)
(fib 3)
@print{} [Entering #[compound-procedure 19 fib]
@print{}     Args: 3]
@print{} [Entering #[compound-procedure 19 fib]
@print{}     Args: 1]
@print{} [1
@print{}       <== #[compound-procedure 19 fib]
@print{}     Args: 1]
@print{} [Entering #[compound-procedure 19 fib]
@print{}     Args: 2]
@print{} [2
@print{}       <== #[compound-procedure 19 fib]
@print{}     Args: 2]
@print{} [3
@print{}       <== #[compound-procedure 19 fib]
@print{}     Args: 3]
@result{} 3
@end example
@end deffn

@deffn {procedure+} untrace-entry [procedure]
Stops tracing the entry of @var{procedure}.  If @var{procedure} is not
given, the default is to stop tracing the entry of all entry-traced
procedures.
@end deffn

@deffn {procedure+} untrace-exit [procedure]
Stops tracing the exit of @var{procedure}.  If @var{procedure} is not
given, the default is all exit-traced procedures.
@end deffn

@deffn {procedure+} untrace [procedure]
Stops tracing both the entry to and the exit from @var{procedure}.  If
@var{procedure} is not given, the default is all traced procedures.
@end deffn

@deffn {procedure+} break-entry procedure
Like @code{trace-entry} with the additional effect that a breakpoint is
entered when @var{procedure} is invoked.  Both @var{procedure}
and its arguments can be accessed by calling the procedures
@code{*proc*} and @code{*args*}, respectively.  Use @code{restart} or
@code{continue} to continue from a breakpoint.
@end deffn

@deffn {procedure+} break-exit procedure
Like @code{trace-exit}, except that a breakpoint is entered just prior
to leaving @var{procedure}.  @var{Procedure}, its
arguments, and the result can be accessed by calling the procedures
@code{*proc*}, @code{*args*}, and @code{*result*}, respectively.  Use
@code{restart} or @code{continue} to continue from a breakpoint.
@end deffn

@deffn {procedure+} break-both procedure
@deffnx {procedure+} break procedure
Sets a breakpoint at the beginning and end of @var{procedure}.  This is
@code{break-entry} and @code{break-exit} combined.
@end deffn

@deffn {procedure+} unbreak [procedure]
Discontinues the entering of a breakpoint on the entry to and exit from
@var{procedure}.  If @var{procedure} is not given, the default is
all breakpointed procedures.
@end deffn

@deffn {procedure+} unbreak-entry [procedure]
Discontinues the entering of a breakpoint on the entry to
@var{procedure}.  If @var{procedure} is not given, the default is all
entry-breakpointed procedures.
@end deffn

@deffn {procedure+} unbreak-exit [procedure]
Discontinues the entering of a breakpoint on the exit from
@var{procedure}.  If @var{procedure} is not given, the default is all
exit-breakpointed procedures.
@end deffn

The following three procedures are valid only within the dynamic extent
of a breakpoint.  In other words, don't call them unless you are stopped
inside a breakpoint.

@deffn {procedure+} *proc*
Returns the procedure in which the breakpoint has stopped.
@end deffn

@deffn {procedure+} *args*
Returns the arguments to the procedure in which the breakpoint has
stopped.  The arguments are returned as a newly allocated list.
@end deffn

@deffn {procedure+} *result*
Returns the result yielded by the procedure in which the breakpoint has
stopped.  This is valid only when in an exit breakpoint.
@end deffn

The following procedures install @dfn{advice} procedures that are called
when the advised procedure is entered or exited.  An entry-advice
procedure must accept three arguments: the advised procedure, a list of
the advised procedure's arguments, and the advised procedure's
application environment (that is, the environment in which the
procedure's formal parameters are bound).  An exit-advice procedure must
accept four arguments: the advised procedure, a list of the advised
procedure's arguments, the result yielded by the advised procedure, and
the advised procedure's application environment.

Note that the trace and breakpoint procedures described above are all
implemented by means of the more general advice procedures, so removing
advice from an advised procedure will also remove traces and
breakpoints.

@deffn {procedure+} advise-entry procedure advice
@var{Advice} must be an entry-advice procedure.  @var{Advice} is
attached to @var{procedure}, so that whenever @var{procedure} is
entered, @var{advice} is called.
@end deffn

@deffn {procedure+} advise-exit procedure advice
@var{Advice} must be an exit-advice procedure.  @var{Advice} is attached
to @var{procedure}, so that whenever @var{procedure} returns,
@var{advice} is called.
@end deffn

@deffn {procedure+} advice procedure
Returns the advice procedures, if any, that are attached to
@var{procedure}.  This is returned as a list of two lists: the first
list is all of the entry-advice procedures attached to @var{procedure},
and the second is all of the exit-advice procedures.
@end deffn

@deffn {procedure+} unadvise-entry [procedure]
Removes all entry-advice procedures from @var{procedure}.  If
@var{procedure} is not given, the default is all entry-advised
procedures.
@end deffn

@deffn {procedure+} unadvise-exit [procedure]
Removes exit-advice procedures from @var{procedure}.  If @var{procedure}
is not given, the default is all exit-advised procedures.
@end deffn

@deffn {procedure+} unadvise [procedure]
Removes all advice procedures from @var{procedure}. This is a
combination of @code{unadvise-entry} and @code{unadvise-exit}.  If
@var{procedure} is not given, the default is all advised procedures.
@end deffn

@node GNU Emacs Interface, Edwin, Debugging, Top
@chapter GNU Emacs Interface

There is an interface library, called @file{xscheme}, distributed with
MIT Scheme and GNU Emacs, which facilitates running Scheme as a
subprocess of Emacs.  If you wish to use this interface, please install
the version of @file{xscheme.el} that comes with MIT Scheme, as it is
guaranteed to be correct for your version of Scheme.

This interface works under unix only, because it requires unix signals
for its operation.  Porting it to either OS/2 or Windows would require
reimplementing the interface to eliminate the use of signals.  We have
no plans to do this.

@findex run-scheme
@findex -emacs
To invoke Scheme from Emacs, load the @file{xscheme} library, then use
@kbd{M-x run-scheme}.  You may give @code{run-scheme} a prefix argument,
in which case it will allow you to edit the command line that is used to
invoke Scheme.  @emph{Do not} remove the @code{-emacs} option!

@emph{Note carefully:} In Emacs 19 and later, the @code{run-scheme}
command exists, but is different from the one described here!  In order
to get this interface, you must load the @file{xscheme} library before
executing @code{run-scheme}.

@findex scheme-interaction-mode
Scheme will be started up as a subprocess in a buffer called
@samp{*scheme*}.  This buffer will be in @code{scheme-interaction-mode}
and all output from the Scheme process will go there.  The mode line for
the @samp{*scheme*} buffer will have this form:

@example
--**-*scheme*: 1 [Evaluator]           (Scheme Interaction: input)------
@end example

@noindent
@cindex level number, REPL
The first field, showing @samp{1} in this example, is the level number.

@noindent
The second field, showing @samp{[Evaluator]} in this example, describes
the type of @sc{repl} that is running.  Other values include:

@example
@group
[Debugger]
[Where]
@end group
@end example

@noindent
The @dfn{mode} after @samp{Scheme Interaction} is one of:

@table @samp
@item input
Scheme is waiting for input.

@item run
Scheme is running an evaluation.

@item gc
Scheme is garbage collecting.
@end table

@findex scheme-mode
When @file{xscheme} is loaded, @code{scheme-mode} is extended to include
commands for evaluating expressions (do @kbd{C-h m} in any
@code{scheme-mode} buffer for the most up-to-date information):

@table @kbd
@item M-o
@kindex M-o
@findex xscheme-send-buffer
Evaluates the current buffer (@code{xscheme-send-buffer}).

@item M-z
@kindex M-z
@findex xscheme-send-definition
Evaluates the current definition (@code{xscheme-send-definition}).  This
is also bound to @kbd{C-M-x}.

@item C-M-z
@kindex C-M-z
@findex xscheme-send-region
Evaluates the current region (@code{xscheme-send-region}).

@item C-x C-e
@kindex C-x C-e
@findex xscheme-send-previous-expression
Evaluates the expression to the left of point@*
(@code{xscheme-send-previous-expression}).  This is also bound to
@kbd{M-@key{RET}}.

@item C-c C-s
@kindex C-c C-s
@findex xscheme-select-process-buffer
Selects the @samp{*scheme*} buffer and places you at its end
(@code{xscheme-select-process-buffer}).

@item C-c C-y
@kindex C-c C-y
@findex xscheme-yank-previous-send
Yanks the most recently evaluated expression, placing it at point
(@code{xscheme-yank-previous-send}).  This works only in the
@samp{*scheme*} buffer.
@end table

The following commands provide interrupt capability:

@table @kbd
@item C-c C-c
@kindex C-c C-c
@findex xscheme-send-control-g-interrupt
Like typing @kbd{C-g} when running Scheme without Emacs.@*
(@code{xscheme-send-control-g-interrupt})

@item C-c C-x
@kindex C-c C-x
@findex xscheme-send-control-x-interrupt
Like typing @kbd{C-c C-x} when running Scheme without Emacs.@*
(@code{xscheme-send-control-x-interrupt})

@item C-c C-u
@kindex C-c C-u
@findex xscheme-send-control-u-interrupt
Like typing @kbd{C-c C-u} when running Scheme without Emacs.@*
(@code{xscheme-send-control-u-interrupt})

@item C-c C-b
@kindex C-c C-b
@findex xscheme-send-breakpoint-interrupt
Like typing @kbd{C-c C-b} when running Scheme without Emacs.@*
(@code{xscheme-send-breakpoint-interrupt})

@item C-c C-p
@kindex C-c C-p
@findex xscheme-send-proceed
Like evaluating @code{(continue)}.  (@code{xscheme-send-proceed})
@end table

@node Edwin, Release Notes, GNU Emacs Interface, Top
@chapter Edwin

This chapter describes how to start Edwin, the MIT Scheme text editor.
Edwin is very similar to GNU Emacs --- you should refer to the GNU Emacs
manual for information about Edwin's commands and key bindings ---
except that Edwin's extension language is MIT Scheme, while GNU Emacs
extensions are written in Emacs Lisp.  This manual does not discuss
customization of Edwin.

@menu
* Starting Edwin::              
* Leaving Edwin::               
* Edwin Scheme Mode::           
* Edwin Scheme Evaluation::     
* Edwin REPL Mode::             
* Edwin Debugger::              
* Last Resorts::                
@end menu

@node Starting Edwin, Leaving Edwin, Edwin, Edwin
@section Starting Edwin

To use Edwin, start Scheme with the following command-line options:

@example
scheme -edwin -edit
@end example

@noindent
Alternatively, you can load Edwin by giving the @code{-edwin}
command-line option and then calling the procedure @code{edit}:

@deffn {procedure+} edit
@deffnx {procedure+} edwin
Enter the Edwin text editor.  If entering for the first time, the editor
is initialized (by calling @code{create-editor} with no arguments).
Otherwise, the previously-initialized editor is reentered.

The procedure @code{edwin} is an alias for @code{edit}.
@end deffn

@defvr {variable+} inhibit-editor-init-file?
When Edwin is first initialized, it loads your init file (called
@file{~/.edwin} under unix, @file{edwin.ini} on PCs) if you have one.  If
the Scheme variable @code{inhibit-editor-init-file?} is true, however,
your init file will not be loaded even if it exists.  By default, this
variable is false.

Note that you can set this variable in your Scheme init file
(@pxref{Customizing Scheme}).
@end defvr

@deffn {procedure+} create-editor arg @dots{}
Initializes Edwin, or reinitializes it if already initialized.
@code{create-editor} is normally invoked automatically by @code{edit}.

If no @var{arg}s are given, the value of @code{create-editor-args} is
used instead.  In other words, the following are equivalent:

@example
@group
(create-editor)
(apply create-editor create-editor-args)
@end group
@end example

@noindent
On the other hand, if @var{arg}s are given, they are used to update
@code{create-editor-args}, making the following equivalent:

@example
@group
(apply create-editor @var{args})
(begin (set! create-editor-args @var{args}) (create-editor))
@end group
@end example
@end deffn

@defvr {variable+} create-editor-args
This variable controls the initialization of Edwin.  The following
values are defined:

@table @code
@item (#f)
This is the default.  Creates a window of some default size, and uses
that window as Edwin's main window.  Under unix, if X11 is not available
or if the @code{DISPLAY} environment variable is undefined, Edwin will
run on Scheme's console.

@item (x)
Unix only.  Creates an X window and uses it as Edwin's main window.
This requires the @code{DISPLAY} environment variable to have been set
to the appropriate value before Scheme was started.

@item (x @var{geometry})
Unix only.  Like @code{(x)} except that @var{geometry} specifies the
window's geometry in the usual way.  @var{Geometry} must be a character
string whose contents is an X geometry specification.

@item (console)
Unix only.  Causes Edwin to run on Scheme's console, or in unix
terminology, the standard input and output.  If the console is not a
terminal device, or is not powerful enough to run Edwin, an error will
be signalled at initialization time.

@item (pm)
OS/2 only.  Creates a Presentation Manager window and uses it as Edwin's
main window.

@item (win32)
Windows only.  Creates a window and uses it as Edwin's main window.
@end table
@end defvr

@node Leaving Edwin, Edwin Scheme Mode, Starting Edwin, Edwin
@section Leaving Edwin

Once Edwin has been entered, it can be exited in the following ways:

@table @kbd
@item C-x z
@kindex C-x z
@findex suspend-edwin
Stop Edwin and return to Scheme (@code{suspend-edwin}).  The call to the
procedure @code{edit} that entered Edwin returns normally.  A subsequent
call to @code{edit} will resume Edwin where it was stopped.

@item C-x c
@kindex C-x c
@findex save-buffers-kill-edwin
Offer to save any modified buffers, then kill Edwin, returning to Scheme
(@code{save-buffers-kill-edwin}).  This is like the @code{suspend-edwin}
command, except that a subsequent call to @code{edit} will reinitialize
the editor.

@item C-x C-z
@kindex C-x C-z
@findex suspend-scheme
Stop Edwin and suspend Scheme, returning control to the operating
system's command interpreter (@code{suspend-scheme}).  When Scheme is
resumed (using the command interpreter's job-control commands), Edwin is
automatically restarted where it was stopped.  This command is identical
to the @kbd{C-x C-z} command of GNU Emacs.

@item C-x C-c
@kindex C-x C-c
@findex save-buffers-kill-scheme
Offer to save any modified buffers, then kill both Edwin and Scheme
(@code{save-buffers-kill-scheme}).  Control is returned to the operating
system's command interpreter, and the Scheme process is terminated.
This command is identical to the @kbd{C-x C-c} command of GNU Emacs.
@end table

@node Edwin Scheme Mode, Edwin Scheme Evaluation, Leaving Edwin, Edwin
@section Scheme Mode

As you might expect, Edwin has special support for editing and
evaluating Scheme code.  This section describes @dfn{Scheme Mode}, the
appropriate mode for editing MIT Scheme programs.

Scheme mode is normally entered automatically by visiting a file whose
file name ends in @samp{.scm}.  You can also mark a file as Scheme code
by placing the string @samp{-*-Scheme-*-} on the first line of the
file.  Finally, you can put any buffer in Scheme mode by executing the
command @kbd{M-x scheme-mode}.

Scheme mode is similar to the Emacs modes that edit Lisp code.  So, for
example, @kbd{C-i} indents the current line, and @kbd{C-M-q} indents the
expression to the right of point.  The close parenthesis will
temporarily flash the matching open parenthesis.  Most Scheme constructs
requiring special indentation are recognized by Scheme mode, for
example, @code{begin}, @code{do}, and @code{let}.

Scheme mode also provides support that is specific to Scheme programs,
much as Emacs-Lisp mode does in Emacs.  Completion of global variable
names is provided: type the first few characters of a variable, then
type @kbd{C-M-i}, and Edwin will attempt to complete the variable name
using the current set of bound variables.  If @kbd{C-M-i} is given a
prefix argument, it will complete the name using the current set of
interned symbols (which includes the bound variables as a subset).

The @kbd{M-A} command (note the @emph{uppercase} @kbd{A}) will show the
parameters of a procedure when point is inside a procedure call.  For
example, type the string @samp{(quotient}, then press @kbd{M-A}, and the
command will echo @samp{(n d)} in the echo area.  With a prefix
argument, @kbd{M-A} will insert the parameter names in the buffer at
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

Scheme mode also provides commands for evaluating Scheme expressions.
The simplest evaluation command is @kbd{C-x C-e}, which evaluates the
expression to the left of point.  (This key is bound in all buffers,
even if they don't contain Scheme code.)  The command @kbd{M-z}
evaluates the definition that point is in (a definition is an expression
starting with a left parenthesis in the leftmost column).  The command
@kbd{M-:} prompts for an expression in the minibuffer, evaluates it, and
prints the value in the echo area.

Other commands that evaluate larger amounts of code are @kbd{C-M-z},
which evaluates all of the expressions in the region, and @kbd{M-o},
which evaluates the entire buffer.  Both of these commands are
potentially dangerous in that they will evaluate anything that appears
to be an expression, even if it isn't intended to be.

Normally, these commands evaluate expressions by sending them to a
@sc{repl} buffer, which performs the evaluations in a separate thread.
This has two advantages: it allows you to continue editing while the
evaluation is happening, and it keeps a record of each evaluation and
its printed output.  If you wish to stop a running evaluation and to
erase any pending expressions, use the @kbd{C-c C-c} command from any
Scheme buffer.  (Note that by default, Edwin starts up with one
@sc{repl} buffer, called @samp{*scheme*}.)

If you would prefer to have Scheme mode evaluation commands evaluate
directly, rather than sending expressions to the @sc{repl} buffer, set
the Edwin variable @code{evaluate-in-inferior-repl} to @code{#f}.  In
this case, you will not be able to use Edwin while evaluation is
occurring; any output from the evaluation will be shown in a pop-up
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

Edwin provides a special mechanism for interacting with Scheme
read-eval-print loops: @sc{repl} buffers.  A @sc{repl} buffer is
associated with a Scheme @sc{repl} running in a separate thread of
execution; because of this, expressions may be evaluated in this buffer
while you simultaneously do other things with the editor.  A @sc{repl}
buffer captures all printed output from an evaluated expression, as well
as supporting interactive programs such as @code{debug}.  For these and
other reasons, @sc{repl} buffers are the preferred means for interacting
with the Scheme interpreter.

When Edwin starts, it has one buffer: a @sc{repl} buffer called
@samp{*scheme*}.  The command @kbd{M-x repl} selects this buffer, if it
exists; otherwise it creates a new @sc{repl} buffer.  If you want two
@sc{repl} buffers, just rename the @samp{*scheme*} buffer to something
else and run @kbd{M-x repl} again.

@sc{repl} buffers support all the same evaluation commands that Scheme
mode does; in fact, @sc{repl} buffers use a special mode called
@sc{repl} mode that inherits from Scheme mode.  Thus, any key bindings
defined in Scheme mode are also defined in @sc{repl} mode.  One
exception to this is the @kbd{M-o} command, which is deliberately
undefined in @sc{repl} mode; otherwise it would be too easy to
re-evaluate all the previously evaluated expressions in the @sc{repl}
buffer.

In addition to evaluation commands, @sc{repl} mode provides a handful of
special commands for controlling the @sc{repl} itself.  The commands
@kbd{C-c C-x} and @kbd{C-c C-u} abort the current evaluation, returning
to the current or previous @sc{repl} levels, respectively.  The command
@kbd{C-c C-b} interrupts the current evaluation, entering a breakpoint.

Each @sc{repl} buffer maintains a history of the expressions that were
typed into it.  Several commands allow you to access the contents of
this history.  The command @kbd{M-p} moves backwards through the
history, inserting previously evaluated expressions at point.  Likewise,
@kbd{M-n} moves forward through the history.  The commands @kbd{C-c C-r}
and @kbd{C-c C-s} search backward and forward through the history for a
particular string.  The command @kbd{C-c C-o} deletes any output from
the previous evaluation; use this command with care since it cannot be
undone.  The command @kbd{C-c C-l} finds the most recent expression in
the buffer and moves point there.

When an expression that you evaluate signals an error, the @sc{repl}
buffer notices this and offers to run the debugger for you.  Answer this
question with a @samp{y} or @samp{n} response.  You can start the
debugger whenever the @sc{repl} buffer is listening by executing the
@kbd{C-c C-d} command.  In either case, this starts the Edwin debugger,
which pops up a new window containing the debugger.  Your @sc{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

The Edwin debugger is similar to the command-line debugger, except that
it takes advantage of multiple windows and Edwin's command structure to
provide a more intuitive interface.  The debugger operates as a browser,
much like Dired, presenting you with an overview of the subproblem
structure, and allowing you to examine parts of that structure in more
detail by selecting the parts.  When started, the debugger creates a
buffer @samp{*debug*} showing the subproblem structure, and selects the
first line.

Each line beginning with @samp{S} represents either a subproblem or
stack frame.  A subproblem line may be followed by one or more indented
lines (beginning with the letter @samp{R}) which represent reductions
associated with that subproblem.  The subproblems are indexed with the
natural numbers.  To obtain a more complete description of a subproblem
or reduction, click the mouse on the desired line or move the cursor to
the line using the arrow keys (or @kbd{C-n} and @kbd{C-p}).  The
description buffer will display the additional information.

The description buffer contains three major regions.  The first region
contains a pretty-printed version of the current expression.  The
current subproblem within the expression is highlighted.  The second
region contains a representation of the frames of the environment of the
current expression.  The bindings of each frame are listed below the
frame header.  If there are no bindings in the frame, none will be
listed.  The frame of the current expression is preceded with
@samp{==>}.

The bottom of the description buffer contains a third region for
evaluating expressions in the environment of the selected subproblem or
reduction.  This is the only portion of the buffer where editing is
possible.  This region can be used to find the values of variables in
different environments, or even to modify variable values or data
structures (note that variables in compiled code cannot usually be
modified).

Typing @kbd{e} creates a new buffer in which you may browse through the
current environment.  In this new buffer, you can use the mouse, the
arrows, or @kbd{C-n} and @kbd{C-p} to select lines and view different
environments.  The environments listed are the same as those in the
description buffer.  If the selected environment structure is too large
to display (i.e.@: if the number of bindings in the environment exceeds
the value of the editor variable @code{environment-package-limit}) a
message to that effect is displayed.  To display the environment in this
case, use @kbd{M-x set-variable} to set @code{environment-package-limit}
to @code{#f}.  At the bottom of the new buffer is a region for
evaluating expressions, similar to that of the description buffer.

The appearance of environment displays is controlled by the editor
variables @code{debugger-show-inner-frame-topmost?} and
@code{debugger-compact-display?}  which affect the ordering of
environment frames and the line spacing respectively.

Type @kbd{q} to quit the debugger, killing its primary buffer, any
others that it has created, and the window that was popped up to show
the debugger.

@strong{Note}: The description buffers created by the debugger are given
names beginning with spaces so that they do not appear in the buffer
list; these buffers are automatically deleted when you quit the
debugger.  If you wish to keep one of these buffers, simply rename it
using @kbd{M-x rename-buffer}: once it has been renamed, it will not be
automatically deleted.

@node Last Resorts,  , Edwin Debugger, Edwin
@section Last Resorts

When Scheme exits abnormally it tries to save any unsaved Edwin buffers.
The buffers are saved in an auto-save file in case the original is more
valuable than the unsaved version.  You can use the editor command
@kbd{M-x recover-file} to recover the auto-saved version.  The name
used to specify an auto-save file is operating-system dependent: under
unix, and on PC file systems with long file names, @file{foo.scm} will
be saved as @file{#foo.scm#}; on PC file systems with short file names,
it will be saved as @file{foo.sav}.

The following Scheme procedures are useful for recovering from bugs in
Edwin's implementation.  All of them are designed for use when Edwin is
@emph{not} running --- they should not be used when Edwin is running.
These procedures are designed to help Edwin's implementors deal with
bugs during the implementation of the editor; they are not intended for
casual use, but as a means of recovering from bugs that would otherwise
require reloading the editor's world image from the disk.

@deffn {procedure+} save-editor-files
Examines Edwin, offering to save any unsaved buffers.  This is useful if
some bug caused Edwin to die while there were unsaved buffers, and you
want to save the information without restarting the editor.
@end deffn

@deffn {procedure+} reset-editor
Resets Edwin, causing it to be reinitialized the next time that
@code{edit} is called.  If you encounter a fatal bug in Edwin, a good
way to recover is to first call @code{save-editor-files}, and then to
call @code{reset-editor}.  That should completely reset the editor to
its initial state.
@end deffn

@deffn {procedure+} reset-editor-windows
Resets Edwin's display structures, without affecting any of the buffers
or their contents.  This is useful if a bug in the display code causes
Edwin's internal display data structures to get into an inconsistent
state that prevents Edwin from running.
@end deffn

@node Release Notes, GNU Free Documentation License, Edwin, Top
@appendix Release Notes

The previous full release of MIT Scheme was version 7.5.17.  This
section describes changes that have occurred since that time.  For
more detailed information, see the @file{ChangeLog} files in the
source code.

Note that MIT Scheme still conforms to the @cite{Revised^4 Report on the
Algorithmic Language Scheme}, but not to the @cite{Revised^5 Report on
The Algorithmic Language Scheme}.

@menu
* Recent Changes::              
* Older Changes::               
@end menu

@node Recent Changes, Older Changes, Release Notes, Release Notes
@appendixsec Recent Changes

These are the changes since release 7.6.0:

@itemize @bullet
@item
Release 7.7.1 fixes several bugs in @acronym{IMAIL}; fixes a bug that
prevented the use of server sockets on Windows systems; and fixes a bug
that caused the debugger to generate errors in common circumstances.

@item
Release 7.7.0 provides ``hygienic'' macro support, as defined in
@cite{R^4RS} and @cite{R^5RS}.  This is a complete rewrite of the syntax
engine, so any program that uses macros should be rewritten to use the
new engine.  A subset of the old macro-definition syntax is still
supported, but this will eventually be removed.  Note that the new
syntax engine has no effect on the compiled-code format; most binaries
compiled by release 7.6.x should continue to work.

There are several user-visible consequences to this change:

@itemize @bullet
@item
These syntactic keywords have been eliminated:
@code{define-macro},
@code{in-package},
@code{macro},
@code{make-environment},
@code{scode-quote},
@code{unassigned?}, and
@code{using-syntax}.

@item
The syntactic keyword @code{the-environment} has been restricted to use
in top-level environments.  It is no longer allowed in the body of any
binding form (e.g.@: @code{lambda}, @code{let}).

@item
Syntactic keywords are now stored in environments, rather than in a
separate syntax-table structure.  The environment abstraction has been
enhanced to support this, as well as to make it more general.  The
changes are documented in the reference manual.

@item
The syntax-table abstraction has been eliminated, and most procedures
and arguments involving syntax tables have been removed.  One exception
is the @code{load} procedure, which still accepts a syntax-table
argument, but ignores it.
@end itemize

Although the 7.6.1 release had a workaround for problems with certain
@acronym{AMD} Athlon processors, the workaround was ineffective on
machines running Windows operating systems (and possibly OS/2 systems as
well).  This version fixes that problem.

The hash-table abstraction is now always loaded.  It's not necessary to
call @code{load-option} prior to use of hash tables.  For upwards
compatibility, calling @samp{(load-option 'hash-table)} is still
permitted but does nothing.

@item
Release 7.6.1 provides a workaround for a bug on some @acronym{AMD}
Athlon processors (specifically, models 1, 3, and 4).  This bug causes
those processors to incorrectly execute certain kinds of self-modifying
code, including that used by MIT Scheme.

Release 7.6.1 also fixes a problem that caused the *PARSER and XML
subsystems not to load correctly on Windows and OS/2 systems.
@end itemize

@node Older Changes,  , Recent Changes, Release Notes
@appendixsec Older Changes

These are the changes that occurred between releases 7.6.0 and 7.5.17:

@itemize @bullet
@item
The variable-reference machinery has been completely redesigned.  The
new design provides two new features: (1) a procedure
@code{link-variables} that can link two variable bindings with
different names (previously @code{environment-link-name} could only
link bindings with the same name); (2) a new procedure
@code{unbind-variable} that can remove a variable binding.  Both of
these operations work only on ``top-level'' environments; they don't
work on environments created by invoking compiled procedures.

@strong{This is an incompatible change to the compiled-code
representation.  All programs must be recompiled.}

@item
The ``packaging'' subsystem has been redesigned to make it more
flexible.  The new design takes advantage of the improved
variable-linking mechanism to allow packages to export bindings using
names different from their internal names.  Also, each package now
maintains an in-memory data structure that should (in principal) allow
it to be uninstalled or reinstalled.  This subsystem is still
evolving; expect further changes in the future.

This subsystem is now included in the released binaries; it can be
loaded by @samp{(load-option 'cref)}.

@item
Compiled-code debugging information is now keyed to prevent using the
wrong debugging info when examining compiled code.  This means that
in-memory data structures have an identifying key that is matched
against a corresponding key in the debugging-info file.  The debugging
info is used only when the keys match.

@item
MIT Scheme now has a non-validating @acronym{XML} parser that is
mostly conformant (except that it doesn't support @acronym{UTF-16}).

@item
There is very limited support for @acronym{UTF-8}.  At present this is
only used by the @acronym{XML} parser.

@item
All string and character procedures now operate on
@acronym{ISO-8859-1} rather than @acronym{US-ASCII} as the base
character set.  This isn't real internationalization support, but at
least it broadens the character support slightly.  This involved
changing a number of procedures that were formerly written in C and
are now written in Scheme, which may have a performance impact on some
uses.

@item
The procedure @code{length} now detects circularities in its argument
and signals an error.

@item
A new @code{rexp} facility provides a more readable syntax for
specifying regular expressions.  This syntax can be compiled into the
usual syntax.

@item
There is a new @dfn{parser buffer} abstraction that supports the
building of parsers with backtracking.  An associated high-level
parser description language allows parsers to be described in a
@acronym{BNF}-like language that is compiled into efficient Scheme
code.

@item
A new procedure @code{flo:finite?} returns @samp{#f} for infinite or
@samp{NaN} flonums and @samp{#t} for all others.

@item
The signal-handling code for GNU/Linux systems has been changed to
take advantage of additional information identifying the types of
arithmetic exceptions.  This allows more accurate error messages to
be generated.

@item
The following procedure names were changed:

@multitable @columnfractions .5 .5
@item Old name
@tab New name
@item @code{list-transform-positive}
@tab @code{keep-matching-items}
@item @code{list-transform-negative}
@tab @code{delete-matching-items}
@item @code{list-search-positive}
@tab @code{find-matching-item}
@end multitable

@noindent
and the following new procedures were implemented:
@code{keep-matching-items!} and @code{delete-matching-items!}.

@item
@acronym{IMAIL} now supports commands to sort folders according to
various criteria.  The design is similar to that of Rmail.

@item
@acronym{IMAIL} has been re-engineered to improve performance on very
large folders.  There is now a disk cache for each @acronym{IMAP}
folder, to eliminate unnecessary network delays.  Also, the summary
buffer previously used a quadratic algorithm to associate lines in the
summary with messages in the folder; it now uses a linear algorithm.

@item
A new @acronym{IMAIL} command @code{imail-file-message} appends the
text of a message to a file more or less as it appears in the buffer.
This is intended to allow collecting messages into a file in a
human-readable format.

@item
@acronym{IMAIL} used to determine the type of file folders by their
file names; now it examines the file contents instead.  When creating
a new file folder, it prompts for the type.
@end itemize

@node GNU Free Documentation License, Index, Release Notes, Top
@unnumbered GNU Free Documentation License
@include gfdl.texinfo

@node Index,  , GNU Free Documentation License, Top
@unnumbered Index
@printindex cp

@contents
@bye

@c Local Variables:
@c selective-display: t
@c truncate-lines: nil
@c End:
