-- (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 (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@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 scripts in system directory? Three shell scripts, named "hermes", "hparse", and "hsh" 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. 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. .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. 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 Hermes shell scripts during the tape installation procedure, you may manually install the shell scripts at a later time as follows. The hermes interpreter (hermes) and standalone parser (hparse) are run from shell scripts provided in hermes/sysbin. Another script (hsh) is an abbreviation for "hermes cache shell". This is the way most users will want to run Hermes. To install the scripts, 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. 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", "construct", or "hparse" 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 can help. V. 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 cache shell will start the interpreter and run a shell from which you can compile Hermes programs. The "hsh" shell script discussed above is an abbreviation of the above command line. 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) One 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 or extend the make/fixinclude script. 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 newversion 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). In addition you may have problems with the Makefiles and your version of make. The following changes have been necessary for some of the ports; eventually they will be incorporated in a more general Makefile structure. 1. HP 9000 : a. The ld process requires a space between a -L option indicator and the library directory path. This is implemented in an alternate definition of LIBDIRS in make/includefile . b. A special Berkely Unix library is necessary - see the alternate definition of HPUXLIBS = -lBSD in make/includefile . c. When compiling the interpreter, one module requires the special flags -Wc,-Nw400 to allocate space needed during compilation. This is implemented by adding HANDFLAGS="-Wc,-Nw400" to the make command line. 2. Convex : a. The make interpreter does not process @if correctly. Change all occurences in the principle Makefile to @-if . b. The option -Nm5000 to the yacc process is not recognized. A bigyacc process was configured (see above) and must be called with the options -d -v on the porting machine, this is implemented by a change to fe/Makefile . 3. NeXT machine : a. The yacc process automatically allocates large tables as needed, and does not understand the option -Nm5000 . An alternate definition of YACC = yacc in fe/Makefile implements the fix. b. The env function is not implemented. Changing the definition of ENV to a null string in make/includefile implements the fix, since the system understands options of the form Name=String . Alternate definitions for other machines, such as the iris workstation appear in make/includefile as well . 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.