MIT Scheme 7.4.2 for OS/2

MIT Scheme is an implementation of the Scheme programming language.
This implementation is compliant with the "Revised^4 Report on the
Programming Language Scheme" and (with one small exception) the "IEEE
Standard for the Programming Language Scheme".  It supplies a large
runtime library, a native-code compiler with source-level debugging
tools, and an extensible integrated text editor which looks very much
like GNU Emacs.

MIT Scheme is free software.  Source code for the entire
implementation is available from our ftp server:

    swiss-ftp.ai.mit.edu:/pub/scheme-7.4/

See the file "doc\user.inf" for more information about using MIT Scheme.
You can read that file using the OS/2 "view" command.

If you discover any bugs, we'd like to hear about them.  Please send
bug reports to

   bug-cscheme@zurich.ai.mit.edu

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 (*note Image Files for OS/2 Installation::.).

   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:

  1. 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'.

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

  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:\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.

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

  5. *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.

  6. *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.

  7. *Optional:* Consider setting some of other environment variables
     described below.

   ---------- Footnotes ----------

   (1)  *Note Memory Usage::, for more detail about this topic.


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; *note 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.

  1. `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.

  2. `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.

  3. `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.

  4. `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 *Note 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
