-*- Text -*-

	       Installation of MIT Scheme 7.2 alpha test

We will demonstrate the installation for SGI computers running Irix.
The installation is essentially the same for other machines except
Intel 386/486-based machines running either Unix or DOS.

For DOS installation instructions, look at the instructions in the DOS
distribution.

For Intel 386/486-based Unix installation instructions, see the NOTES
section at the end of this file first.  Then read the rest.

MIT Scheme is distributed as a compressed `tar' file.  The tar file
contains this file (INSTALL), and two directories, "bin" and "lib".
The "bin" subdirectory contains two executable files, "scheme" and
"bchscheme", while the "lib" subdirectory contains several files and
subdirectories that Scheme uses while it is executing.  Here is a
listing of the contents of the tar file:

-rw-r--r-- 5046/11 10612 Aug 21 09:36 1992 INSTALL
drwxrwxr-x 5046/11     0 Aug 21 09:43 1992 bin/
-r-xr-xr-x 5046/11 1176196 Aug 21 09:43 1992 bin/bchscheme
-r-xr-xr-x 5046/11 1136988 Aug 21 09:43 1992 bin/scheme
-rw-rw-r-- 5046/11   16604 Aug 18 22:31 1992 lib/utabmd.bin
-rw-rw-r-- 5046/11 2742936 Aug 20 13:06 1992 lib/runtime.com
-rw-rw-r-- 5046/11 6085692 Aug 20 16:14 1992 lib/compiler.com
-rw-rw-r-- 5046/11 6480104 Aug 20 13:08 1992 lib/edwin.com
-rwxrwxr-x 5046/11   42188 Aug 19 00:43 1992 lib/bchdrn
drwxrwxr-x 5046/11       0 Aug 21 09:28 1992 lib/options/
-rw-rw-r-- 5046/11   55068 Aug 19 20:50 1992 lib/options/cpress.bci
-rw-rw-r-- 5046/11   52372 Aug 19 20:50 1992 lib/options/cpress.com
-rw-rw-r-- 5046/11   17362 Aug 19 20:56 1992 lib/options/format.bci
-rw-rw-r-- 5046/11   18192 Aug 19 20:56 1992 lib/options/format.com
-rw-rw-r-- 5046/11   31554 Aug 19 21:01 1992 lib/options/hashtb.bci
-rw-rw-r-- 5046/11   31000 Aug 19 21:01 1992 lib/options/hashtb.com
-rw-rw-r-- 5046/11   19982 Aug 19 21:03 1992 lib/options/krypt.bci
-rw-rw-r-- 5046/11   17932 Aug 19 21:03 1992 lib/options/krypt.com
-rw-rw-r-- 5046/11   18821 Aug 19 21:09 1992 lib/options/numint.bci
-rw-rw-r-- 5046/11   30640 Aug 19 21:09 1992 lib/options/numint.com
-rw-rw-r-- 5046/11   28126 Aug 19 21:14 1992 lib/options/process.bci
-rw-rw-r-- 5046/11   31612 Aug 19 21:14 1992 lib/options/process.com
drwxrwxr-x 5046/11       0 Aug 21 09:37 1992 lib/edwin/
-rw-r--r-- 5046/11   33852 Aug 21 09:36 1992 lib/edwin/TUTORIAL
drwxrwxr-x 5046/11       0 Aug 21 09:47 1992 lib/edwin/autoload/
-rw-rw-r-- 5046/11   20535 Aug 20 11:19 1992 lib/edwin/autoload/c-mode.bci
-rw-rw-r-- 5046/11   26588 Aug 20 11:19 1992 lib/edwin/autoload/c-mode.com
-rw-rw-r-- 5046/11   33595 Aug 20 11:20 1992 lib/edwin/autoload/cinden.bci
-rw-rw-r-- 5046/11   34488 Aug 20 11:20 1992 lib/edwin/autoload/cinden.com
-rw-rw-r-- 5046/11   60294 Aug 20 11:27 1992 lib/edwin/autoload/dired.bci
-rw-rw-r-- 5046/11   66352 Aug 20 11:27 1992 lib/edwin/autoload/dired.com
-rw-rw-r-- 5046/11   77047 Aug 20 11:35 1992 lib/edwin/autoload/info.bci
-rw-rw-r-- 5046/11   82260 Aug 20 11:35 1992 lib/edwin/autoload/info.com
-rw-rw-r-- 5046/11   16940 Aug 20 11:37 1992 lib/edwin/autoload/keymap.bci
-rw-rw-r-- 5046/11   14776 Aug 20 11:37 1992 lib/edwin/autoload/keymap.com
-rw-rw-r-- 5046/11    6125 Aug 20 11:41 1992 lib/edwin/autoload/midas.bci
-rw-rw-r-- 5046/11    7748 Aug 20 11:41 1992 lib/edwin/autoload/midas.com
-rw-rw-r-- 5046/11   14763 Aug 20 11:43 1992 lib/edwin/autoload/pasmod.bci
-rw-rw-r-- 5046/11   17872 Aug 20 11:43 1992 lib/edwin/autoload/pasmod.com
-rw-rw-r-- 5046/11   11783 Aug 20 11:46 1992 lib/edwin/autoload/reccom.bci
-rw-rw-r-- 5046/11   10580 Aug 20 11:46 1992 lib/edwin/autoload/reccom.com
-rw-rw-r-- 5046/11   23540 Aug 20 11:59 1992 lib/edwin/autoload/tagutl.bci
-rw-rw-r-- 5046/11   24812 Aug 20 11:59 1992 lib/edwin/autoload/tagutl.com
-rw-rw-r-- 5046/11   10622 Aug 20 12:02 1992 lib/edwin/autoload/tximod.bci
-rw-rw-r-- 5046/11   14636 Aug 20 12:02 1992 lib/edwin/autoload/tximod.com

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.
Let's proceed.


1. First unpack the distribution:

     zcat sgi.tar.Z | tar xvf -

2. 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; in what
   follows, substitute the name of your directory for
   "/usr/local/bin".

   Install the executables by moving them into "/usr/local/bin".  Here
   is one way to do this:

      mv bin/* /usr/local/bin/.

   Once this has been done successfully, you can remove the "bin"
   subdirectory:

      rmdir bin

3. The remaining subdirectory, "lib", contains library files that
   Scheme needs to use while it's running.  By default, Scheme looks
   for them in the directory "/usr/local/lib/mit-scheme".  If it is
   possible and convenient for you to install the library there, you
   should do so.  Otherwise, put it somewhere else that is convenient,
   and substitute the name of your directory for
   "/usr/local/lib/mit-scheme" in what follows; later we will explain
   what you must do to tell Scheme that you have installed the
   libraries in a different place.

   Install the library files by creating the directory
   "/usr/local/lib/mit-scheme" and moving them to that directory.  The
   directory is normally created by the command

      mkdir /usr/local/lib/mit-scheme

   Moving the library files into place is somewhat more involved.
   Here are three methods -- choose the one that seems appropriate for
   you, or consult a system wizard at your site for help.

   * The first method only works if you have unpacked the distribution
     on the same physical device as "/usr/local/lib/mit-scheme".  (If
     you don't know what this means, either ask someone or use one of
     the other methods.)  Here is the command:

        mv lib/* /usr/local/lib/mit-scheme/.

   * The second method applies to systems that support the `cp -r'
     command.  (If you don't know whether your system supports this
     command, just try it -- you'll get an error message if it isn't
     supported.)  

        cp -r lib/* /usr/local/lib/mit-scheme/.

   * The third method applies to systems that support the `cpio'
     command.  It is somewhat more involved than the other methods,
     but it works for most systems that the other methods don't:

        (cd lib ; find * -print | cpio -pdmuv /usr/local/lib/mit-scheme)

   Once you have installed the library files, you're done with the
   installation.  Since you have copied all of the files from the
   "lib" directory to other places, you can delete it.

4. If you were unable to use the directory "/usr/local/lib/mit-scheme"
   in step 3, there is one final step: informing Scheme where to find
   the library files.

   When the "scheme" (or "bchscheme") executable is started, one of
   the things it does is look for the library files.  It does this in
   three steps:

   * If there is a "-library" option on the command line, it looks in
     that directory for the library files.  For example, if you have
     stored the library files in the directory "/usr/lib/scheme", you
     could invoke Scheme like this:

        scheme -library /usr/lib/scheme

   * If there is no "-library" option, Scheme looks at the value of
     the environment variable "MITSCHEME_LIBRARY_PATH".  If this
     variable is set, Scheme uses its value as the directory for the
     library files.  If you use the Bourne shell, you can set this in
     your ".profile" as follows:

	MITSCHEME_LIBRARY_PATH=/usr/lib/scheme
	export MITSCHEME_LIBRARY_PATH

     If you use the C shell, you can set it in your ".login" as
     follows:

	setenv MITSCHEME_LIBRARY_PATH /usr/lib/scheme

     It may be more convenient to set this environment variable so
     that it is the same for all users.  If you wish to do this,
     edit the files "/etc/profile" and "/etc/csh.login" with the help
     of a system wizard.

     An alternative to setting the environment variable in a login
     script is to install an executable shell script that first sets
     the environment variable to the appropriate value, and then
     invokes Scheme.  If you need help doing this, consult your system
     wizard.

   * Finally, if there is no "-library" option, and the environment
     variable "MITSCHEME_LIBRARY_PATH" has no value, Scheme assumes
     that the library files are to be found in
     "/usr/local/lib/mit-scheme".

   So, in summary: use "/usr/local/lib/mit-scheme" if you can,
   otherwise your best bet is to set the environment variable
   "MITSCHEME_LIBRARY_PATH" to the correct value.

			NOTES:

Note on using an HP 9000 series 600-800 (PA-RISC) computers:

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 "HPPAmodels", that
describes the cache structure for each model of computer.  At present,
that database contains entries for the following models:

    850, 835, 834, 720, 730, 750, 710, 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 "hppacache" that is included in the distribution.  You
must give this program the filename of the database file as an
argument.  Normally this is "/usr/local/lib/mit-scheme/HPPAmodels",
but if you install it 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/HPPAmodels".

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
    ./hppacache -update HPPAmodels

The reason that you must be super-user is that "hppacache" 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 "hppacache" 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 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
"hppacache" program, as follows:

    cd /usr/local/lib/mit-scheme
    ./hppacache -print HPPAmodels > model-[678]xx

(If you have previously updated the database, you do not need to be
super-user to execute this command.)  The resulting file, "model-[678]xx"
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!

Note on installing MIT Scheme 7.2 on Intel 386/486-based Unix.

There is no bin/ subdirectory in the 386 tar file.
The tar file includes the src/microcode subdirectory instead.
There are two reasons for this:

- There are many different versions of Unix for 386/486-based machines
(e.g. SCO, Linux, BSDI, Mach 3.0, System V3, Solaris, etc.) and the
Unix binaries for all of them are different (the Scheme binaries
should be the same).

- We don't have access to any 386/486 machines running any of the most
common versions of Unix, so we can't generate the binaries.

At any rate, you need to make bin/scheme (and perhaps bin/bchscheme)
yourselves.  The sources for this program are in the src/microcode
directory.  You should not attempt this unless you are very familiar
with the C language, and knowledgeable about Unix in general and the
particular version that you are dealing with. 

You should start by looking at the Bourne-shell script config.sh.
This script configures the microcode directory for your architecture
and OS type.  You may want to emulate the i386-sysv entry but choose a
system file that approximates your operating system better (if there
is one).  All the system files reside in the src/microcode/s
subdirectory.

After configuring the microcode, you should be able to "make" it.
However, it is likely that the compilation will fail because the
sources have probably not been conditionalized correctly (if at all)
for your OS.  At this point, you are mostly on your own, but will
probably want to take a look at the file src/microcode/ux.h and make
sure that all the appropriate HAVE_... macros have been defined for
your variant of Unix, and that the appropriate include files appear in
this file.

If you get the microcode to compile, then you can copy
src/microcode/scheme (and bchscheme) to bin/scheme
and proceed with the rest of the installation instructions.

Of course, there is no guarantee at that point that the system will
work, and you will have to try it.

If scheme boots but behaves improperly or strangely, you may want to
verify that all the appropriate system calls are enabled (with the
HAVE_... macros), particularly those having to do with terminal
control.

Good luck!
