-- (C) Copyright International Business Machines Corporation 23 January 
-- 1990.  All Rights Reserved. 
--  
-- See the file USERAGREEMENT distributed with this software for full 
-- terms and conditions of use. 
	How to Install the Hermes Language System, Release 0.5 (alpha)

A. Installing a Pre-compiled System

I. Extract the files from the release tape/tar file

The hermes system as provided on magnetic tape consists of several tar
files, the first of which contains a shell script that knows how to
extract all the rest.  Alternatively, the tar files and the
installation shell script may have been obtained through other means,
such as via anonymous ftp from software.watson.ibm.com.  A typical
installation proceeds as follows:

1. Extract the first tar file from the tape into some convenient
directory (this need not be the directory into which you wish to
install the Hermes system).  E.g.:

	cd /tmp ; tar xf /dev/rst8

If you have obtained the tar files and installation script via some
other means, this step does not apply.

2. Run the 'install-hermes' script that results from step 1.  You will
be asked the following questions:


    Install from disk or tape?
	Respond with one of the words "disk" or "tape", depending on
	whether already have the tar files on your disk or you need to
	extract them from the release tape.

    Name of non-rewinding tape device:
	This question appears only if you responded "tape" to the
	first question.

	Respond with the name of a tape device that does not
	automatically rewind on close operations.  Typically this
	might be /dev/nrst8 on Sun systems, or /dev/rmt0.5 on the IBM
	RiscSystem/6000.

    Directory containing (compressed or uncompressed) tar files: "
	This question appears only if you responded "disk" to the
	first question.

	REspond with a path to the directory containing the release
	tar files.  You need not uncompress the tar files before
	proceeding if you obtained the compressed versions (*.tar.Z
	files).

    Directory where Hermes should be installed:
	Respond with a path to the directory where you wish the
	Hermes system to be rooted.  This will normally be an empty
	directory, though it is OK to run install-hermes more than
	once on the same directory (e.g. to install executables for a
	machine type that was omitted during an earlier install).

    Install <component> (nnn bytes)?
	This question will appear for each component of the hermes
	distribution that appears on your release tape or in the
	directory containing your tar files.  Respond 'y' or 'n'
	to each question depending on whether you want to install the
	component.  See below for a list of the components and some
	recommendations on whether you need them.

    OK to send notification of installation to hermes@watson.ibm.com?
	We like to keep track of where hermes has been installed.  If
	you respond 'y' to this question, an electronic mail
	notification will be generated for us.  If you respond 'n', no
	notification will be sent.

At this point, the installation will proceed, extracting the selected
tar files and skipping the others.  If you selected Hermes binaries,
you will be asked a final question:

     Install Hermes shell script in system directory?  

	A shell script, named "hermes", is provided for running the
	Hermes interpreter.  The shell script automatically invokes
	the executable for the proper architecture.  If you respond
	'y' to this question, the shell script will be installed in
	the directory of your choice.  For example, you might specify
	/usr/local/bin as the system directory for the shell script.

If the installation procedure outlined above fails, you may be able to
extract the files manually from the tape.  Use the second file on the
tape as a guide to what should be extracted.  It is a tar file
containing a single file named "directory," which lists all the
remaining tar files on the tape in the order they appear.  Thus the
first file listed in "directory" would be the third file on the tape,
and so forth.

Following is a list of the components of the hermes distribution.

    required.tar
	This component contains the user agreement with which you must
	comply if you wish to use this Hermes implementation.  You are
	not offered the choice of declining this component; it will
	always be loaded.  The user agreement will be extraced into
	the file USERAGREEMENT at the top of the hermes tree.  You
	should be sure to read it before you use the software.

    doc.tar
	This component contains the users guide, README, these
	installation notes, and assorted random documentation at
	various levels of quality and usefulness.

    binary.tar
	This component contains all the machine-independent hermes
	binaries.  These are the things that are produced when you
	compile a hermes program.  They include the compiler and a
	number utilities.  You will either need to accept this
	component now or go through the compiler bootstrapping
	procedure later if you actually want to run hermes programs.

    source.tar
	This is the complete source distribution.  It includes the C
	sources for the parser, interpreter and runtime, and hermes
	sources for the compiler and utilities.

    demobin.tar
	This component contains the hermes binaries for a
	demonstration appointment scheduling program.

    demosrc.tar
	This component contains the source for the demonstration
	program.

    tutbin.tar
	This component contains the program examples appearing in the
	tutorial section of "Hermes: A Language for Distributed
	Computing" by Strom, etc., published in 1991 by Prentice-Hall,
	Inc.  If you extract this component you can actually run the
	programs appearing in the book.

    tutsrc.tar
	This component contains all the source files for the tutorial
	examples.

    <architecture>.tar
	There are several components containing machine-dependent
	executables for various architectures.  Select the ones that
	correspond to platforms on which you plan to run hermes.  It
	is possible to load several of these components on a single
	machine and then run hermes (via NFS mounts) from the same
	installation tree on different architectures.
    
    chbinary.tar
	Transformed .po files produced by chcode from all the
	binaries in binary.tar.  You should extract this and
	the appropriate ch-<architecture> components if you
	wish to make use of the c-coded versions of the
	standard libraries.

    ch-<architecture>.tar
	The Unix object files (.o files) produced by compiling
	the chcode-generated C sources for the standard Hermes
	binaries, for the specified architecture.

    chsource.tar
	The C source files produced by chcode for all the
	standard Hermes binaries.

    chskel.tar
	Like chbinary.tar, but no Unix object file names
	appear in the .po files.  These skeletons can be used
	with chcode to recompile the C sources supplied in the
	chsource component for a new platform, with the
	-notransform option.  The non-skeleton versions are
	not usable for this, since when they are loaded, the
	interpreter will immediately attempt to dynamically
	link the object files named in the .po files; this
	will fail, and the chcode process will terminate.

The remainder of this document will assume that the hermes tree is
rooted in a directory named hermes.

II. Set up the Hermes root directory.

The Hermes interpreter needs to know where the rest of the system has
been installed.  Unless it has been moved, this will be the directory
specified when the install-hermes script was run to extract the system
from tape or tar files.  It will be the directory containing bin,
mbin, and sysbin subdirectories.  This is the Hermes system root
directory.

The root directory can be set either by creating an entry for "hermes"
in /etc/passwd with the Hermes root directory as its home directory,
or by setting the environment variable HROOTDIR to the Hermes root
directory.

III. Install Shell Scripts

If you did not request installation of the Hermes shell script during the
tape installation procedure, you may manually install the shell
script at a later time as follows.

The hermes interpreter (hermes) is normally run from a shell
script provided in hermes/sysbin.  To install the script,
connect to hermes/sysbin and say

	make SYSBINDIR=/usr/local/bin install

where /usr/local/bin is the name of your local system binary directory.

If you are using a system for which pre-built executables were not
offered in the installation procedure, you will have to compile the
Hermes system.  See below.

IV. Start Using Hermes

You should start by reading the Hermes language tutorial in the book,
and the Hermes User's Guide (in hermes/doc).  The Hermes interpreter
is called hermes, so a command like

	hermes shell

will start the interpreter and run a shell from which you can compile
Hermes programs.  Actually, if the hermes shell script is
invoked without arguments, it runs the shell by default, so
the word "shell" could be omitted from the above command.

B. Compiling the Hermes System

If pre-compiled binaries are not available for your system, you will
have to compile it yourself.  At present, this amounts to porting
Hermes to your system, since we include binaries for all machines on
which we have tested Hermes.

I. Prepare the makefiles

All the makefiles in the distribution are generated from files called
Makefile.cpp that are run through the C preprocessor.  A shell script in
the root directory will generate all the makefiles for you.  First,
connect to the Hermes root directory.  Then define the following
environment variables:

    HROOTDIR: The full path name of the Hermes root directory.
    HARCH: The name of the architecture for which you wish to
        build hermes.

Finally, say "make-makehermes"; all the Makefiles in the source tree
will be created.

Before performing this step, it may be wise for you to check through the
file make/includefile, which includes several customization based on the
architecture for which makefiles are being built.

II. Run Make

At this point, you should be able to build the binaries by connecting to
the top-level hermes directory and issuing:

	make newversion interpboot

This will recursively invoke make in the C directories and build an
interpreter.

If you are building on an architecture that has not yet been ported,
you will almost certainly come across a few minor problems during
compilation.  We have made every attempt to make the code portable.


III. Make window support

If you are building for a Sun with Sunview, issue the following
command while logged into the Sun:

	make sunwindow

If you are building for a machine running X11R3, issue the following
command while logged into that machine:

	make xwindow


Direct questions about porting to hermes@watson.ibm.com.

