We will use as an example the installation for HP 9000 series 400 computers. The installation for other Unix systems is similar. If you are installing for an HP 9000 series 700 or 800, see also section HP-PA Installation.
MIT Scheme is distributed as a compressed `tar' file. The tar file contains a single directory, called `dist-7.3', and that directory contains subdirectories `bin', `etc', and `lib'. The `bin' subdirectory contains two executable files, `scheme' and `bchscheme'. The `etc' subdirectory contains several files that are used during the installation process. The `lib' subdirectory contains several files and subdirectories 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.
gzip -cd hp400.tar.gz | tar xvf -If you do not have the `gzip' program: we have built executables of this program for each of the machines that we support. Either use the executable that we have already built, or else get the gzip sources (from us or from numerous other sources) and build it yourself.
cd dist-7.3The easiest way to install the files is to use the "install.sh" shell script that we've provided in the distribution. You will need to edit that script to tell it where and how you want Scheme installed. If you want to do something more complicated, or if the script can't easily be made to work for your system, use the script as a guide to installation.
./install.sh
schemeat the command line (if you use the C shell, you may have to type `rehash' before `scheme' will be recognized).
If you are using an HP 9000 series 700/800 computer (often called an HP Precision Architecture machine, or HP-PA for short), read this section.
Scheme has built-in code that flushes the instruction and data caches of your machine in certain circumstances. This code is sensitive to your computer's model, because each model has different cache hardware.
This distribution contains a database, called `hppacach.mod', that describes the cache structure for each model of computer. As of this writing, that database contains entries for the following models:
705, 710, 715, 720, 730, 735, 750, 755, 834, 835, 850, 867
If you have a model that is not in the database, Scheme will not run -- instead it will print an error message informing you of this fact, and stop. If this happens, you must add an entry to the database. This must be done once, at installation, for each new model.
Here is the procedure for updating the database:
cd /usr/local/lib/mit-scheme ./hppacache -update hppacach.modThe reason that you must be super-user is that `hppacache' needs to read the device `/dev/kmem' to get the information that it needs. Normally, `/dev/kmem' is readable only by the super-user, or by users in group
sys. Thus, becoming super-user is the easiest way
to read this information. An alternative method for doing this is to
change the permissions of the `hppacache' program so that it is in
group sys, and to turn on its "set group ID on exec" permission
bit, but since this also requires you to be super-user, you might as
well just execute the program as the super-user.
Please note that you must execute this program on the computer whose
model you wish to add to the database. Also, if you wish to add several
models to the database, you must execute the program once on each model.
If you have several computers that are all of the same model, you need
only update the database once from one of the computers; thereafter all
of the other computers of that model will work.
cd /usr/local/lib/mit-scheme ./hppacache -print hppacach.mod > model-7xx(If you have previously updated the database, you do not need to be super-user to execute this command.) The resulting file, `model-7xx' in this example, is the model information for the machine that you executed the command on; it is C code that we can use to update our copy of the database. Send the model information for each new model to us by electronic mail at
bug-cscheme@zurich.ai.mit.edu. Thanks!
This section describes how to install MIT Scheme on DOS, Windows 3.1, and Windows NT. We would prefer that the Windows version be used, rather than the DOS version, because we intend to maintain the DOS version only so long as it is convenient. For the most part the installation on any of these platforms uses the same files, and the procedure is similar. It is possible to install MIT Scheme so that it will run under all three operating systems on one computer, but this does require some care with the configuration of the system.
Note that we have only tested the DOS version on Microsoft DOS 5.0.
MIT Scheme requires at least a 386SX with 8Mb RAM. The bare minimum disk space required is 5.5Mb, which gives you a command line interface for Scheme. We strongly recommend a more advanced environment. To build the Edwin editor band requires an additional 4.3Mb. The whole installation without source code occupies 36Mb of disk.
The installation is split into several files according to functional units and the size constraints of a 1.4M high density 3.5" floppy disk. The following files are distributed:
BIN.ZIP Scheme binaries for Windows 3.1/Windows NT DOSBIN.ZIP Scheme binaries for DOS LIB.ZIP Smaller files from Scheme library RUNTIME.ZIP `runtime.com' band RUNNOFLO.ZIP `runtime.com' band for DOS machines with no FP hardware EDDEL.ZIP `eddel.com': a kit to build `edwin.com' band COMPDEL.ZIP `compdel.com': a kit to build `compiler.com' band HELP.ZIP WinHelp User and Reference Manuals BCIRUN1.ZIP Debugging information for runtime system BCIRUN2.ZIP " " " " " BCIRUN3.ZIP " " " " " BCIED1.ZIP Debugging information for Edwin BCIED2.ZIP " " " " BCIED3.ZIP " " " " BCINOFLO.ZIP Extra debugging information for machines with no FP hardware SRCRUN.ZIP Source code for the runtime system SRCUC.ZIP Source code for the microcode (C) SRCED.ZIP Source code for Edwin SRCCOMP.ZIP Source code for i386 compiler WIN32S.ZIP Win32s installation floppy from Microsoft INSTALL.TXT These instructions UNZIP.EXE Program to unpack the `.zip' files
Minimal installation on Windows NT requires: `BIN.ZIP', `LIB.ZIP' and `RUNTIME.ZIP'.
For the Edwin editor and the native code compiler add `EDDEL.ZIP' and `COMPDEL.ZIP' repectively.
Any configuration for Windows 3.1 is the same as for Windows NT except that Win32S also needs to be installed.
For DOS the minimal installation comprises `DOSBIN.ZIP', `LIB.ZIP' and one of `RUNTIME.ZIP' or `RUNNOFLO.ZIP'.
These installation instructions describe how to install MIT Scheme on one or more of DOS, Windows 3.1, and Windows NT. If you are installing for DOS and another operating system, you should do the bulk of the installation using the windowing environment.
In each of the following steps the amount of disk space consumed is indicated in square brackets. These sizes do not include the `.zip' files which are required only during installation.
a: unzip wherever\win32s.zipRun the `setup' command on the floppy disk. If you are not sure whether you have Win32s installed, or what version you have installed, try to install it anyway. If you have version 1.0 then the Win32s installation disk will upgrade your Win32s system to version 1.1.
a:setup
mkdir c:\scheme cd \schemescheme is the string `
C:\scheme'.
unzip wherever\bin.zip unzip wherever\lib.zip unzip wherever\runtime.zipThis will create the directory structures `scheme\bin', `scheme\lib' and `scheme\etc', and unpack the essential files. (Wherever stands for the place that you have put the `.zip' files, which might be another directory or a floppy disk.) If you have a computer without floating-point hardware (e.g. a 386 machine or a 486SX) and you wish to run the DOS version then you must install the runtime with special floating point support instead of `runtime.zip':
unzip wherever\runnoflo.zip
unzip wherever\dosbin.zipThis creates a `scheme\dos-bin' directory containing the DOS versions of the `.exe' files. These files are different from the Windows versions, so they are placed in a different directory to allow both versions to co-exist on your computer. It is only the `.exe' files that differ between DOS and Windows. The other parts of the MIT Scheme system are shared. The DOS version will run under Windows 3.1 but not under NT. Either running on DOS or Windows 3.1, the DOS version has no graphics support
path %PATH%;scheme\bin\win31This command must be in a `.bat' file to work
PATH in the
system environment (using the Registry Editor, regedt32
PATH=scheme\bin\nt in your
environment (use the control panel's system option
PATH rather than copying
files, i.e. you must arrange for Windows 3.1 to be run with
`scheme\bin\win31' on the path and for Windows NT to be run
with `scheme\bin\nt' on the path.
This can be done by putting
path %PATH%;scheme\bin\win31in the `autoexec.bat' file and adding `scheme\bin\nt' to the Windows NT system environment path.
PATH.
MITSCHEME_LIBRARY_PATH is defined:
set MITSCHEME_LIBRARY_PATH=scheme\lib
scheme\bin\schemeFrom DOS you should be able to get Scheme running by typing the following at the DOS prompt:
scheme\dos-bin\schemeIf there are any problems at this stage, review the installation so far. Remember that you might have to restart your machine to get the effect of any changes that you made in `autoexec.bat' or the NT registry.
File|Run option:
scheme\bin\scheme -load scheme\etc\pmgrpThis program creates a program group called `MIT Scheme' which contains
unzip wherever\help.zipThis installs two windows help files, `user.hlp' and `scheme.hlp', in `scheme\bin'.
cd scheme unzip wherever\eddel.zipTo build `edwin.com' start the `build EDWIN.COM band' icon, or run the following command:
scheme\bin\scheme -large -load scheme\etc\build -eval (edwin.com)This will load in `eddel.com' and create the new band [4.3Mb]. After a successful build the program will exit. The `edwin.com' band can be used by both the DOS and Windows versions, so you only need to do this step once, even if you are installing for more than one of DOS, Windows 3.1, and Windows NT. If you are installing only for DOS you will have to build `edwin.com' from the command line. Be sure to run the DOS `scheme.exe' rather than the Windows version:
scheme\dos-bin\scheme -large -load scheme\etc\build -eval (edwin.com)
cd scheme unzip wherever\compdel.zipTo build `compiler.com' start the `build COMPILER.COM band' icon, or run the following command:
scheme\bin\scheme -large -load scheme\etc\build -eval (compiler.com)This will load in `compdel.com' and create the new `compiler.com' band [4.8Mb]. After a successful build the program will exit. As for Edwin, this step needs to be done only once. If you choose to build this band using the DOS version be sure to run the DOS `scheme.exe' rather than the Windows version:
scheme\dos-bin\scheme -large -load scheme\etc\build -eval (compiler.com)
cd scheme unzip wherever\eddel.zip unzip wherever\compdel.zipTo build `all.com' start the `build ALL.COM band' icon, or run the following command:
scheme\bin\scheme -large -load scheme\etc\build -eval (all.com)This will load in both `eddel.com' and `compdel.com' into the runtime band and create the new band [6.7Mb]. After a successful build the program will exit. If you choose to build this band under DOS, be sure to run the DOS `scheme.exe' rather than the Windows version:
scheme\dos-bin\scheme -large -load scheme\etc\build -eval (all.com)
bchscheme instead of scheme copy
the icons and edit the command lines to change `scheme' to `bchschem'
(that is right: no tailing `e').
MITSCHEME_INF_DIRECTORY environment variable to this
directory. `bcied1.zip' through `bcied3.zip' [3.8Mb
installed] hold the debugging information files for Edwin.
This chapter describes interesting features and problems for the 7.3 release.
The last full release of the MIT Scheme system was version 7.1.3 in 1991. Since that time, there was a partial release of version 7.2 for i386/i486 machines and some MIPS R3000 machines. This section summarizes the changes that have occurred since version 7.1.3. The changes are divided into two parts: those that were incorporated in the 7.2 partial release, and those that were subsequently incorporated.
This is an abbreviated list of the changes that have been incorporated in the 7.3 release since the (partial) 7.2 release.
define-structure now
creates records by default; these records are identical to those created
with the record abstraction.
call-with-current-continuation is now properly tail-recursive.
-no-suspend-file prevents the generation
of `scheme_suspend' files.
call-with-values ;replaces with-values current-load-pathname error-output-port fold-left fold-right interaction-i/o-port notification-output-port prompt-for-command-char prompt-for-command-expression prompt-for-confirmation prompt-for-evaluated-expression prompt-for-expression standard-unparser-method ;replaces unparser/standard-method stream-first stream-rest symbol<? trace-output-port
string-pad-left now truncates from the left instead of the right.
make-graphics-device is now a symbol.
set-working-directory-pathname! changes only the value
for the current REPL.
string-capitalized? string-lower-case? string-upper-case? substring-capitalized? substring-lower-case? substring-upper-case?
M-x dabbrev-expandM-x describe-syntaxM-x rcs-ci-locked-filesM-x rcs-diffM-x rcs-list-locked-filesM-x rcs-logM-x recover-fileM-x show-parameter-listM-x sort-lines and other sorting commandsauto-mode-alistvariable (as in Emacs) Encryption/decryption of files inDiredUndo upgraded to match GNU Emacs 18.57 Buffers grow/shrink with constant amortized time Emacs 19 tags support (multiple tags files, inclusion)
gzip
instead of compress.
This is an abbreviated list of the changes that were incorporated in the (partial) 7.2 release since the 7.1 release.
WM_DELETE_WINDOW protocol) and has some limited support for event
handling. Windows are now closed when they are reclaimed by the garbage
collector.
*default-pathname-defaults* ->namestring ->truename close-port directory-namestring directory-pathname directory-pathname-as-file enough-namestring enough-pathname file-access file-attributes-direct ;same as file-attributes file-modification-time-direct file-modification-time-indirect ;same as file-modification-time file-namestring file-pathname file-readable? host-namestring i/o-port? make-generic-i/o-port make-i/o-port open-i/o-file pathname-simplify pathname-wild? pathname=? port/copy port/input-channel port/operation port/operation-names port/output-channel port/state port? record-copy record-modifier ;replaces record-updater set-port/state!
with-input-from-file and with-output-to-file no longer
close the port when they are exited abnormally.
#!optional and #!rest to be something distinct
from symbols.
"\nnn" octal character escapes, much
like those in C.
canonicalize-input-filename canonicalize-input-pathname canonicalize-output-filename canonicalize-output-pathname canonicalize-overwrite-filename canonicalize-overwrite-pathname home-directory-pathname init-file-truename pathname->absolute-pathname pathname->input-truename pathname->output-truename pathname->overwrite-truename pathname->string pathname-components pathname-default-host pathname-directory-path pathname-directory-string pathname-name-path pathname-name-string pathname-new-host pathname-relative? string->pathname symbol->pathname
pathname-default no longer accepts a host argument.
#f or a list of symbols and strings with
first element either absolute or relative.
unspecific. unspecific now means that the field is not
used by the operating system.
M-x manual-entryM-x outline-modeM-x shell-resync-dirsM-x shell-commandM-x shell-command-on-regionM-x telnetRMAIL summary RMAIL sort REPL mode and asynchronous evaluation Printing commands "run light" for evaluation commands Reading and writing of compressed files (".Z"suffix) Reading and writing of encrypted files (".KY"suffix) Compress/uncompress commands forDiredSupport for X protocols:WM_DELETE_WINDOWandWM_TAKE_FOCUSTime, load, and mail notification in mode line
This release introduces an important new feature: the compiler can generate output in C, which can then be compiled and linked using the usual C development tools. This feature is being used to support architectures, such as the SPARC and IBM RS6000, for which the compiler does not have native-code support.
MIT Scheme systems that have been built using this compiler feature are referred to as C back-end systems. This section provides a brief description of the features and known problems for such systems.
This section describes the general design of C back-end systems.
unsigned data items and addresses fit into the same memory, and
if union-ed, take the same space.
COMPILE_FOR_STATIC_LINKING if it is to be statically linked into
the microcode or collected into a larger dynamically-loadable
library (e.g. edwin or the compiler). If you'd like to put together a
shared library of a large subsystem that you have written, please
contact us for advice on how it can be done.
This section details problems and shortcomings of the system that are specific to the C back-end.
compile-procedure and compile-scode do not work. This
will be fixed for a future release and is not very hard to bypass in
most cases. compile-procedure gives an error.
compile-scode returns something which is not a compiled
expression. cf and compile-bin-file work.
disk-restore, previously loaded
modules are still mapped. In addition, at least in some versions of
unix, the shared object file cannot be deleted while it is loaded, so
recompilation of a module in place will fail if some process has it
already loaded.
fasdump does not work for compiled code. It gives an error.
Only bands can be dumped.
do
{
body
} while (0)
Most of these macros are not really necessary, and the code generator
could just issue the body directly.
(load "foo.scm") in the
interaction buffer and got an error, say a mis-matched parenthesis.
You then switch to the foo.scm buffer, fix the problem and then
try to save the file.
Edwin refuses, saying
Unable to open file "your-path\\foo.scm" because: UnknownWork-around: In the interaction buffer: Quit to top level. Do a
(gc-flip), which forces the file to be closed when the file port
is garbage-collected. Now you will be able to save the file.
MITSCHEME_INF_DIRECTORY sometimes does not work.
The runtime system cannot find the debugging information unless it is on
the `C:' drive.
To test if the debugging information is available, try
(pp pp)If the debugging information is available the
pp procedure
pretty-prints procedures as Scheme code.
If the information cannot be found then it prints the procedure as an
opaque object, similar to this:
#[compiled-procedure 13 ("pp" #x2) #xF #x646BF7]
(edwin-load "dabbrev")in your `edwin.ini' file.
emm386 you may have to put the following in
`config.sys':
device=emm386 noems novcpi
This chapter describes how to run MIT Scheme on a unix system or a PC running DOS, Windows 3.1, or Windows NT. It also describes how you can customize the behavior of MIT Scheme using command-line options and environment variables.
Usually, MIT Scheme is invoked by typing
scheme
at your operating system's command interpreter. (Under Windows 3.1 you must use the Program Manager's Run command, or an icon.) Scheme will load itself, clear the screen, and print something like this:
Scheme saved on Thursday December 2, 1993 at 6:18:35 PM Release 7.3.0 (beta) Microcode 11.146 Runtime 14.166
This information, which can be printed again by evaluating
(identify-world)
tells you the following version information. "Release" is the release number for the entire Scheme system. This number is changed each time a new version of Scheme is released. An "(alpha)" or "(beta)" following the release number indicates that this is a alpha- or beta-test release. "Microcode" is the version number for the part of the system that is written in C. "Runtime" is the version number for the part of the system that is written in Scheme.
Following this there may be additional version numbers for specific
subsystems. `SF' refers to the scode optimization program
sf, `Liar' is the native-code compiler,
`Edwin' is the Emacs-like text editor,
and `Student' is the S&ICP compatibility package.
If the compiler is supported for your machine, you can invoke it by giving Scheme the `-compiler' option:
scheme -compiler
This option causes Scheme to use a larger constant space and heap, and to load the world image containing the compiler.
You can customize your setup by using a variety of tools:
-no-init-file command line option causes Scheme to ignore the
`.scheme.init' file (see section Command-Line Options).
On PC systems these initialization files are called `scheme.ini'
and `edwin.ini' respectively and are searched for in the directory
identified by the HOME environment variable.
One of the important parameters that can be customized is how much memory Scheme uses and how that memory is used. Scheme uses four kinds of memory:
All aspects except the last may be controlled both by command-line
options and by environment variables. MIT Scheme uses a two-space
copying garbage collector for reclaiming storage in the heap. There are
two version of Scheme which handle garbage collection differently.
Ordinary scheme has two heaps, one for each `space'.
bchscheme has one heap and uses a disk file for the other
`space', thus trading memory usage against garbage collection speed.
The total storage required by scheme is:
stack + (constant + 2*heap) + extra
where stack, constant and heap are parameters that may
be selected when `scheme' starts.
For bchscheme, which has only one heap in memory, the equation is
stack + (constant + heap) + extra
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 the 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 your
own bands with the -band option. Dynamic adjustment of the heap
and constant space avoids this problem; now all that is required is that
the total space is sufficient.
The Scheme procedure (print-gc-statistics) shows how much heap
and constant space is available.
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. (At present, any arguments other than these options will generate a warning message when Scheme starts. In the future, there will be an advertised mechanism by which the extra arguments can be handled by user code.)
These are the microcode options:
-band filename
MITSCHEME_BAND, or if that isn't defined, `runtime.com'; in
these cases the library directories are searched, but not the working
directory.
-compiler
-large. If the
-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 MITSCHEME_COMPILER_BAND, if defined, or
`compiler.com'; the library directories are searched to locate this
file. Note that the -compiler option is available only on
machines with compiled-code support.
-edwin
-large. If the
-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 MITSCHEME_EDWIN_BAND, if defined, or
`edwin.com'; the library directories are searched to locate this
file. Note that the -edwin option is available only on machines
with compiled-code support.
-large
MITSCHEME_LARGE_HEAP MITSCHEME_LARGE_CONSTANT MITSCHEME_LARGE_STACKIf this option isn't given, the small sizes are used, specified by the environment variables
MITSCHEME_SMALL_HEAP MITSCHEME_SMALL_CONSTANT MITSCHEME_SMALL_STACKThere 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
-heap,
-constant, and -stack options.
Note: the Scheme procedure (print-gc-statistics) shows how much
heap and constant space is available and in use.
-heap blocks
bchscheme
allocates only one, and uses a disk file for the other.
-constant blocks
-stack blocks
-option-summary
-emacs
-interactive
scheme < /usr/cph/foo.in >& /usr/cph/foo.out &This option only makes sense under unix.
-nocore
-library path
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 `/usr/local/lib/mit-scheme'. On PCs, the elements
of the list are separated by semicolons, and the default value is
`c:\scheme'.
-utabmd filename
-utab filename
MITSCHEME_UTABMD_FILE, or if that isn't defined,
`utabmd.bin'; in these cases the library directories are searched,
but not the working directory.
-utab is an alternate name for the -utabmd option. At
most one of these options may be given.
-fasl filename
-band option. This option is useful only for
maintainance and development of the MIT Scheme runtime system.
The following options are runtime options. They are processed after the microcode options and after the runtime, Edwin or some other band is loaded.
-no-init-file
-no-suspend-file
-no-suspend-file option is given, Scheme will not write a
`scheme_suspend' file under any circumstances.
-eval
user-initial-environment.
Unless explicitly handled, errors during evaluation are silently ignored.
-load
user-initial-environment using the default syntax table.
Unless explicitly handled, errors during loading are silently ignored.
In addition to the above, bchscheme recognises the following
command line options, all of which specify parameters affecting how
bchscheme uses disk storage to do garbage collection:
-gc-directory directory
MITSCHEME_GC_DIRECTORY is used instead, and
if that is not defined, `/tmp' is used.
-gc-end-position number
-gc-file at which this
invocation of scheme can write. If the option is not given, the value
of environment variable MITSCHEME_GC_END_POSITION is used
instead, and if that is not defined, it is computed from the start
position (as provided with -gc-start-position) and the heap size. The
area of the file used (and locked if possible) is the region between
-gc-start-position and -gc-end-position.
-gc-file filename
-gcfile filename
MITSCHEME_GC_FILE is used, and if this is not defined, a unique
filename is generated in the directory specified with
-gc-directory.
-gcfile is an alias for -gc-file. At most one of these
options should be specified.
-gc-keep
-gc-start-position number
-gc-file at which this
invocation of scheme can write. If the option is not given, the value
of environment variable MITSCHEME_GC_START_POSITION is used
instead, and if that is not defined, 0 is used, meaning the beginning of
the file. The area of the file used (and locked if possible) is the
region between -gc-start-position and -gc-end-position.
-gc-window-size blocks
MITSCHEME_GC_WINDOW_SIZE is used instead, and if that is
not defined, the value 16 is used.
The following command line options are only used by an experimental
version of bchscheme that uses Unix System V-style shared memory,
and only then if the gcdrone program is installed in the lib
directory.
-gc-drone program
bchscheme. If the option is not given, the value of
environment variable MITSCHEME_GC_DRONE is used instead, and if
that is not defined, `gcdrone' is used.
-gc-read-overlap N
bchscheme. If the option is not given, the value of
environment variable MITSCHEME_GC_READ_OVERLAP is used instead,
and if that is not defined, 0 is used, disabling overlapped reads.
-gc-write-overlap N
bchscheme. If the option is not given, the value of
environment variable MITSCHEME_GC_WRITE_OVERLAP is used instead,
and if that is not defined, 0 is used, disabling overlapped writes.
There are many environment variables that Scheme (and Edwin, etc.) look
for. Environment variables that affect the microcode must be defined
before you start Scheme, but others can be defined or overwritten within
Scheme by using the set-environment-variable! procedure, e.g.
(set-environment-variable! "EDWIN_FOREGROUND" "32")
The rest of this section is a summary of the environment variables that are specific to MIT Scheme. The environment variables are organised according to the parts of MIT Scheme that they affect.
These environment variables are referred to by the microcode (the executable C programs called `scheme' and `bchscheme').
MITSCHEME_BAND (default: `runtime.com' on the library path)
-band,
-compiler, or -edwin.
MITSCHEME_COMPILER_BAND (default: `compiler.com' on the library path)
-compiler option is given.
Overridden by -band.
MITSCHEME_EDWIN_BAND (default: `edwin.com' on the library path)
-edwin option is given.
Overridden by -band.
MITSCHEME_LARGE_CONSTANT (default: `1000')
-large,
-compiler, or -edwin options are given. Overridden by
-constant. Note: default is somewhat larger on RISC machines.
MITSCHEME_LARGE_HEAP (default: `1000')
-large,
-compiler, or -edwin options are given. Overridden by
-heap.
MITSCHEME_LARGE_STACK (default: `100')
-large,
-compiler, or -edwin options are given. Overridden by
-stack.
MITSCHEME_LIBRARY_PATH
MITSCHEME_INF_DIRECTORY
MITSCHEME_SMALL_CONSTANT (default: `400')
-constant, -large,
-compiler, or -edwin. Note: default is somewhat larger on
RISC machines.
MITSCHEME_SMALL_HEAP (default: `250')
-heap, -large, -compiler, or
-edwin.
MITSCHEME_SMALL_STACK (default: `100')
-stack, -large, -compiler, or
-edwin.
MITSCHEME_UTABMD_FILE (default: `utabmd.bin' in the library path)
-utabmd
and -utab. It is only necessary when re-building
`runtime.com'.
These environment variables are referred to by `bchscheme' (not by `scheme').
MITSCHEME_GC_DIRECTORY (default: `/tmp')
-gc-directory.
MITSCHEME_GC_END_POSITION (default: start-position + heap-size)
-gc-end-position.
MITSCHEME_GC_FILE (default: `GCXXXXXX')
-gc-file.
MITSCHEME_GC_START_POSITION (default: 0)
-gc-start-position.
MITSCHEME_GC_WINDOW_SIZE (default: 16)
-gc-window-size.
The following environment variables are only used by an experimental
version of Bchscheme that uses Unix System V-style shared memory, and
only then if the gcdrone program is installed:
MITSCHEME_GC_DRONE (default: `gcdrone')
-gc-drone.
MITSCHEME_GC_READ_OVERLAP (default: 0)
-gc-read-overlap.
MITSCHEME_GC_WRITE_OVERLAP (default: 0)
-gc-write-overlap.
These environment variables are referred to by the Windows, Windows NT, and DOS versions of MIT Scheme.
MITSCHEME_DPMI_EXT_KBD (default: `false')
MITSCHEME_X32_EXT_KBD (default: `false')
MITSCHEME_TRAP_ALT_TAB (default: `false')
MITSCHEME_TRAP_ALT_ESCAPE (default: `false')
MITSCHEME_GEOMETRY (default: `-1,-1,-1,-1')
MITSCHEME_FOREGROUND (default: according to desktop color scheme)
0xff0000 for blue.
MITSCHEME_BACKGROUND (default: according to desktop color scheme)
MITSCHEME_FOREGROUND.
These environment variables are referred to by the runtime system.
HOME
TEMP, TMP
TEMP is given preference
to TMP.
These environment variables are referred to by Edwin.
EDWIN_BINARY_DIRECTORY (default: `edwin/autoload' on the library path)
EDWIN_INFO_DIRECTORY (default: `edwin/info' on the library path)
EDWIN_ETC_DIRECTORY (default: `edwin/etc' on the library path)
EDWIN_FOREGROUND (default: none (white))
EDWIN_BACKGROUND (default: none (black))
TERM
LINES (default: auto-sense)
MITSCHEME_LINES (default: auto-sense or 25)
COLUMNS (default: auto-sense)
MITSCHEME_COLUMNS (default: auto-sense, or 80)
There are two distinct versions of MIT Scheme that run on IBM `compatible' PCs: the DOS version is a character-mode only implementation, which can also run under Windows 3.1 as a DOS application. The Windows version runs as a graphics-based application under Windows 3.1 or Windows NT. The DOS version does not run under Windows NT.
Under Windows 3.1, Scheme must be run from the Program Manager or the File Manager. Scheme cannot be run from the command line, because only DOS programs can be run from the command line. (This is the case even with WXSERVER as it appears not to work with win32s-based programs). Windows NT overcomes this restriction, but it is still useful to know how to run Scheme from the Program Manager.
Once an icon is set up to run Scheme with some particular command line options, Scheme is run by double-clicking that icon. The rest of this section gives some tips on how to set up icons in the Program Manager that run Scheme. If you are unfamiliar with this concept you should read about it under the help topic of the Program Manager.
Under Windows NT program manager groups can be common or personal. When setting up icons in a common group it is important to make the icons independent of the vagaries of the environment of the user who is running them. It is often worthwhile doing this under Windows 3.1 and for personal groups too:
scheme.exe and bchscheme.exe
in the icon Command line if these executables are not in a
directory on the default PATH.
%HOMEPATH%
-eval (edit)at the end of the command line.
There are two ways you can leave Scheme. The first is to evaluate
(exit)
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 way to leave Scheme is to suspend it; when this is done you may later restart where you left off. Unfortunately this is not possible in all operating systems -- currently it works only on unix versions that support job control (i.e. all of the unix versions for which we distribute Scheme), but not on PCs.
Scheme is suspended by evaluating
(quit)
If your system supports suspension, this will cause Scheme to stop, and
you will be returned to the operating system's command interpreter.
Scheme remains stopped, and can be continued using the job-control
commands of your command interpreter. If your system doesn't support
suspension, this procedure does nothing. (Calling the quit
procedure is analogous to typing Control-Z, but it allows Scheme
to respond by typing a prompt when it is unsuspended.)
When you first start up Scheme from the command line (i.e not under Edwin), you will be typing at a program called the Read-Eval-Print Loop (abbreviated 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 RET). Scheme evaluates the expression, prints the result, and gives you another prompt.
The REPL prompt normally has the form
1 ]=>
The `1' in the prompt is a 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 f o o RET after starting Scheme:
;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>
In this case, the level number has been incremented to `2', which
indicates that a new REPL has been started (also the prompt string
has been changed to remind you that the REPL was started because of
an error). The `2' means that this new REPL is "over" the
old one. The original REPL still exists, and is waiting for you to
return to it, for example, by entering (restart 1). Furthermore,
if an error occurs while you are in this REPL, yet another
REPL will be started, and the level number will be increased to
`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 REPL and back to the top level REPL is to use the C-g interrupt. This is a single-keystroke command executed by holding down the CTRL key and pressing the G key. C-g always terminates whatever is running and returns you to the top level REPL immediately.
Note: The appearance of the `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 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.
Scheme has two interrupt keys under unix: C-g and C-c. Other systems, like the PC, may have more than two. The PC version has C-b, C-x, and C-u as well as C-g and C-c. The C-g key stops any Scheme evaluation that is running and returns you to the top level REPL. C-c prompts you for another character and performs some action based on that character. It is not necessary to type RET after C-g or C-c, nor is it needed after the character that C-c will ask you for.
Here are the more common options for C-c.
(exit) at the REPL, except that it works
even if Scheme is running an evaluation, and does not request
confirmation.
(quit) at the REPL, except that it works
even if Scheme is running an evaluation.
(cmdl-interrupt/abort-top-level)The options C-c C-g and C-c g, supplied for compatibility with older implementations, are equivalent to C-c C-c.
(cmdl-interrupt/abort-nearest)The option C-c x, supplied for compatibility with older implementations, is equivalent to C-c C-x. On the PC version C-x is equivalent to C-c C-x.
(cmdl-interrupt/abort-previous)The option C-c u, supplied for compatibility with older implementations, is equivalent to C-c C-u. On the PC version C-u is equivalent to C-c C-u.
(proceed)in that REPL at any time. The option C-c b, supplied for compatibility with older implementations, is equivalent to C-c C-b. On the PC version C-b is equivalent to C-c C-b.
Another way of exiting a REPL is to use the restart
procedure:
;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>
If the k argument is given, it must be a positive integer index
into the list (in this example it must be between one and three
inclusive). The integer k selects an item from the list and
invokes it. If k is not given, restart prints the list and
prompts for the integer index:
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:
The simplest restart methods just perform their actions. For example:
2 error> (restart 1) ;Abort! 1 ]=>
Other methods will prompt for more input before continuing:
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 ]=>
Every REPL has a 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
user-initial-environment. There are a number of other
environments in the system, for example
system-global-environment, where the runtime system's bindings
are stored.
You can get the current REPL environment by evaluating
(nearest-repl/environment)
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
(procedure-environment procedure)
Your programs create new environments whenever a procedure is called.
Here is the procedure that changes the REPL's environment:
ge stands for "Goto Environment"). 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.
if, lambda). If you write macros, often you will want to
make your own syntax table, in which case it is useful to be able to
make that syntax table be the current one. gst allows you to do
that.
This chapter is out of date and currently under revision.
This chapter is adapted from Don't Panic: A 6.001 User's Guide to the Chipmunk System, by Arthur A. Gleckler.
Even computer software that has been planned carefully and written well may not always work correctly. Mysterious creatures called 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 debugging.
It is impossible to prove the correctness of any non-trivial program; hence the Cynic's First Law of Debugging:
Programs don't become more reliable as they are debugged; the bugs just get harder to find.
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 breakpoints, places where the program will pause for inspection.
Many bugs are detected when programs try to do something which is
impossible, like adding a number to a symbol, or using a variable which
does not exist; this type of mistake is called an error.
Whenever an error occurs, Scheme prints an error message and starts a
new REPL. For example, using a nonexistent variable foo will
cause Scheme to respond
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>
Sometimes, a bug will never cause an error, but will still cause the program to operate incorrectly. For instance,
(prime? 7) => #f
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:
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.
Understanding the concepts of reduction and subproblem is essential to good use of the debugging tools. The Scheme interpreter evaluates an expression by 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 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 (+ 5 6) and (+ 7 9) are subproblems of
the following combination:
(* (+ 5 6) (+ 7 9))
If (prime? n) is true, then (cons 'prime n) is a reduction
for the following expression:
(if (prime? n)
(cons 'prime n)
(cons 'not-prime n))
This is because the entire subproblem of the if expression can
be reduced to the problem (cons 'prime n), once we know that
(prime? n) is true; the (cons 'not-prime n) can be
ignored, because it will never be needed. On the other hand, if
(prime? n) were false, then (cons 'not-prime n) would be
the reduction for the if expression.
The subproblem level is a number representing how far back in the
history of the current computation a particular evaluation is. Consider
factorial:
(define (factorial n)
(if (< n 2)
1
(* n (factorial (- n 1)))))
If we stop factorial in the middle of evaluating (- n 1),
the (- n 1) is at subproblem level 0. Following the history of
the computation "upwards," (factorial (- n 1)) is at subproblem
level 1, and (* n (factorial (- n 1))) is at subproblem level 2.
These expressions all have reduction number 0. Continuing
upwards, the 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 debug.
There are three debuggers available with MIT Scheme. Two of them require and run under Edwin, and are described in that section of this document (see section Edwin). The third is command oriented, does not require Edwin, and is described here.
The debugger, called 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 continuation
browser.
Here is the transcript of a typical Scheme session, showing a user
evaluating the expression (fib 10), Scheme responding with an
unbound variable error for the variable fob, and the user
starting the debugger:
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>
This tells us that the error occurred while trying to evaluate the
expression fob while running (fib 10). It also tells us
this is subproblem level 0, the first of 8 subproblems that are
available for us to examine. The expression shown is marked "(from
stack)", which tells us that this expression was reconstructed from the
interpreter's internal data structures. Another source of information
is the 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.
An important step in debugging is to locate the piece of code from which the error is signalled. The Scheme debugger contains a history examiner and an environment examiner to aid the user in locating a bug.
proceed. Sample
usage:
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> (proceed)
bar
;Value: done
where enters the environment examination system.
This allows environments and variable bindings to be examined and
modified. where accepts one letter commands. The commands can
be found by typing ? to the `where>' prompt. The optional
argument, obj, is an object with an environment associated with
it: an environment, a procedure, or a promise. If obj is omitted,
the environment examined is the read-eval-print environment from which
where was called (or an error or breakpoint environment if called
from the debugger). If a compound procedure is supplied, where
lets the user examine the environment of definition of the procedure.
This is useful for debugging procedure arguments and values.
Giving advice to procedures is a powerful debugging technique.
trace and break are useful examples of advice-giving
procedures.
Note that the advice system only works for interpreted procedures.
[Entering #[compound-procedure 1 foo]
Args: val1
val2
...]
where val1, val2 etc. are the evaluated arguments supplied to the procedure.
trace-both is the same as calling both trace-entry and
trace-exit on proc.
trace is the same as trace-both.
untrace-entry stops tracing the entry of proc.
If proc is not given, the
default is to stop tracing the entry of all entry-traced procedures.
trace-entry with the additional effect that a breakpoint is
entered when procedure proc is invoked. Both proc and its
arguments can be accessed by calling the procedures *proc* and
*args*, respectively.
Use restart or proceed to continue from a breakpoint.
trace-exit, except that a breakpoint is entered just prior
to leaving the procedure proc. Proc, its arguments, and the
result can be accessed by calling the procedures *proc*,
*args*, and *result*, respectively.
Use restart or proceed to continue from a breakpoint.
break-entry and break-exit combined.
trace-entry and
break-entry are examples of entry-advising procedures.
advise-entry gives advice to proc. When proc
is invoked, advice is passed three arguments: proc, a list
of proc's argument values, and the current environment.
trace-exit and
break-exit are examples of exit-advising procedures.
Advice is a procedure that should accept four arguments:
proc, its argument values, the result computed by proc, and
the current environment. Advice is responsible for returning a
value on behalf of proc. That is, the value returned by
advice is the value returned by the advised procedure.
unadvise-entry and unadvise-exit. If proc is not
given, the default is all advised procedures.
*proc* is a procedure which returns as its value the "broken"
procedure. It is used only at a breakpoint set by the procedures
break-exit and break-entry or procedures defined in terms
of these procedures (like break-both and break).
*args* is a procedure which returns as its value a list of the
arguments supplied to the "broken" procedure. It is used only at a
breakpoint set by the procedures break-exit and
break-entry or procedures defined in terms of these procedures
(like break-both and break).
*result* is a procedure which returns as its value the result that
was about to be returned by the "broken" procedure. It is used only at
a breakpoint set by the procedure break-exit or procedures
defined in terms of this procedure (like break-both and
break).
To load files of Scheme code, use the procedure load:
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 "scm", and files of binary
SCode have pathname type "bin". Native-code binaries have
pathname type "com". (See the description of
pathname-type in the reference manual.)
load-noisily? is set to #t, 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.)
load/default-types is a list of associations that maps
pathname types (strings) to loader procedures. 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:
"com" "so" "sl" "bin" "scm"
This means that, for example, (load "foo") will try to load
`foo.com' first, and `foo.scm' only after looking for and
failing to find the other pathname types.
All pathnames are interpreted relative to a working directory, which is
initialized when Scheme is started. The working directory can be
obtained from the procedure pwd or modified by the procedure
cd; see the reference manual for details. Files may be loaded
when Scheme first starts; see the -load command line option for
details.
A world image is a file that contains a complete Scheme system,
perhaps additionally including user application code. Scheme provides
two methods for saving and restoring world images. The first method
writes a file containing all of the Scheme code in the world, which is
called a band. The file `runtime.com' that is loaded by the
microcode is just such a band.
To make your own band, use the procedure
disk-save.
#t
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 REPL.
#f
#t, except that the runtime system will not perform
normal restart initializations; in particular, it will not load your
init file.
To restore a saved band, give the -band option when starting
Scheme. Alternatively, evaluate (disk-restore filename)
from a running Scheme, which will destroy the current world, replacing
it with the saved world. The argument to disk-restore may be
omitted, in which case it defaults to the filename from which the
current world was last restored.
Note: with the C back-end, disk-save is not very useful. The
reason is that compiled procedures are compiled C code that has been
dynamically linked in, and disk-save does not save any C
procedures. If you need to build a band for a C back-end system, please
contact us. Your system is a C back-end system if the following
expression does not evaluate to #f:
(system-library-directory-pathname "shared")
Note: when restoring a saved band, the Scheme executable must be
configured with a large enough constant space and heap to hold the
band's contents. If you attempt to restore a band using the
-band option, and the band is too large, Scheme will write an
error message that tells you the appropriate command-line options needed
to load that band. If you attempt restore a too-large band using
disk-restore, Scheme will signal an error, but will not provide
the configuration information. In general, the configuration that was
used to save a band is sufficiently large to restore it.
Another method for saving the world is the dump-world procedure,
which accepts the same arguments as disk-save and works in much
the same way. However, rather than dumping a band, dump-world
saves an executable image, which is started just like any other program.
This has the advantage of being considerably faster to start on some
systems, but the image file is typically much larger than the
corresponding band. However, dump-world is only supported for a
few operating systems, and is not built into the distributed executable
files -- if you wish to use dump-world, you must build your own
executable file from the source code.
Note that dump-world is unlikely to work with this release as MIT
Scheme now uses shared libraries.
This section describes procedures that control garbage collection. See see section Customizing Scheme for a discussion of how MIT Scheme uses memory.
Safety-margin determines the number of words of storage available for system tasks in-between detecting the need for a garbage collection and entering the garbage collector proper. An example of such a system task is changing the run-light to show `gc' when scheme is running under Emacs.
#F, the user is not notified, otherwise the user is
notified. The default is no notification.
The notification appears as a single line like the following, showing how many garbage collections have occured, the time taken to perform the garbage collection and the free storage remaining (in words) after collection.
GC 5: took: 0.50 (8%) CPU time, 0.70 (2%) real time; free: 364346
To operate comfortably, the amount of free storage after garbage collection should be a substantial proportion of the heap size. If the percentage CPU time is consistently high (over 20%), you should consider running with a larger heap. A rough rule of thumb to halve the GC overhead is to take the amount of free storage, divide by 1000, and add this figure to the current value used for the `-heap' command line option. Unfortunately there is no way to adjust the heap size without restarting Scheme.
Note: the procedures described in this section are only available in the
`compiler.com' world image. Furthermore, cf is only
available on machines that support native-code compilation.
(cf "foo")
cf compiles the file `foo.scm', producing the file
`foo.com' (incidentally it will also produce `foo.bin',
`foo.bci', and possibly `foo.ext'). If you later evaluate
(load "foo")
`foo.com' will be loaded rather than `foo.scm'.
If destination is given, it says where the output files should go. If this argument is a directory, they go in that directory, e.g.:
(cf "foo" "../bar/")
will take `foo.scm' and generate the file `../bar/foo.com'. If destination is not a directory, it is the root name of the output:
(cf "foo" "bar")
takes `foo.scm' and generates `bar.com'.
About the `.bci' files: these files contain the debugging
information that Scheme uses when you call debug to examine
compiled code. When you load a `.com' file, Scheme remembers where
it was loaded from, and when the debugger (or pp) looks at the
compiled code from that file, it attempts to find the `.bci' file
in the same directory from which the `.com' file was loaded. Thus
it is a good idea to leave these files together.
`.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 behaviour: debugging information is cached in memory, and uncompressed versions of `.bci' files are kept around. The default behavior is that a temporary file is created and the `.bci' file is uncompressed into it. The temporary file is kept around for a while afterwards, and during that time if the uncompressed `.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 `.bci'
file each time it is referenced, and the other uncompresses the `.bci'
file and writes it back out as a `.bif' file (the old default).
The `.bif' file remains after Scheme exits.
The time interval and the behavior are controlled by variables. (These
variables are not in the global environment; perhaps they should be.
They are in the (runtime compiler-info) package environment.)
#f
automatic
#t
#f.
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 sf is just to say:
(sf filename)
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
"bin". If you do not specify a pathname type on the input file,
"scm" is assumed.
Like load, the first argument to sf may be a list of
filenames rather than a single filename.
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.
Several declarations can be added to your programs to help cf and
sf make them more efficient.
Normally, all files have a line
(declare (usual-integrations))
near their beginning, which tells the compiler that free variables whose
names are defined in 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 car,
cdr, and cons, you should indicate it in the declaration:
(declare (usual-integrations car cdr cons))
You can obtain an alphabetically-sorted list of the names that the
usual-integrations declaration affects by evaluating the
following expression:
(eval '(sort (append usual-integrations/constant-names
usual-integrations/expansion-names)
(lambda (x y)
(string<=? (symbol->string x)
(symbol->string y))))
(->environment '(scode-optimizer)))
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:
integrate declaration, except that it only
substitutes for references that appear in the operator position of a
combination. All other references are ignored.
If 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 `/usr/cph/foo.scm', then the compiler looks for a file called `/usr/cph/filename.ext'.
Note: When the compiler finds top-level integrations, it collects them
and outputs them into an auxiliary file with extension `.ext'.
This `.ext' file is what the integrate-external declaration
refers to.
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,
define-integrable, which is like define but performs the
appropriate declarations. For example:
(define-integrable (foo-bar foo bar) (vector-ref (vector-ref foo bar) 3))
Here is how you do the same thing without this special form: there
should be an integrate-operator declaration for the procedure's
name, and (internal to the procedure's definition) an integrate
declaration for each of the procedure's parameters, like this:
(declare (integrate-operator foo-bar))
(define foo-bar
(lambda (foo bar)
(declare (integrate foo bar))
(vector-ref (vector-ref foo bar) 3)))
The reason for this complication is as follows: the
integrate-operator declaration finds all the references to
foo-bar and replaces them with the lambda expression from the
definition. Then, the integrate declarations take effect because
the combination in which the reference to foo-bar occurred
supplies code which is substituted throughout the body of the procedure
definition. For example:
(foo-bar (car baz) (cdr baz))
First use the integrate-operator declaration:
((lambda (foo bar) (declare (integrate foo bar)) (vector-ref (vector-ref foo bar) 3)) (car baz) (cdr baz))
Next use the internal integrate declaration:
((lambda (foo bar) (vector-ref (vector-ref (car baz) (cdr baz)) 3)) (car baz) (cdr baz))
Next notice that the variables foo and bar are not used,
and eliminate them:
((lambda () (vector-ref (vector-ref (car baz) (cdr baz)) 3)))
Finally, remove the ((lambda () ...)) to produce
(vector-ref (vector-ref (car baz) (cdr baz)) 3)
Useful tip: to see the effect of integration declarations (and of macros) on a source file, pretty-print the `.bin' file like this (be prepared for a lot of output).
(sf "foo.scm") (pp (fasload "foo.bin"))
The 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:
Declaration:
(declare (replace-operator (map (2 map-2) (3 map-3))))
Replacements:
(map f x y z) ==> (map f x y z) (map f x y) ==> (map-3 f x y) (map f x) ==> (map-2 f x) (map f) ==> (map f) (map) ==> (map)
Presumably map-2 and map-3 are efficient versions of
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 map procedure, which is less efficient because
it must handle a variable number of arguments.
The syntax of this declaration is
(replace-operator
(name
(nargs1 value1)
(nargs2 value2)
...))
where
any, else or otherwise.
'constant
variable
(primitive primitive-name [arity])
(global var)
The meanings of these fields are:
any, else or otherwise, then the operation is
replaced with a call to the corresponding valueN.
Only one of the nargsN may be of this form.
any, else or otherwise, then the operation is not
replaced.
The reduce-operator declaration is provided to inform the
compiler that certain names are n-ary versions of binary operators.
Here are some examples:
Declaration:
(declare (reduce-operator (cons* cons)))
Replacements:
(cons* x y z w) ==> (cons x (cons y (cons z w))), (cons* x y) ==> (cons x y) (cons* x) ==> x (cons*) error--> too few arguments
Declaration:
(declare (reduce-operator (list cons (null-value '() any))))
Replacements:
(list x y z w) ==> (cons x (cons y (cons z (cons w '())))) (list x y) ==> (cons x (cons y '())) (list x) ==> (cons x '()) (list) ==> '()
Declaration:
(declare (reduce-operator (- %- (null-value 0 single) (group left))))
Replacements:
(- x y z w) ==> (%- (%- (%- x y) z) w) (- x y) ==> (%- x y) (- x) ==> (%- 0 x) (-) ==> 0
Declaration:
(declare (reduce-operator (+ %+ (null-value 0 none) (group right))))
Replacements:
(+ x y z w) ==> (%+ x (%+ y (%+ z w))) (+ x y) ==> (%+ x y) (+ x) ==> x (+) ==> 0
Note: This declaration does not cause an appropriate definition of
%+ (in the last example) to appear in your code. It merely
informs the compiler that certain optimizations can be performed on
calls to + by replacing them with calls to %+. You should
provide a definition of %+ as well, although it is not required.
Declaration:
(declare (reduce-operator (apply (primitive cons)
(group right)
(wrapper (global apply) 1))))
Replacements:
(apply f x y z w) ==> ((access apply ()) f (cons x (cons y (cons z w)))) (apply f x y) ==> ((access apply ()) f (cons x y)) (apply f x) ==> (apply f x) (apply f) ==> (apply f) (apply) ==> (apply)
(reduce-operator
(name
binop
[(group ordering)]
[(null-value value null-option)]
[(singleton unop)]
[(wrapper wrap [n])]
[(maximum m)]
))
where
'constant
variable
(primitive primitive-name [arity])
(global var)
always, any, one,
single, none, or empty.
left, right, or
associative.
The meaning of these fields is:
group option specifies whether name associates to the
right or left.
null-value option specifies a value to use in the following
cases:
none
empty
one
single
any
always
singleton option specifies a function, unop, to be
invoked on the single argument left. This option supersedes the
null-value option, which can only take the value none.
wrapper option specifies a function, wrap, to be
invoked on the result of the outermost call to binop after the
expansion.
If 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.
There is an interface library, called 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 `xscheme.el' that comes with MIT Scheme, as it is
guaranteed to be correct for your version of Scheme.
To invoke Scheme from Emacs, use M-x run-scheme, which is defined
when either of the libraries `scheme' or `xscheme' is loaded.
You may give run-scheme a prefix argument, in which case it will
allow you to edit the command line that is used to invoke Scheme.
Do not remove the -emacs option!
Scheme will be started up as a subprocess in a buffer called
*scheme*. This buffer will be in scheme-interaction-mode
and all output from the Scheme process will go there. The mode line for
the *scheme* buffer will have this form:
--**-*scheme*: 1 [Evaluator] (Scheme Interaction: input)------
The first field, showing `1' in this example, is the level number.
The second field, showing `[Evaluator]' in this example, describes the type of REPL that is running. Other values include:
[Debugger] [Where]
The mode after `Scheme Interaction' is one of:
When xscheme is loaded, scheme-mode is extended to include
commands for evaluating expressions (do C-h m in any
scheme-mode buffer for the most up-to-date information):
xscheme-send-buffer).
xscheme-send-definition). This
is also bound to ESC C-x.
xscheme-send-region).
xscheme-send-previous-expression). This is also bound to
ESC RET.
*scheme* buffer and places you at its end
(xscheme-select-process-buffer).
xscheme-yank-previous-send). This works only in the
*scheme* buffer.
The following commands provide interrupt capability:
xscheme-send-control-g-interrupt).
xscheme-send-control-x-interrupt).
xscheme-send-control-u-interrupt).
xscheme-send-breakpoint-interrupt).
(proceed) (xscheme-send-proceed).
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.
To use Edwin, start Scheme with a world image containing Edwin (for
example by giving the -edwin command-line option), then call the
procedure edit:
create-editor with no arguments).
Otherwise, the previously-initialized editor is reentered.
This procedure is sometimes evaluated from the command line to start Scheme with Edwin running:
scheme -edwin -eval (edit)
inhibit-editor-init-file? is true, however,
your init file will not be loaded even if it exists. By default, this
variable is false.
create-editor is normally invoked automatically by edit.
If no args are given, the value of create-editor-args is
used instead. In other words, the following are equivalent:
(create-editor) (apply create-editor create-editor-args)
On the other hand, if args are given, they are used to update
create-editor-args, making the following equivalent:
(apply create-editor args) (begin (set! create-editor-args args) (create-editor))
(console)
(x)
DISPLAY environment variable to have been set to the appropriate
value before Scheme was started.
(x geometry)
(x) except that geometry specifies the
window's geometry in the usual way. Geometry must be a character
string whose contents is an X geometry specification.
(#f)
Once Edwin has been entered, it can be exited in the following ways:
suspend-edwin). The call to the
procedure edit that entered Edwin returns normally. A subsequent
call to edit will resume Edwin where it was stopped.
save-buffers-kill-edwin). This is like the suspend-edwin
command, except that a subsequent call to edit will reinitialize
the editor.
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 C-x C-z command of GNU Emacs.
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 C-x C-c command of GNU Emacs.
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
M-x recover-file to recover the auto-saved version. The
auto-save files are named so: under unix, `foo.scm' will be saved
as `#foo.scm#'; on PCs it will be saved as `foo.s00', a backup
file with version `00' (which is never used as an actual version).
The following Scheme procedures are useful for recovering from bugs in Edwin's implementation. All of them are designed for use when Edwin is 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.
edit is called. If you encounter a fatal bug in Edwin, a good
way to recover is to first call save-editor-files, and then to
call reset-editor. That should completely reset the editor to
its initial state.
This section documents all known differences between Edwin 3.82 and Emacs 18.57. A reference to a "documented" feature of Emacs means that the feature is documented in the GNU Emacs version 18 manual.
These are differences in design, unlikely to be `fixed'.
car or call-with-current-continuation.
comment-indent-hook is defined differently. In Emacs, it is
called with no arguments and with point at the beginning of the comment;
in Edwin, it is called with a single argument, the mark at the beginning
of the comment, and with point undefined.
Scheme and Scheme Interaction modes, M-TAB completes
the Scheme variable name. Completion is environment-dependent, so a
prefix may complete differently (or not at all) in two different buffers
with different associated environments.
DOS Note: Since Alt+TAB is an MS Windows hot key, you can get the
same effect (without disabling it) by typing Alt+Ctrl+I.
text-mode-hook is an event distributor rather than a
procedure of no arguments.
Deficiencies are shortcomings of Edwin that are likely to be fixed.
n view-emacs-news c-c describe-copying c-d describe-distribution c-w describe-warranty
v view this file. B byte-compile this file. M change this file's permissions. G change this file's group. O change this file's owner. C compress this file. U uncompress this file.
k mark file for copying y copy marked files
The following documented subsystems are implemented by Emacs but not by Edwin.
DOS Note:
Some modes are available under Unix, but are not included in the standard DOS edwin binary to reduce its size or because they don't work under DOS:
Missing Command or mode Reason
----------------------- ------
* dabbrev reduce size
compile needs subprocess support
shell needs subprocess support
+ there is a DOS replacement
techinfo specific to MIT & Unix
telnet needs subprocess support
* midas mode (assembly language editing) reduce size
* pascal mode reduce size
texinfo reduce size
man specific to unix
print does not work yet
* run-notifier reduce size
* outline mode reduce size
* info reduce size
rcs needs subprocess support
sendmail needs subprocess support
malias useless without sendmail
* occur (and list-matching-lines) reduce size
rmail needs subprocess support
+ specific to Unix ?
rmailsrt useless without rmail
Many of the missing modes and commands (compile, shell, rcs, sendmail) require subprocess support. They should be easy to bring up if subprocesses become available, however the code (or even the concept) may be Unix specific. There is a pseudo-shell mode for DOS.
Many of the subsystems listed above have not been tried under DOS.
The ones that are known to work are marked with an asterisk (*),
although for some of them variables have to be set appropriately
before use (e.g. info-directory for info).
These commands are implemented by Emacs but not by Edwin. The commands marked with an asterisk are implemented by the unix version of Edwin but not by the PC version. Some of the asterisked comands can work in the PC version but the code to implement them is not loaded in order to save space; others are unix-specific and are not implemented on the PC.
abbrev-mode abbrev-prefix-mark add-change-log-entry add-change-log-entry-other-window add-global-abbrev add-mode-abbrev add-name-to-file append-to-buffer byte-compile-file byte-recompile-directory cancel-debug-on-entry * compile convert-mocklisp-buffer copy-to-buffer debug-on-entry define-abbrevs * delete-matching-lines * delete-non-matching-lines describe-copying describe-distribution describe-no-warranty describe-syntax disable-command disassemble display-time (run-notifier is similar) dissociated-press doctor edit-abbrevs edit-abbrevs-redefine edit-options edit-picture edit-tab-stops edit-tab-stops-note-changes edt-emulation-on emacs-lisp-mode emacs-version enable-command expand-abbrev expand-region-abbrevs flush-lines fortran-mode global-set-key (set-key is similar) grep hanoi indent-c-exp c-indent-expression insert-abbrevs insert-kbd-macro write-kbd-macro insert-parentheses inverse-add-global-abbrev inverse-add-mode-abbrev * keep-lines kill-all-abbrevs latex-mode Note: BAL has one lisp-complete-symbol (scheme-complete-variable is similar) lisp-interaction-mode (inferior-repl-mode is similar) lisp-mode lisp-send-defun list-abbrevs list-command-history list-options list-tags local-set-key * lpr-buffer * lpr-region make-symbolic-link make-variable-buffer-local * manual-entry modify-syntax-entry move-past-close-and-reindent next-error next-file nroff-mode * occur * occur-mode-goto-occurrence open-dribble-file open-termscript overwrite-mode plain-tex-mode prepend-to-buffer * print-buffer * print-region read-abbrev-file recover-file run-lisp save-buffers-kill-emacs save-buffers-kill-scheme set-gosmacs-bindings * shell-command * shell-command-on-region spell-buffer spell-region spell-string spell-word suspend-emacs suspend-scheme tab-to-tab-stop tags-apropos tex-mode top-level unexpand-abbrev vi-mode view-buffer view-emacs-news view-file vip-mode write-abbrev-file yow zap-to-char
These documented variables are implemented by Emacs but not Edwin. The variables marked with an asterisk are implemented by the unix version of Edwin, but not by the PC version.
abbrev-all-caps
abbrev-file-name
blink-matching-paren
blink-matching-paren-distance
buffer-read-only
c-tab-always-indent
comment-start-skip
* compile-command
completion-ignore-case (not documented)
ctl-arrow
debug-on-error debug-on-editor-error
debug-on-internal-error
debug-on-evaluation-error
are similar, but more specific
debug-on-quit
default-directory
default-major-mode
echo-keystrokes
initial-major-mode Scheme variable initial-buffer-mode
insert-default-directory
inverse-video
kill-ring-max
load-path
* lpr-switches
major-mode
mark-ring
mark-ring-max mark-ring-maximum
meta-flag
no-redraw-on-recenter
save-abbrevs
selective-display-ellipses
* shell-file-name
tab-stop-list
tags-file-name (tags-table-pathname is similar)
track-eol
visible-bell
These documented variables are per-buffer in Emacs but not in Edwin.
abbrev-mode auto-fill-hook buffer-auto-save-file-name buffer-backed-up buffer-file-name buffer-offer-save buffer-read-only buffer-saved-size buffer-undo-list ctl-arrow default-directory local-abbrev-table major-mode mark-ring mode-name overwrite-mode selective-display selective-display-ellipses shell-prompt-pattern
Incorrect behavior of Edwin that will be fixed:
This document was generated on 11 August 1998 using the texi2html translator version 1.51.