1. Installation

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

1.1 Unix Installation
1.2 Windows Installation
1.3 OS/2 Installation
1.4 Optional Configuration

1.1 Unix Installation

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

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

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

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

To install the software in `/usr/local', do the following

cd /usr/local gzip -cd path-to-distribution/linux.tar.gz | tar xf -

After executing these commands, the executable files will be in `/usr/local/bin', and the library files will be in `/usr/local/lib/mit-scheme'. No further configuration is required.

To install the files in directories of your choice:

• First unpack the distribution:

  mkdir temp cd temp gzip -cd linux.tar.gz | tar xvf -

• Next, move the contents of the `bin' directory to somewhere convenient that is on your execution path. For example, if you had a directory `~/bin' on your path, you would do this:

  mv bin/* ~/bin/.

• Next, move or copy the `mit-scheme' directory somewhere convenient. For example, you could move it to your home directory:

  mv lib/mit-scheme ~/.

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

• Next, you must tell Scheme where to find the `mit-scheme' directory. This can be done in one of two ways. The first way is to bind the environment variable MITSCHEME_LIBRARY_PATH to the full path to the directory, e.g. in bash you would do

  export MITSCHEME_LIBRARY_PATH=~/mit-scheme

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

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

  scheme -library ~/mit-scheme

• You should now be able to run MIT Scheme. See section 2. Running Scheme for more information.

1.2 Windows Installation

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

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

To uninstall the software, open up the `Control Panel', run `Add/Remove Programs', and double-click on `MIT Scheme 7.5'.

1.3 OS/2 Installation

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

1.3.1 OS/2 Installation Procedure
1.3.2 Environment Variables

1.3.1 OS/2 Installation Procedure

After unpacking the ZIP file, `os2.zip', you will have these directories containing the following files:

`exe'

The executable programs `scheme.exe' and `bchschem.exe'.

`dll'

The dynamic link libraries `blowfish.dll', `gdbm.dll', and `md5.dll'.

`doc'

Documentation files in HTML.

`lib'

A directory containing the data files needed by Scheme when it is running.

Perform the following steps to install Scheme:

1. Move the executable files `scheme.exe' and `bchschem.exe' from `exe' to any directory that appears in your PATH environment variable. You may either add the `exe' directory to your path by editing `config.sys' and rebooting, or you may move the files in `exe' to an existing directory that is already on your PATH.

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

2. Move the dynamic link libraries from `dll' to any directory that appears in your LIBPATH environment variable. As above, you may either add `dll' to your LIBPATH, or move the files in `dll' to a directory that is already on your LIBPATH.

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

   For example, if you decide to store the directory as `c:\schdata', you would add the following to `config.sys':

   SET MITSCHEME_LIBRARY_PATH=C:\SCHDATA

   (Remember that you must reboot OS/2 after editing `config.sys' in order for the changes to take effect.)

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

   scheme -library d:\myscm\mylib

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

4. Optional: Move the `doc' directory anywhere you like, or delete it if you do not want to keep the documentation.

5. Optional: Consider setting some of the environment variables described below.

1.3.2 Environment Variables

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

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

MITSCHEME_LIBRARY_PATH

says where to find Scheme's data files. This is the only required environment variable (but is not required when Scheme is invoked with the -library command-line option).

SET MITSCHEME_LIBRARY_PATH=C:\SCHEME\LIB

MITSCHEME_INF_DIRECTORY

tells Scheme where to find debugging information for the runtime system. The default value for this environment variable is a subdirectory `src' located in the directory specified by MITSCHEME_LIBRARY_PATH.

SET MITSCHEME_INF_DIRECTORY=C:\SCHEME\LIB\SRC

TMPDIR

tells Scheme the name of a directory where it can store temporary files.

SET TMPDIR=C:\TMP

HOME

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

SET HOME=C:\CPH

USER

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

SET USER=cph

SHELL

tells Edwin what shell program to use in shell buffers and for running shell commands. If not specified, this defaults to the standard OS/2 shell, `cmd.exe'.

SET SHELL=C:\4OS2251\4OS2.EXE

1.4 Optional Configuration

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

The Scheme runtime environment and associated tools are normally stored in bands, which are large memory images stored in files (see section 3.3 World Images). Scheme requires at least one band to work properly. The Scheme distribution contains several bands. These bands are stored in the `lib/mit-scheme' directory on unix systems, and the `lib' directory on PC systems.

`runtime.com'

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

`compiler.com'

This contains the runtime files and the native-code Scheme compiler. This band is chosen when the -compiler command-line option is supplied.

`edwin.com'

This contains the runtime files and the Edwin text editor. This band is chosen when the -edwin command-line option is supplied.

`all.com'

This contains the runtime files, the native-code compiler, and Edwin. This band is chosen when both the -compiler and -edwin command-line options are supplied.

Depending on your needs, you may not need all of these files. For example, if you always want the full development environment, you might keep `all.com' and delete the others. Or if you will never use the compiler, you could delete `compiler.com' and `all.com'. Remember that you must keep at least one of these files to use Scheme.

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

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

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

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