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


Running Scheme

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

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 `File | Run..' command, or an icon.) Scheme will load itself, clear the screen, and print something like this:

Scheme saved on Monday March 25, 1996 at 2:15:03 PM
  Release 7.4.2
  Microcode 11.151
  Runtime 14.168

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 SICP 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:

Memory Usage

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

Scheme uses four kinds of memory:

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

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

The total storage required by `scheme' is:

stack + (constant + 2*heap) + extra

where stack, constant and heap are parameters that are 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 extra microcode storage is not included in this adjustment. Previous versions of MIT Scheme needed to be told the amount of constant space that was required when loading bands with the `-band' option. Dynamic adjustment of the heap and constant space avoids this problem; now all that is required is that the total space be sufficient.

The Scheme expression `(print-gc-statistics)' shows how much heap and constant space is available (see section Garbage Collection).

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 expression `(print-gc-statistics)' shows how much heap and constant space is available and in use (see section Garbage Collection).
-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, which prevents it from getting signals sent to the process group of that terminal. If this option is specified, Scheme will not detach itself from the controlling terminal. This detaching behavior is useful for running Scheme as a background job. For example, using 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 is ignored under non-Unix operating systems.
-nocore
Specifies that Scheme should not generate a core dump under any circumstances. If this option is not given, and Scheme terminates abnormally, you will be prompted to decide whether a core dump should be generated. This option is ignored under non-Unix operating systems.
-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
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 maintenance and development of the MIT Scheme runtime system.

In addition to the above, `bchscheme' recognizes 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-file 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
Specifies the first byte position in GC file at which the Scheme process can write. If not given, the value of the environment variable `MITSCHEME_GC_START_POSITION' is used, 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-end-position number
Specifies the last byte position in GC file at which the Scheme process can write. If not given, the value of the environment variable `MITSCHEME_GC_END_POSITION' is used, and if that is not defined, the sum of the start position (as specified by `-gc-start-position') and the heap size is used. 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 then only if the `gcdrone' program is installed in the library directory.

-gc-drone program
Specifies that program should be used as the drone program for overlapped I/O during garbage collection. 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. 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. 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.

The following options are runtime options. They are processed after the microcode options and after the image file 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).
-suspend-file
Under some circumstances Scheme can write out a file called `scheme_suspend' in the user's home directory.(3) This file is a world image containing the complete state of the Scheme process; restoring this file continues the computation that Scheme was performing at the time the file was written. Normally this file is never written, but the `-suspend-file' option enables writing of this file.
-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.

Environment Variables

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

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

(set-environment-variable! "EDWIN_FOREGROUND" "32")

Environment Variables for the Microcode

These environment variables are referred to by the microcode (the executable C programs called `scheme' and `bchscheme' under Unix, and `scheme.exe' and `bchschem.exe' on the PC).

`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 depends on machine; on most machines it is larger than `1000'.
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_SMALL_CONSTANT (default: `450')
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 depends on machine; on most machines it is larger than `450'.
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 in which GC files are written. Overridden by `-gc-directory'.
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_END_POSITION (default: start-position+heap-size)
The last position in the GC file to use. Overridden by `-gc-end-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 then only 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 Runtime System

These environment variables are referred to by the runtime system.

HOME
Directory in which to look for init files. E.g. `c:\users\joe' or `/home/joe'.
TEMP
TMP
Directory for various temporary files. `TEMP' is given preference to `TMP'.
MITSCHEME_INF_DIRECTORY (default: `SRC' on the library path)
Directory containing the debugging information files for the Scheme system. Should contain subdirectories corresponding to the subdirectories in the source tree. For example, if its value is `f:\random', runtime system debugging files will be expected in `f:\random\runtime', while Edwin debugging files will be expected in `f:\random\edwin'.
MITSCHEME_LOAD_OPTIONS (default: `optiondb.scm' on the library path)
Specifies the location of the options database file used by the load-option procedure.

Environment Variables for 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.
ESHELL
Unix and OS/2 only. Filename of the shell program to use in shell buffers. If not defined, `SHELL' is used instead.
SHELL (default: `/bin/sh' (Unix), `cmd.exe' (OS/2))
Unix and OS/2 only. Filename of the shell program to use in shell buffers and when executing shell commands. Used to initialize the shell-path-name editor variable.
PATH
Unix and OS/2 only. Used to initialize the exec-path editor variable, which is subsequently used for finding programs to be run as subprocesses.
DISPLAY
Unix running X11 only. Specifies the display on which Edwin will create windows.
TERM
Unix terminals only. Terminal type.
LINES (default: auto-sense)
Unix terminals only. Number of text lines on the screen, for systems that don't support `TIOCGWINSZ'.
COLUMNS (default: auto-sense)
Unix terminals only. Number of text columns on the screen, for systems that don't support `TIOCGWINSZ'.

Environment Variables for Windows

These environment variables are specific to the Windows implementation.

MITSCHEME_FONT (default: determined by operating system)
A string specifying a font name and characteristics, for example, `Courier New 16 bold'. Allowed characteristics are integer, specifiying the font size, and the following style modifiers: `bold', `italic', `regular', `underline' and `strikeout'. Note that the size is the total height in pixels, and not the point size. Thus the fonts tend to be 20-50% smaller than you might expect. You should specifiy only fixed-width fonts as variable width fonts are not drawn correctly. Once in Edwin, the font can be changed with the `set-font' and `set-default-font' commands.
MITSCHEME_GEOMETRY (default: `-1,-1,-1,-1')
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)
A 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)
A value specifying the window background color. See `MITSCHEME_FOREGROUND'.
HOMEDRIVE
HOMEPATH
These variables are used together to indicate the user's home directory. This is the preferred way to specify the home directory.
USERNAME
USER
Specifies the login name of the user running Scheme. This is used for several different purposes. `USERNAME' is preferred; `USER' is used if `USERNAME' is not defined. If neither of these variables is defined, "nouser" is used as the user's name.
USERDIR
Specifies a directory that contains the home directories of users. One of the places in which Scheme looks for the user's home directory, by searching for a subdirectory with the user's login name.

Environment Variables for OS/2

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

USER
Specifies the login name of the user running Scheme. This is used for several different purposes. If this variable is undefined, "nouser" is used as the user's name.
USERDIR
Specifies a directory that contains the home directories of users. One of the places in which Scheme looks for the user's home directory, by searching for a subdirectory with the user's login name.

Starting Scheme from Windows

The Windows version of MIT Scheme runs as a graphics-based application. Under Windows NT and Windows 95, Scheme can be started from the command line as described at the beginning of this chapter.

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 it is not a DOS program (although some people run other shell programs in place of `command.com' that can run Windows applications).

Shortcuts (Windows 95) or Program Manager groups and icons (Windows 3.1 and Windows NT) are a convenient way to start Scheme. The rest of this section gives some tips on how to set up shortcuts that run Scheme. If you are unfamiliar with this concept you should read about it in the system help.

Leaving Scheme

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


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