[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This chapter describes how to run MIT/GNU Scheme. It also describes how you can customize the behavior of MIT/GNU Scheme using command-line options and environment variables.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Under unix and OS/2, MIT/GNU Scheme is invoked by typing
scheme |
at your operating system's command interpreter. Under Windows, MIT/GNU Scheme is invoked by double-clicking on a shortcut. In either case, Scheme will load itself and print something like this:
Scheme saved on Monday June 17, 2002 at 12:10:46 PM Release 7.7.1 Microcode 14.9 Runtime 15.1 |
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. `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 `6.001' is the SICP compatibility package.
You can load the compiler 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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
You can customize your setup by using a variety of tools:
HOME
environment variable. Under unix, the file is called
`.scheme.init'; on the PC it is called `scheme.ini'.
In addition, when Edwin starts up, it loads a separate init file from your home directory into the Edwin environment. This file is called `.edwin' under unix, and `edwin.ini' on the PC (see section 7.1 Starting Edwin).
You can use both of these files to define new procedures or commands, or to change defaults in the system.
The `--no-init-file' command-line option causes Scheme to ignore the `.scheme.init' file (see section 2.4 Command-Line Options).
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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:
cons
cells and strings. Storage used for objects in the heap
that become unreferenced is eventually reclaimed by garbage
collection.
All kinds of memory except the last may be controlled either by command-line options or by environment variables.
MIT/GNU 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 (see section 1.4 Optional Configuration).
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/GNU 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.
If the size of the constant space is not specified, it is automatically set to the correct size for the band being loaded. Thus, in general it is rarely necessary to explicitly set the size of the constant space. Additionally, each band requires a small amount of heap space; this amount is added to any specified heap size, so that the specified heap size is the amount of free space available.
The Scheme expression `(print-gc-statistics)' shows how much heap and constant space is available (see section 3.4 Garbage Collection).
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Scheme accepts the command-line options detailed in the following sections. The options may appear in any order, with the restriction that the microcode options must appear before the runtime options, and the runtime options must appear before any other arguments on the command line. Any arguments other than these options will generate a warning message when Scheme starts. If you want to define your own command-line options, see 2.5 Custom Command-line Options.
Note that MIT/GNU Scheme supports only long options, that is, options specified by verbose names, as opposed to short options, which are specified by single characters. As of release 7.7.2, all options start with two hyphens, for compatibility with GNU coding standards (and most modern programs). Prior to this release, options started with a single hyphen. While the single-hyphen style continues to work, it is deprecated and will someday stop working.
These are the microcode options:
MITSCHEME_COMPILER_BAND
, if defined, or
`compiler.com'; the library directories are searched to locate this
file.
MITSCHEME_EDWIN_BAND
, if defined, or
`edwin.com'; the library directories are searched to locate this
file.
MITSCHEME_ALL_BAND
, if defined, or `all.com'; the
library directories are searched to locate this file.
MITSCHEME_BAND
, or if that isn't defined, `runtime.com'; in
these cases the library directories are searched, but not the working
directory.
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 3.4 Garbage Collection).
bchscheme
allocates only one, and uses a disk file for the other.
The size specified by this option is incremented by the amount of heap space needed by the band being loaded. Consequently, `--heap' specifies how much free space will be available in the heap when Scheme starts, independent of the amount of heap already consumed by the band.
This detaching behavior is useful for running Scheme as a background
job. For example, using bash
, the following will run Scheme
as a background job, redirecting its input and output to files, and
preventing it from being killed by keyboard interrupts or by logging
out:
scheme < /usr/cph/foo.in > /usr/cph/foo.out 2>&1 & |
This option is ignored under non-unix operating systems.
This option is ignored under non-unix operating systems.
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\lib'.
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.
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:
MITSCHEME_GC_DIRECTORY
is used instead, and
if that is not defined, a standard temporary directory is used (see
TMPDIR
in see section 2.6.3 Environment Variables for the Runtime System).
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.
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'.
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'.
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.
MITSCHEME_GC_DRONE
is
used instead, and if that is not defined, `gcdrone' is used.
MITSCHEME_GC_READ_OVERLAP
is
used instead, and if that is not defined, `0' is used, disabling
overlapped reads.
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.
Normally this file is never written, but the `--suspend-file' option enables writing of this file.
user-initial-environment
. Unless explicitly handled, errors
during evaluation are silently ignored.
user-initial-environment
. Unless explicitly handled, errors
during loading are silently ignored.
The following option is supported only when Edwin is loaded.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
MIT/GNU Scheme provides a mechanism for you to define your own command-line options. This is done by registering handlers to identify particular named options and to process them when Scheme starts. Unfortunately, because of the way this mechanism is implemented, you must define the options and then save a world image containing your definitions (see section 3.3 World Images). Later, when you start Scheme using that world image, your options will be recognized.
The following procedures define command-line parsers. In each, the argument keyword defines the option that will be recognized on the command line. The keyword must be a string containing at least one character; do not include the leading hyphens.
Multiple?, if true, says that keyword may be followed by
more than one argument on the command line. In this case, procedure is
called once for each argument that follows keyword and does not
start with a hyphen. If multiple? is #f
, procedure
is called once, with the command-line argument following keyword.
In this case, it does not matter if the following argument starts with a
hyphen.
values
procedure): the unused
command-line arguments (as a list), and a thunk that is executed to
implement the behavior of the option.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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/GNU 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") |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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_ALL_BAND
(default: `all.com' on the library path)
MITSCHEME_BAND
(default: `runtime.com' on the library path)
MITSCHEME_COMPILER_BAND
(default: `compiler.com' on the library path)
MITSCHEME_EDWIN_BAND
(default: `edwin.com' on the library path)
MITSCHEME_LARGE_CONSTANT
(default: as needed)
MITSCHEME_LARGE_HEAP
(default: `1000')
MITSCHEME_LARGE_STACK
(default: `100')
MITSCHEME_LIBRARY_PATH
MITSCHEME_SMALL_CONSTANT
(default: as needed)
MITSCHEME_SMALL_HEAP
(default: `250')
MITSCHEME_SMALL_STACK
(default: `100')
MITSCHEME_UTABMD_FILE
(default: `utabmd.bin' in the library path)
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
bchscheme
These environment variables are referred to by bchscheme
(not by scheme
).
MITSCHEME_GC_DIRECTORY
TMPDIR
in see section 2.6.3 Environment Variables for the Runtime System).
MITSCHEME_GC_FILE
(default: `GCXXXXXX')
MITSCHEME_GC_START_POSITION
(default: `0')
MITSCHEME_GC_END_POSITION
(default: start-position+heap-size)
MITSCHEME_GC_WINDOW_SIZE
(default: `16')
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')
MITSCHEME_GC_READ_OVERLAP
(default: `0')
MITSCHEME_GC_WRITE_OVERLAP
(default: `0')
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These environment variables are referred to by the runtime system.
HOME
HOMEDRIVE
and HOMEPATH
, set by the operating system, are
used instead. Under unix, HOME
is set by the login shell.
TMPDIR
TEMP
TMP
MITSCHEME_INF_DIRECTORY
(default: `SRC' on the library path)
MITSCHEME_LOAD_OPTIONS
(default: `optiondb.scm' on the library path)
load-option
procedure.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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)
ESHELL
SHELL
environment variable is used instead.
SHELL
(default: `/bin/sh' (unix), `cmd.exe' (PC))
shell-path-name
editor
variable.
PATH
exec-path
editor variable, which is
subsequently used for finding programs to be run as subprocesses.
DISPLAY
TERM
LINES
(default: auto-sense)
COLUMNS
(default: auto-sense)
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These environment variables are specific to the Microsoft Windows implementation.
MITSCHEME_FONT
(default: determined by operating system)
Once in Edwin, the font can be changed with the set-font
and
set-default-font
commands.
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
.
HOMEDRIVE
HOMEPATH
USERNAME
USER
USERNAME
is preferred; USER
is used if USERNAME
is not defined. If neither of these
variables is defined, an error is signalled when the username is
required.
USERDIR
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These environment variables are specific to the OS/2 implementation.
USER
USERDIR
HOME
is not defined; we recommend using
HOME
rather than USERDIR
.
COMSPEC
SHELL
is not defined.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Microsoft Windows version of MIT/GNU Scheme runs as a graphics-based application. Scheme is normally started using shortcuts; the installer automatically generates several different predefined shortcuts for your convenience.
The rest of this section gives some tips on how to set up shortcuts that run Scheme. If you are unfamiliar with this concept you should read about it in the system help.
scheme.exe
and
bchschem.exe
in the shortcut Command line.
MITSCHEME_LIBRARY_PATH
environment
variable.
HOME
environment variable as we recommend.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
(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 procedure suspends Scheme; when this is done you may later restart where you left off. Unfortunately this is not possible in all operating systems; currently it works under unix versions that support job control (i.e. all of the unix versions for which we distribute Scheme). To suspend Scheme, evaluate
(quit) |
If your system supports suspension, this will cause Scheme to stop, and
you will be returned to the shell. Scheme remains stopped, and can be
continued using the job-control commands of your shell. If your system
doesn't support suspension, this procedure does nothing. (Calling the
quit
procedure is analogous to typing C-z, but it allows
Scheme to respond by typing a prompt when it is unsuspended.)
save-buffers-kill-scheme
, normally bound to C-x C-c, and
suspend-scheme
, normally bound to C-x C-z. These two
commands correspond to the procedures exit
and quit
,
respectively.
Under OS/2, there are two distinct ways to close the console window. The first is to use any of the usual window-closing methods, such as the `Close' system-menu item or double-clicking on the system-menu icon. When this is done, you will be presented with a dialog that gives you the option to close the window with or without termating Scheme. The second way is to select the `Exit' item from the `File' menu, which terminates Scheme immediately with no dialog.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |