-- (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.  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/rst0

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

    Name of non-rewinding tape device:
	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 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 Hermes binary files (~nnn bytes)?
	Respond 'y' or 'n' depending on whether you want to install
	the pre-build Hermes binaries.  You probably want to answer
	yes to this, since the binaries are needed in order to run
	Hermes.  Machine-dependent executables are not included in
	this component.

    Install Hermes source files (~nnn bytes)?
	Respond 'y' or 'n' depending on whether you want to install
	a complete set of Hermes source files.  If you plan to make
	changes or extensions to Hermes you will need sources.  There
	are also numerous Hermes programs that might be useful to
	those learning the language.

    Install Hermes executables for machine type "xxx" (~nnn bytes)?
	Respond 'y' or 'n' depending on whether you will be running
	Hermes on machines of the given type from this installation.
	Machines of different architectures can share a single
	installed Hermes tree via NFS cross-mounting.  If you wish to
	do this you will answer 'y' for more than one machine type.

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 scripts in system directory?
	Two shell scripts, named "hermes" and "hermi", are provided
	for running the primary Hermes executables.  The shell scripts
	automatically invoke the executable for the proper
	architecture.  If you respond 'y' to this question, the shell
	scripts will be installed in the directory of your choice.
	Normally, you might specify /usr/local/bin as the system
	directory for these shell scripts.

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.

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 system needs to know where to find its binaries.  This can be done
either by creating an /etc/passwd entry in which "hermes" has as its home
directory the directory in which this file resides (so that this file would be
~hermes/INSTALLATION), or by setting the environment variable HROOTDIR to be
the directory that contains this file.

III. Install Shell Scripts

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

If you are installing Hermes on an IBM RT/PC running ACIS 4.3, a Sun 4
workstation running SunOS 4.0 or greater, or an IBM RISCSystem/6000
workstation running AIXv3.1, precompiled binaries are included in
hermes/mbin.

The hermes interpreter (hermi) and compiler front-end (hermes) are run from
shell scripts provided in hermes/sysbin.  Connect to 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 any other system, you will have to compile the Hermes system.
See below.

IV. Reducing disk space usage

We are currently working on steps to reduce the size of the Hermes
machine-independent binary files.  In the meantime, some space
reduction can be achieved with the machine-dependent executables.
These files reside in subdirectories of hermes/mbin.

1. You probably will not need any of the files "chgram", "asm", or
"hermes" in any of the subdirectories of mbin.  These programs are
used in various parts of the Hermes system build procedure and should
not be needed for normal Hermes program development.  Even if you
anticipate performing builds in the future, the build procedure can
reproduce these files as needed.

2. Stripping the executables will free a substantial amount of space.
We distribute the programs with symbols and debugging information (as
generated by the "-g" c compiler switch), so that if problems arise
debuggers can be used to help with diagnosis.  We recommend that the
executables be left unstripped, but if disk space is tight for you,
this is a valid step.


V. Start Using Hermes

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

	hermi cache shell

will start the interpreter and run a shell from which you can compile Hermes
programs.


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. Make a Big Yacc (if yours isn't big enough)

The main nuisance in compiling Hermes is that its grammar requires
more space than some yaccs provide.  It may be necessary to create a
version of yacc called bigyacc with larger internal tables.  Try
running the make with the normal yacc, and resort to this procedure if
yacc fails on fegram.y for lack of space.  We plan to make the parser
work with bison or other yacc work-alike, which should circumvent this
problem, but have not done so yet.  Normal yacc, with a command-line
option to expand certain tables, is known to work on the IBM RISC
System/6000 running AIX 3.1 and on Sun3 and Sun4 workstations running
SunOS 4.0 or greater.

If your initial build attempt fails in yacc, you'll need to build a
bigyacc and change the following line in hermes/fe/Makefile:

	YACC	=	yacc -Nm50000

becomes

	YACC    =	bigyacc


To make bigyacc, in the Berekeley 4.3 version of yacc, the files that
must be changed are dextern and files.  dextern must have the
following added:

	# ifdef REALLYHUGE
	# define ACTSIZE 12000
	# define MEMSIZE 30000
	# define NSTATES 10000
	# define NTERMS 300
	# define NPROD 1000
	# define NNONTERM 600
	# define TEMPSIZE 10000
	# define CNAMSZ 10000
	# define LSETSIZE 1000
	# define WSETSIZE 350
	# endif

and the file files must have the line

	#define REALLYHUGE

II. Perform Make Includes Manually (if your make lacks "include")

The Hermes makefiles are written assuming that there is an "include" directive
that is understood by make.  If this is not the case, you will have to convert
the Makefile's by connecting to the top-level (hermes) directory and issuing

	% make/fixinclude

This will run a sed script which converts the Makefile's in all of the C code
directories into a file called Mkfile that includes the file 
hermes/make/includefile.  For "make" commands in what follows, you should
substitute "make -f Mkfile".

Note that makefiles for Hermes code are not fixed by this shell script.  If
you change the Hermes code, you will have to handle the includes manually.

III. Run Make

At this point, you should be able to build the binaries by connecting to the
top-level hermes directory (say it's called /u/hermes) and issuing:

	make HROOT=/u/hermes MTYPE=yourarch interpboot

This will recursively invoke make in the C directories and build an
interpreter.  "yourarch" should be the result of executing the arch command,
which gives the name of your machine architecture, such as bsdrt or sun4.

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, and it has been run through lint
(although lint "errors" remain, we have checked the results to make sure none
of them have real consequences).


IV. Make window support

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

	make HROOT=/u/hermes MTYPE=yourarch sunwindow

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

	make HROOT=/u/hermes MTYPE=yourarch xwindow


Direct questions about porting to hermes@ibm.com.

