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

Installation

This chapter describes how to install MIT Scheme release 7.4. 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.

If you are installing on an HP 9000 series 700 or 800, you should also read section HP-PA Installation.

Unix Installation

We will use as an example the installation for GNU/Linux. The installation for other Unix systems is similar. If you are installing on 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.4', 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.

First unpack the distribution:
```
gzip -cd linux.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.
Next, go to the directory that you just unpacked:
```
cd dist-7.4
```
The 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.
The script assumes there is no pre-existing installation of MIT Scheme on your system. If there is, you may need to edit the script, or delete the existing version (particularly the contents of `/usr/local/lib/mit-scheme', see the later note on editing `libdir'). If you have trouble deleting the binary because it is in use, try renaming it to `scheme.busy' and deleting it later.
The installation script normally uses the command `cp -pr' to copy the files from the distribution directory to their final locations. You can change this by editing the definition of the `install' variable in the `install.sh' shell script. Some versions of `cp' do not support the `p' option; using simply `cp -r' in this case is acceptable. You can also use the `mv' command to move the files and directories into place, but note that most versions of `mv' require the source and destination to be on the same physical device.
The installation script may try to make some symbolic links during the installation. This is normally done using the command `ln -s'. If your system doesn't support symbolic links, or if you prefer to copy or hard-link files, change the definition of the `link' variable in the shell script.
For many systems, a standard place to put executable files is the directory `/usr/local/bin'. If this is true for your system, we suggest installing the executables there. Otherwise, you probably have some other directory that serves the same purpose; edit `install.sh' and change the definition of the shell variable `bindir' to be this other directory.
Normally, auxiliary files are stored in the directory `/usr/local/lib/mit-scheme/'. If you can, we suggest that you create such a directory and install these files there. Otherwise, create a directory somewhere else and edit the installation script to change the value of the variable `libdir' to be this directory.
If you have GNU Emacs installed on your system, the installation script will attempt to automatically determine values for the script variables `infodir', `emacslisp', and `movemail'. If it guesses incorrectly, you will have to override the guesses by editing the script with appropriate values.
Once you are satisfied that the `install.sh' script is correct, execute it:
```
./install.sh
```
After `install.sh' finishes, you can delete the `dist-7.4' directory that you unpacked earlier. You should now be able to run MIT Scheme by typing
```
scheme
```
at the command line (if you use the C shell, you may have to type `rehash' before `scheme' will be recognized).

HP-PA Installation

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. You should also read section Unix Installation.

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, 712, 715, 720, 725, 730, 735, 750, 755, 770,
816, 834, 835, 850, 867, 877

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:

Run the program `hppacach' that is included in the distribution. You must give this program the filename of the database file as an argument. Normally the database file name is `/usr/local/lib/mit-scheme/hppacach.mod', but if you install Scheme in a non-standard place it will be different. For example, if you install Scheme as `/usr/foo/mit-scheme/', the database file is called `/usr/foo/mit-scheme/hppacach.mod'.
Assuming that Scheme is installed in the normal place, update the database by becoming the super-user and executing the following commands on your machine:
```
cd /usr/local/lib/mit-scheme
./hppacach -update hppacach.mod
```
The reason that you must be super-user is that `hppacach' 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 `hppacach' 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.
If you add a new model to the database, we'd appreciate it if you would send us the model information, so that we can update the copy of the database that we distribute to others. This can be done using the `hppacach' program, as follows:
```
cd /usr/local/lib/mit-scheme
./hppacach -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!

OS/2 Installation

This section describes how to install MIT Scheme on a machine running OS/2 2.1 or OS/2 Warp 3.0.

Prerequisites

The Scheme files use about 20 megabytes of disk space when installed. An additional 5 megabytes of disk space is required during installation. After installation, you can reduce the amount of disk space required by deleting some files (see section Image Files).

MIT Scheme requires a fair amount of RAM to run well. We haven't tried running this on any machine with less than 36 megabytes, so we don't have any hard data on what the smallest practical amount of RAM is. However, for running Scheme under OS/2 Warp, 8 megabytes is probably the least you should consider, and 12 megabytes is probably comfortable. If you want to use the Scheme compiler or the Edwin text editor, you should have at least 16 megabytes of RAM.

MIT Scheme has been tested only on OS/2 Warp 3.0, but it should also run under OS/2 versions 2.1 and 2.11. It was compiled using IBM Visual Age C++ version 3.0 and the OS/2 Toolkit version 3.0.

OS/2 Installation Procedure

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

`readme': This file.
`bin\': The executable programs `scheme.exe' and `bchschem.exe'.
`doc\': Documentation files. Two files, the MIT Scheme User's Manual and the MIT Scheme Reference Manual, are provided in `.inf' format; these files can be read with the OS/2 `view' command.
`etc\': Installation command files. These are scripts that will be used during the installation procedure.
`icons\': A directory containing some useful icons.
`lib\': A directory containing the data files needed by Scheme when it is running.

Perform the following steps to install Scheme:

Run the command file `etc\mkbands.cmd'. This creates the image files `compiler.com', `edwin.com', and `all.com', and deletes the files `compdel.com' and `eddel.com'.
Move the executable files `scheme.exe' and `bchschem.exe' from `bin\' to any directory that appears in your `PATH' environment variable. Depending on your needs, you may want to keep only one of these files; each of these files is about 450 kilobytes and chances are you'll only be using one of them. If you keep only `bchschem.exe' we recommend you rename it to `scheme.exe'. Of course, you can also keep both programs around if you think you might use them both. The only difference between these two programs is in how they handle garbage collection. `scheme.exe' 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. `bchschem.exe' allocates only one memory heap, creates a disk file during garbage collection, copies objects into the file, then copies them back into memory.(1) These programs provide you with some important performance trade-offs. If you have plenty of memory and want the best performance, use `scheme.exe'. If you don't have enough memory, or if you want to use less memory and will accept slower performance, use `bchschem.exe'. One way to tell that you don't have enough memory is to run `scheme.exe' for a while and see if your machine is paging during garbage collection. You might consider trying to use `scheme.exe' and letting the operating system's paging handle the lack of RAM. But usually you will find that using `bchschem.exe' without paging is much faster than using `scheme.exe' with paging. Of course, if you are using `bchschem.exe' and you're still paging, there's nothing you can do to win.
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:\scheme\lib
```
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.
Optional: Move the `doc\' directory anywhere you like, or delete it if you do not want to keep the documentation.
Optional: Run the command file `etc\mkfolder.cmd' to create a folder containing icons to invoke Scheme. You must give this command file a single argument, which is the full path name of the executable file that you will use. For example, if you stored the file `scheme.exe' as `c:\scheme\bin\scheme.exe', then you would invoke this command file as follows:
```
etc\mkfolder c:\scheme\bin\scheme.exe
```
This will create a folder containing four icons, called `Scheme', `Edwin', `Liar', and `All', which correspond to the image files `runtime.com', `edwin.com', `compiler.com', and `all.com'. If you decide to delete any of the image files, you can delete the corresponding icons as well.
Optional: The `icons\' directory contains some Scheme-ish icon files. If you don't like the icons created by the `etc\mkfolder' command, you can use these icon files to change their appearance.
Optional: Consider setting some of other environment variables described below.

Image Files

Scheme stores its runtime environment in a binary image file, which is directly loaded into the Scheme process. An image file is a snapshot of Scheme's memory taken at a particular time (you can create your own image files using the disk-save procedure; see section World Images). This distribution comes with four different image files, each of which contains different mixes of programs. These image files are stored in the `lib\' directory.

`runtime.com' is the basic runtime environment with no other programs loaded. This is the smallest image file. All other image files are supersets of this file. This is the default image file that is used when Scheme starts up, unless it is overridden by a command-line option.
`compiler.com' contains the basic runtime environment and the Liar native-code compiler. This is the image file that is loaded when Scheme is started with the `-compiler' command-line option.
`edwin.com' contains the basic runtime environment and the Edwin text editor. This is the image file that is loaded when Scheme is started with the `-edwin' command-line option.
`all.com' contains the basic runtime environment, the Liar compiler, and the Edwin editor. This is the largest of the image files. There is no command-line option corresponding to this image file, but the following options can be used to load this file:
```
-large -constant 1600 -band all.com
```

You can delete any of these files that you aren't going to use (these image files take up a lot of disk space!). However, keep in mind that you need at least one image file to run Scheme at all.

Documentation

Documentation for Scheme is included with this release, in the directory `doc\'. It consists of the following files:

`user.inf' is the MIT Scheme User's Manual, which describes how to run and use Scheme. It describes all of the environment variables and command-line options, how to run the compiler and editor, etc.
`scheme.inf' is the MIT Scheme Reference Manual, which documents the programming language and the runtime library. This is a large and detailed document for writing programs.
`console.txt' describes the procedures that can be used to control the appearance of the console window (i.e. Scheme's main window).

Note: the User's Manual and Reference Manual are available in other forms, specifically: as PostScript files and as GNU Info files. These alternate forms of documentation may be obtained from our FTP site, `swiss-ftp.ai.mit.edu'.

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 section 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

TEMP

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

SET TEMP=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:\LOCAL\PROG\4OS2251\4OS2.EXE

Windows Installation

This section describes how to install MIT Scheme on Windows 3.1, Windows 95 and Windows NT. Note that we have tested MIT Scheme only on Windows NT 3.10, Windows 3.1 and Windows 95. It should run under Windows NT 3.51. It was compiled using the Microsoft's MSTOOLS compiler that comes with Windows NT 3.10.

Prerequisites

MIT Scheme requires a fair amount of RAM to run well. We haven't tried running this on any machine with less than 32 megabytes, so we don't have any hard data on what the smallest practical amount of RAM is. However, for running Scheme under Windows 3.1, 8 megabytes is probably the least you should consider, and 12 megabytes is probably comfortable. If you want to use the Scheme compiler or the Edwin text editor, you should have at least 16 megabytes of RAM.

MIT Scheme is a 32-bit program. To run it on Windows 3.1 you need to install the Win32s compatibility package from Microsoft. You might already have Win32s on your machine if another 32-bit software package installed it. Win32s is provided in the self-extracting ZIP file `pw1118.exe'. Create a temporary directory. Copy `pw1118.exe' into the directory, change into the directory and run `pw1118'. This will create three files. Follow the instructions in `readme.txt'.

Windows Installation Procedure

Create a directory where you would like Scheme to be installed. We suggest `c:\scheme'. From now on we will call this directory the Scheme root directory. Change to this directory and unpack `bin.zip':

unzip bin.zip

You will have the following files and directories:

`readme': These installation instructions.
`bin\': The executable programs `scheme.exe' and `bchschem.exe', and the libraries
`scheme16.dll', `scheme31.dll' and `scheme32.dll'.
`doc\': Documentation files. Three files, the MIT Scheme Users' Manual, the MIT Scheme Reference Manual, and the Revised^4 Report on the Algorithmic Language Scheme, are provided in Windows Help (`.hlp') format.
`etc\': Installation command files.
`lib\': A directory containing the data files needed by Scheme when it is running.

If you do not get this directory structure you may be using a version of `unzip' that does not understand directory trees. In this case use the version of `unzip' that comes with MIT Scheme, in the same directory as the `.zip' files.

Perform the following steps to install Scheme:

Build the bands. Make sure that you are in the Scheme root directory (you should be there already). Run the following command files
```
etc\mk_comp.bat
etc\mk_edwin.bat
etc\mk_all.bat
```
This will create the image files `lib\compiler.com', `lib\edwin.com', and `lib\all.com'. You may now delete the files `lib\compdel.com' and `lib\eddel.com'. If you are running Windows 3.1 you cannot run Scheme from the command line. You need to make a folder containing icons to run Scheme, as described below, and then run the following icons in turn: `Build COMPILER.COM band', `Build EDWIN.COM band' and `Build ALL.COM band'.
You may move the executable files `scheme.exe' and `bchschem.exe' and the three
`schemenn.dll' files from `bin\' to any directory that appears in your `PATH', though we suggest that you leave them put. Depending on your needs, you may want to keep only one of the `scheme.exe' or
`bchschem.exe' files; each of these files is about 550 kilobytes and chances are you'll only be using one of them. If you keep only `bchschem.exe' we recommend you rename it to `scheme.exe'. Of course, you can also keep both programs around if you think you might use them both. The only difference between these two programs is in how they handle garbage collection. `scheme.exe' 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. `bchschem.exe' allocates only one memory heap, creates a disk file during garbage collection, copies objects into the file, then copies them back into memory.(2) These programs provide you with some important performance trade-offs. If you have plenty of memory and want the best performance, use `scheme.exe'. If you don't have enough memory, or if you want to use less memory and will accept slower performance, use `bchschem.exe'. One way to tell that you don't have enough memory is to run `scheme.exe' for a while and see if your machine is paging during garbage collection. You might consider trying to use `scheme.exe' and letting the operating system's paging handle the lack of RAM. But usually you will find that using `bchschem.exe' without paging is much faster than using `scheme.exe' with paging. Of course, if you are using `bchschem.exe' and you're still paging, there's nothing you can do to win.
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 to be that location. For example, if you decide to store the directory as `d:\schdata', you would add the following to `autoexec.bat':
```
SET MITSCHEME_LIBRARY_PATH=D:\SCHDATA
```
You can override the setting of this environment variable with the `-library' command-line option to Scheme, for example:
```
scheme -library d:\schdata
```
If you always supply a `-library' option, it is not necessary to have the environment variable defined. For example, instead of editing `autoexec.bat', you might create a `.bat' file or a shortcut (icon) to invoke Scheme and pass it the `-library' option automatically.
Optional: Move the `doc' directory anywhere you like, or delete it if you do not want to keep the documentation.
Create a folder containing shortcuts (icons) to invoke Scheme. Run Scheme and load the file `etc\pmgrp.scm'. On Windows 95 and windows NT you can run scheme from the command line:
```
bin\scheme -library lib -load etc\pmgrp
```
On Windows 3.1 you have to use the `File | Run..' menu option of the Program Manager or File Manager and enter the full paths:
```
c:\scheme\bin\scheme -library c:\scheme\lib -load c:\scheme\etc\pmgrp.scm
```
This will create a folder called `MIT Scheme 7.4.2' containing icons for running Scheme and for reading the help files. The icons called `Scheme', `Edwin', `Liar', and `All', correspond to running Scheme with the image files `runtime.com', `edwin.com', `compiler.com', and `all.com'. If you decide to delete any of the image files, you can delete the corresponding icons as well. There is a bug in Windows 95 that prevents the Edwin shortcut from being created correctly. To get around this problem, we have created the shortcut with an incorrect command line. You have to manually edit the shortcut to change the curly braces on the command line into parentheses. The command line reads
```
...  -eval {edit}
```
but should read
```
...  -eval (edit)
```
Optional: Consider setting some of other environment variables described below.
The two files `w32rtbci.zip' and `w32edbci.zip' contain debugging information for the Scheme runtime and Edwin respectively. The total space required for all of the debugging information is about 8 megabytes. The runtime debugging information is the more useful as it allows the debugger to give you source code level information on all of the standard procedures like `map' and `number->string'. Debugging information can be installed by uncompressing the `w32rtbci.zip' and
`w32edbci.zip' files in the `SRC' subdirectory of the library directory.
```
cd c:\scheme\lib
mkdir SRC
cd SRC
unzip w32rtbci
unzip w32rtbci
```
Debugging information files can be installed in another place.
In this case the the `MITSCHEME_INF_DIRECTORY' environment variable should be set in `autoexec.bat'. To test that you have installed the debugging information correctly, try to pretty-print a compiled procedure, for example,
```
(pp pp)
```
When the debugging information is installed correctly, Scheme will be able to find the source code for the pp procedure, and display it. Otherwise it will use the short opaque form, something like this:
```
#[compiled-procedure 13 ("pp" #x2) #xF #x646BF7]
```

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