This is HeNCE, version 1.3

***** Instructions for the Impatient *****

The following command will suffice to compile HeNCE on many systems:

xmkmf ; make Makefiles ; make clean ; make

This assumes: 

(1) you have MIT X11R4 or X11R5 installed on your system, 
(2) the X11 bin directory (containing imake and xmkmf) is in your search path,
(3) your machine is one of those recognized by the imake.defs file (Sun/3, 
    Sun/4, IBM RS/6000, DecStation, HP Snake), and
(4) you have the latest version of pvm (currently 2.4.1) compiled
    and installed - the libpvm.a file should be in ~/pvm/$(ARCH)/libpvm.a,
    where $(ARCH) is the pvm architecture name of your machine.

Once you get this to work, "make install" will install the HeNCE
binaries in pre-determined locations.  These are:

* programs to be run from pvm go in ~/pvm/$(ARCH)  (This is what pvm
  expects by default.)
* the HeNCE library routines go in ~/hence/$(ARCH)
* the HeNCE include files go in ~/hence/include
* HeNCE programs (htool, master, mkwrap, pvmrsh) go in ~/bin.$(ARCH)
  (THIS DIRECTORY MUST BE ADDED TO YOUR PATH BEFORE YOU RUN htool).

If you want to change any of these before installing HeNCE, edit
"imake.defs" and run "xmkmf" and "make Makefiles" again before running
"make install".

Note that if you have some perversion of MIT X windows (like
DecWindows, AIX Windows, or OpenWindows), the simple instructions may
not work.  Most vendors haven't yet learned to include the basic set
of MIT libraries, include files, and configuration information
necessary to compile X windows programs.

So, if the simple instructions don't work, read on...

***** End of Instructions for the Impatient *****





How to compile and install HeNCE

1.  Before you can compile and link HeNCE, you need to have a current
copy of pvm.  To find out how to get a copy of pvm, type:

echo send index from pvm | mail netlib@ornl.gov

The current version of pvm (as of this writing) is 2.4.1.  Although
HeNCE will work with older versions of pvm also, it is important that
you be using the same version of pvm on each machine.  We therefore
recommend that you install the latest version of pvm on all of your
machines.

Note: pvm 3.0 is currently under development and may be released
before the next version of HeNCE is released.  HeNCE 1.3 will not work
with pvm 3.0.  You need pvm 2.4.x instead, (where x >= 1).


2.  Which machines does HeNCE run on?

HeNCE has three main portions: (1) "htool" (the X windows interface),
(2) "master" (the "executioner", that interprets HeNCE graphs and
schedules the execution of computational nodes), and (3) the libraries
that interface with each program.  In addition, there is a "mkwrap"
utility that is used to generate wrappers for HeNCE node programs, and
a "pvmrsh" program that allows HeNCE programs to be compiled, linked,
and installed on all of the systems in your virtual machine.

* To compile and link htool, you MUST have include files and libraries 
from MIT X windows version 11, release 4 or later.  However, the compiled 
htool runs fine with release 3 based servers, such as those supplied with 
AIX 3.1 and Ultrix 4.1.

* In general, the "master" program (HeNCE executioner), and libraries
can be built on any machine that supports pvm, though minor modifications
may be required.

You only need to install htool and master on the machine where you
initiate HeNCE programs.  You will need to compile and install the
node libraries on at least one machine of every architecture that you
use, so you will have a place to build HeNCE node programs for that
architecture.

HeNCE (the entire system) has been at least minimally tested, and can be 
expected to build without too much effort, on the following machines:

    PVM name    Machine					Notes
    --------    -------					-----
    CRAY        Cray					1
    HP9K        HP 9000 (Snake)				2
    NEXT        NeXT					3
    PMAX        Dec/Mips arch (3100, 5000, etc.)	4
    RIOS        IBM/RS6000				5
    SUN3        Sun 3
    SUN4        Sun 4, 4c, sparc, etc.			6
    SYMM        Sequent Symmetry

[1]  Earlier, "beta" versions of HeNCE have compiled and run on CRAYs.
We would expect this version to work also, but have not actually tested
it.

[2]  Requires pvm 2.4.0 or later.  (pvm 2.3.4 did not support HPs)

[3]  The NeXT version of HeNCE has been built and tested with the X
include files and libraries supplied with Pencomm's "coXist" X server.  
Minor modifications may be required to get HeNCE to compile with other
X windows implementations.

[4]  On Ultrix, you MUST either have MIT X windows (not DECWindows)
installed, OR have the "Unsupported X11 Components" software subset
loaded, in order to compile HeNCE.  The include files supplied with
vanilla DECWindows are incompatible with those supplied by MIT and
required by HeNCE.

[5] If you are running AIX version 3.1, you MUST have installed MIT X
windows (preferably X11R5) include files and libraries in order to
compile HeNCE.  HeNCE WILL NOT compile with the (X11R3-based) X
windows libraries supplied with IBM with release 3.1 of AIX.  

HeNCE does compile and run under AIX v3.2, but IBM doesn't supply
everything you need ready-made.  See the file READ-ME.AIX for 
instructions as to how to compile HeNCE in this environment.

[6] HeNCE prefers to compile under X11R4 or X11R5.  However, we have
gotten HeNCE running under OpenWindows 3.0.  See the file READ-ME.SunOS
for instructions as to how to compile HeNCE in this environment.


In general, htool requires either X11R4 or X11R5 include files and
libraries, and at least an X11R3-based server.  The programs "xmkmf"
and "imake" and their support files, also included with X11, are
required to build htool.  The HeNCE libraries, executioner, and the
remote compilation facility should port pretty easily to any machine
that supports pvm.

3.  Compiling and installing HeNCE

* If you have X windows

If you have a current copy of the X window system, version 11, release
4 or later on your machines, you should be able to compile HeNCE with the
following steps:

a.  Make sure the directory containing the X11 "binary" programs
    (/usr/bin/X11 on many systems) is included in your PATH environment
    variable.  This is so you can find "imake" and "xmkmf" programs.

b.  Change directory to the top-level directory of the HeNCE tree.  
Make the "imake.defs" file writable by typing "chmod +w imake.defs".
Edit the "imake.defs" file and set the following:

LIBPVM	set this to the location of the file "libpvm.a" that resulted from
	compiling pvm.  If you are using a heterogeneous network of UNIX 
	machines that share the same file systems, you will want to use $(ARCH)
	in the name; that name will get expanded into the pvm architecture
	name when you do a "make install".

	Example:	LIBPVM=$(HOME)/pvm/$(ARCH)/libpvm.a

HENCELIBDIR	set this to the directory where you want the HeNCE libraries
	to be installed.

	Example:	HENCELIBDIR=$(HOME)/hence/$(ARCH)

BINDIR	set this to the directory where you want HeNCE programs ("htool",
	"master", and "mkwrap") to be installed.  This directory should be
	listed in your PATH variable so htool can find these programs.

	Example:	BINDIR=$(HOME)/bin.$(ARCH)

If your system is NOT one of those listed above, you will also need to
modify the section of imake.defs that tries to figure out what kind of
machine you are running on.  In particular, you need to set the ARCH
variable to match the pvm name for your machine's architecture.  (See
the file "doc/Arches" in the pvm distribution for a current list.)  On
some machines, you may also need to set the HENCE_DEFINES variable to
add extra arguments to the command that make uses to compile and link
C programs.

c.  To build the top-level Makefile, type "xmkmf".  If the "xmkmf" program
    does not exist on your system, type:

    imake -DUseInstalled -Iconfigdir

    where "configdir" is the directory containing the X11 configuration
    files for your system (e.g. /usr/lib/X11/config).

(On a CRAY, if you are running SCC as your default C compiler, you need
to set the environment variable IMAKECPP to point to the old-style 
C preprocessor.  Normally this is "/lib/pcpp".  Do this BEFORE running
"xmkmf")

d.  Having built the top-level Makefile, now build all of the Makefiles
    for sub directories by typing "make Makefiles".

e.  If you have old object (.o) files left over from a previous HeNCE
    compilation on a different system, type "make clean" to remove them.

f.  Now simply type "make" which should compile everything.

g.  "make install" should install things.

    Make sure the directories named in LIBPVM, HENCELIBDIR, and BINDIR in
    imake.defs already exist before typing "make install".  Due to a bug 
    in the Imakefiles, the automagic directory-create-if-it-doesn't-exist 
    code is broken.

* If you don't have X windows

If you don't have X windows on a particular machine, you can't compile
htool there.  However, you can compile the HeNCE node libraries and
use this machine in your HeNCE-based computations.  Do this as
follows:

a.  cd master

b.  edit the Makefile.libs file as necessary to set the ARCH and HENCELIBDIR
    variables as appropriate for your system.

c.  type "make -f Makefile.libs" to compile

d.  type "make -f Makefile.libs install" to install

You may be able to compile the HeNCE executioner ("master") by typing 
"make -f Makefile.vanilla", but nobody has tried this recently.

The "mkwrap" program, which is used to build the glue ("wrapper") between
the C or FORTRAN function that implements a HeNCE node program, and the
HeNCE libraries, is in the "mkwrap" directory.  Again, try using
"make -f Makefile.vanilla" if you can't use the imake-based compilation
system.


4.  Things you need to know before running HeNCE

htool needs to have some X resources defined before it will run well.

NOTE: The best way to define most X resources for HeNCE is to put them
in a file named ~/htool.  If you run htool on different machines that
do not share files, each machine can have its own ~/htool file that
specifies the defaults for that machine.

Some resources (such as colors or fonts) may be specific to a
particular X windows display.  These resources are best set in
~/.Xdefaults or via the "xrdb" command.

Here is a description of some resources you might want to set:

htool.includeDir *	the directory that contains the include files
			needed by HeNCE node programs.  Set this to point
			to the subdirectory "master/include" from the HeNCE 
			source code.  If you don't set this resource, htool
			will assume you've made a copy of the HeNCE include
			files in "$(HOME)/hence/include".  "htool" will copy 
			whatever string you put here into the Makefiles it 
			generates and uses to compile node programs.

htool.pvmLib *		the path of the libpvm.a file.  "htool" also copies
			this into the Makefiles it generates to compile
			node programs.  This should match the LIBPVM
			define in "imake.defs".

htool.binDir *		the directory where the compiled node programs should
			be installed.  This also gets copied into the Makefiles
			for the node programs and is used by "make install".
			By default, PVM expects to find such programs in 
			"$(HOME)/pvm/$(ARCH)", so the htool.binDir resource
			should be set to "$(HOME)/pvm/$(ARCH)", unless 
			you've changed it in the PVM source code.  This 
			is NOT the same as the BINDIR define in "imake.defs".

htool.henceLibDir *	the directory where the HeNCE libraries (used by
			HeNCE node programs) are installed.  "htool" uses
			these resources to build Makefiles that compile 
			HeNCE node programs.  This should match the
			HENCELIBDIR define in "imake.defs".

htool.xtermCommand	the pathname of the "xterm" command (or equivalent)
			on your system.  This can be a full pathname if
			necessary, or simply "xterm" if the directory
			containing that program is already in your path.

htool.pvmHostFile	Whenever it starts pvm, htool builds a pvm hosts file
			that contains a line for each machine in htool's 
			current cost matrix.  If you need to override pvm's
			defaults for one or more machines (i.e. you have
			a different login on that machine, or pvmd on that
			machine is in some location besides /tmp/pvm/pvmd),
			you may put host entries for those machines in a file
			and set the pvmHostFile resource to point to this file.
			See the pvm documentation for the format of the host
			file.
			
Example:

One of the authors of htool (username "moore") has the following in
his ~/htool file:

htool.pvmHostFile:      ~/.htool_pvm_hosts

The file ~/.htool_pvm_hosts contains the following:

castor.epm.ornl.gov	lo=kmoore
msr.epm.ornl.gov	lo=kmoore

These entries are necessary so that htool will tell pvm that it should
login as user "kmoore" on those machines rather than user "moore".


Note on use of ~ versus $(HOME) in X resources: For resources that
correspond to filenames, htool understands the ~ and ~user conventions
from the C-Shell.  So ~/foo refers to file foo in your home directory
and ~joe/foo refers to file foo in joe's home directory.  These
filenames get expanded (replace with full pathnames) when htool starts
up, so you can use ~ whenever you need to refer to a file relative to
someone's home directory.  

On the other hand, most versions of "make" don't understand the tilde
convention, but it does effectively interpret $(HOME) as the location
of your home directory.  So you want to use $(HOME) for htool's X
resources that correspond to Makefile variables (those with *'s in the
list above), and tildes for other filenames like the pvmHostFile
resource.

There are other resources you can also set to change how htool works
and/or how it looks on your screen.  See the HeNCE User's Guide for a
more complete list.


5.  Bug Reports

Development on HeNCE is a continuing process.  We would appreciate
reports on bugs that you find in the HeNCE software, and comments
about the HeNCE facility in general and how we can improve it.
Send these via email to the HeNCE developers at <hence@msr.epm.ornl.gov>.

In any bug report, please include the following:

* what kind of machine you are running HeNCE on
* what version of X Windows you are using (both libraries and display server,
  if they are different)  For instance, you might be using MIT's libraries
  but running htool from an X terminal.
* what version of HeNCE you are running.  Check the file patchlevel.h
  in the htool and master directories.
* a copy of your HeNCE graph (filename.gr), and if it seems necessary,
  the source code to your node programs.
* a precise set of steps necessary to make HeNCE exhibit the bug
* anything else you think is relevant

(We want to hear about bugs even if you can't provide all of the above
information, but it's often difficult to know if the bug is fixed without
a repeatable test case.)

The file "buglist", available from netlib, will include a list of
HeNCE bugs we know about, and those we think are fixed.  To get
a copy of this, type:

send buglist from hence | mail netlib@ornl.gov


6.  Acknowledgement

Htool's file selector dialog box makes use of a *modified* version of
the regular expression package developed by Henry Spencer of the
University of Toronto.  The files regexp.c and regsub.c in the
directory "htool" are Copyright (c) 1986 by University of Toronto,
and may be redistributed only under the terms described in those files.
If you wish to use this package in other software, we recommend that
you get the unmodified version, available via anonymous ftp from
cs.toronto.edu, directory pub, files regexp.README and regexp.shar.Z


7.  Examples

The "demo*" directories contain various example HeNCE programs.
Each directory has a README file that describes what the demo is.
Many of these demos are variations on a Mandelbrot generator, just
to illustrate various features of HeNCE.  The directory demo0
contains a program called xpx.c that can be used to display the
output file from one of these programs on an X window (if you have
a color display).

The directory demo6 contains the dot product program from the
HeNCE User's Guide.

We are working on better examples and will make them available via
netlib when we have them ready.
