Go to the first, previous, next, last section, table of contents.

Running Scheme

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.

Basics of Starting Scheme

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.

Customizing Scheme

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

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.

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. (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
Specifies the initial world image file (band) to be loaded. Searches for filename in the working directory and the library directories, using the full pathname of the first readable file of that name. If filename is an absolute pathname (on unix, this means it starts with `/'), then no search occurs -- filename is tested for readability and then used directly. If this option isn't given, the filename is the value of the environment variable MITSCHEME_BAND, or if that isn't defined, `runtime.com'; in these cases the library directories are searched, but not the working directory.
-compiler
This option specifies defaults appropriate for loading the compiler. It specifies the use of large sizes, exactly like -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
This option specifies defaults appropriate for loading the editor. It specifies the use of large sizes, exactly like -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
Specifies that large heap, constant, and stack sizes should be used. These are specified by the environment variables
MITSCHEME_LARGE_HEAP
MITSCHEME_LARGE_CONSTANT
MITSCHEME_LARGE_STACK
If this option isn't given, the small sizes are used, specified by the environment variables
MITSCHEME_SMALL_HEAP
MITSCHEME_SMALL_CONSTANT
MITSCHEME_SMALL_STACK
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 -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
Specifies the size of the heap in 1024-word blocks. Overrides any default. Normally two such heaps are allocated; bchscheme allocates only one, and uses a disk file for the other.
-constant blocks
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.
-stack blocks
Specifies the size of the stack in 1024-word blocks. Overrides any default. This is Scheme's stack, not the unix stack used by C programs.
-option-summary
Causes Scheme to write an option summary to standard error. This shows the values of all of the settable microcode option variables.
-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.
-interactive
If this option isn't specified, and Scheme's standard I/O is not a terminal, Scheme will detach itself from its controlling terminal. This will prevent 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 the C shell in unix, 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:
scheme < /usr/cph/foo.in >& /usr/cph/foo.out &
This option only makes sense under unix.
-nocore
Specifies that Scheme should not generate a core dump under any circumstances. Under unix, 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 on PC versions.
-library path
Sets the library search path to 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 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
Specifies that filename contains the microcode tables (the microcode tables are information that informs the runtime system about the microcode's structure). 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 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
Specifies that a cold load should be performed, using 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 -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
This option causes Scheme to ignore the `~/.scheme.init' or `scheme.ini' file, normally loaded automatically when Scheme starts (if it exists).
-no-suspend-file
Under some circumstances Scheme will write out a file called `scheme_suspend' in the user's home directory.(1) This file is a "band" 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. If the -no-suspend-file option is given, Scheme will not write a `scheme_suspend' file under any circumstances.
-eval
This option causes Scheme to evaluate the expressions 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 user-initial-environment. Unless explicitly handled, errors during evaluation are silently ignored.
-load
This option causes Scheme to load the files (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 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
Specifies that directory should be used to create files for garbage collection. If the option is not given, the value of environment variable MITSCHEME_GC_DIRECTORY is used instead, and if that is not defined, `/tmp' is used.
-gc-end-position number
It specifies the last byte position in -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
Specifies that filename should be used for garbage collection. If the option is not given, the value of environment variable 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
Specifies that the gc file used for garbage collection should not be deleted when scheme terminates. The gc file is deleted only if the file was created by this invocation of scheme, and this option is not set.
-gc-start-position number
It specifies the first byte position in -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
Specifies the size of the windows into new space during garbage collection. If this option is not given, the value of environment variable 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
Specifies that program should be used as the drone program for overlapped I/O during garbage collection. This option is recognized only by 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
Specifies that scheme should delegate at most N simultaneous disk read operations during garbage collection. This option is recognized only by 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
Specifies that scheme should delegate at most N simultaneous disk write operations during garbage collection. This option is recognized only by 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.

Environment Variables

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.

Environment Variables Affecting the Microcode

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)
The initial band to be loaded. Overridden by -band, -compiler, or -edwin.
MITSCHEME_COMPILER_BAND (default: `compiler.com' on the library path)
The initial band to be loaded if the -compiler option is given. Overridden by -band.
MITSCHEME_EDWIN_BAND (default: `edwin.com' on the library path)
The initial band to be loaded if the -edwin option is given. Overridden by -band.
MITSCHEME_LARGE_CONSTANT (default: `1000')
The size of constant space, in 1024-word blocks, if the -large, -compiler, or -edwin options are given. Overridden by -constant. Note: default is somewhat larger on RISC machines.
MITSCHEME_LARGE_HEAP (default: `1000')
The size of the heap, in 1024-word blocks, if the -large, -compiler, or -edwin options are given. Overridden by -heap.
MITSCHEME_LARGE_STACK (default: `100')
The size of the stack, in 1024-word blocks, if the -large, -compiler, or -edwin options are given. Overridden by -stack.
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 `/usr/local/lib/mit-scheme'. On PC systems the list is semi-colon separated with the default `c:\scheme\lib'.
MITSCHEME_INF_DIRECTORY
Directory containing the debugging information files for the system. It should contain subdirectories corresponding to the subdirectories in the source tree. For example, if its value is `f:\random', then runtime system debugging files will be expected in `f:\random\runtime', while edwin debugging files will be expected in `f:\random\edwin'.
MITSCHEME_SMALL_CONSTANT (default: `400')
The size of constant space, in 1024-word blocks, if the size options are not given. Overridden by -constant, -large, -compiler, or -edwin. Note: default is somewhat larger on RISC machines.
MITSCHEME_SMALL_HEAP (default: `250')
The size of the heap, in 1024-word blocks, if the size options are not given. Overridden by -heap, -large, -compiler, or -edwin.
MITSCHEME_SMALL_STACK (default: `100')
The size of the stack, in 1024-word blocks, if the size options are not given. Overridden by -stack, -large, -compiler, or -edwin.
MITSCHEME_UTABMD_FILE (default: `utabmd.bin' in the library path)
The file containing the microcode tables. Overridden by -utabmd and -utab. It is only necessary when re-building `runtime.com'.

Environment Variables for Bchscheme

These environment variables are referred to by `bchscheme' (not by `scheme').

MITSCHEME_GC_DIRECTORY (default: `/tmp')
The directory where to write gc files. Overridden by -gc-directory.
MITSCHEME_GC_END_POSITION (default: start-position + heap-size)
The last position in the gc file to use. Overridden by -gc-end-position.
MITSCHEME_GC_FILE (default: `GCXXXXXX')
The name of the file to use for garbage collection. If it ends in 6 Xs, the Xs are replaced by a letter and process id of the scheme process, thus generating a unique name. Overridden by -gc-file.
MITSCHEME_GC_START_POSITION (default: 0)
The first position in the gc file to use. Overridden by -gc-start-position.
MITSCHEME_GC_WINDOW_SIZE (default: 16)
The size in blocks of windows into new space (in the gc file). Overridden by -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')
The program to use as the I/O drone during garbage collection. Overridden by -gc-drone.
MITSCHEME_GC_READ_OVERLAP (default: 0)
The maximum number of simultaneous read operations. Overridden by -gc-read-overlap.
MITSCHEME_GC_WRITE_OVERLAP (default: 0)
The maximum number of simultaneous write operations. Overridden by -gc-write-overlap.

Environment Variables for the PC

These environment variables are referred to by the Windows, Windows NT, and DOS versions of MIT Scheme.

MITSCHEME_DPMI_EXT_KBD (default: `false')
DOS only. Boolean option specifying whether Scheme inserts its own keyboard handling routine when running under DPMI (DOS Protected Mode Interface) or Windows.
MITSCHEME_X32_EXT_KBD (default: `false')
DOS only. Boolean option specifying whether Scheme inserts its own keyboard handling routine when not running under DPMI or Windows.
MITSCHEME_TRAP_ALT_TAB (default: `false')
MITSCHEME_TRAP_ALT_ESCAPE (default: `false')
Windows and Windows NT only. Boolean option specifying the handling of system command accelerators. These options do not actually work.
MITSCHEME_GEOMETRY (default: `-1,-1,-1,-1')
Windows and Windows NT only. Four integers separated by commas or spaces that specify the placement and size of the MIT Scheme window as a left,top,width,height quadruple. The units are screen pixels, and `-1' means allow the system to choose this parameter. E.g. `-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.
MITSCHEME_FOREGROUND (default: according to desktop color scheme)
Windows and Windows NT only. An value specifying the window text color. The color is specified as hex blue, green and red values (not RGB): e.g. 0xff0000 for blue.
MITSCHEME_BACKGROUND (default: according to desktop color scheme)
Windows and Windows NT only. A value specifying the window background color. See MITSCHEME_FOREGROUND.

Environment Variables Affecting the Runtime System

These environment variables are referred to by the runtime system.

HOME
Directory where to look for init files. E.g. `c:\users\joe' or `/homes/joe'.
TEMP, TMP
Directory for various temporary files. TEMP is given preference to TMP.

Environment Variables Affecting Edwin

These environment variables are referred to by Edwin.

EDWIN_BINARY_DIRECTORY (default: `edwin/autoload' on the library path)
Directory where edwin expects to find files providing autoloaded facilities.
EDWIN_INFO_DIRECTORY (default: `edwin/info' on the library path)
Directory where edwin expects to find files for the `info' documentation subsystem.
EDWIN_ETC_DIRECTORY (default: `edwin/etc' on the library path)
Directory where edwin expects to find utility programs and documentation strings.
EDWIN_FOREGROUND (default: none (white))
DOS version only. ANSI foreground color specifier. Must be a two-digit sequence in the range 30-37. E.g. 32 (green).
EDWIN_BACKGROUND (default: none (black))
DOS version only. ANSI background color specifier. Must be a two-digit sequence in the range 40-47. E.g. 40 (black).
TERM
Terminal type. For DOS, should be `ansi.sys' or `ibm_pc_bios'. For Windows and Windows NT it should be `ansi.sys', which is the default if not set.
LINES (default: auto-sense)
Unix only. Number of text lines on the screen, depending on the terminal type.
MITSCHEME_LINES (default: auto-sense or 25)
DOS only. Number of text lines on the screen, depending on the video adapter and support software. E.g. 43.
COLUMNS (default: auto-sense)
Unix only. Number of text columns on the screen, depending on the terminal type (Unix) or video adapter and support software (DOS). E.g. 132.
MITSCHEME_COLUMNS (default: auto-sense, or 80)
DOS only. Number of text columns on the screen, depending on the video adapter and support software. E.g. 132.

Starting Scheme from Windows 3.1/NT

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:

Leaving Scheme

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.)


Go to the first, previous, next, last section, table of contents.