This is HeNCE, version 1.2

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

HeNCE has been tested with both pvm version 2.3.4 and 2.4.0 (the
current version).  WARNING: pvm 2.3.4 and pvm 2.4.0 cannot talk to
each other.  You therefore need to be running the same version of pvm
on each of your machines.

2.  Which machines does HeNCE run on?

HeNCE has three main portions: htool (the X windows interface), master
(the "executioner", or scheduler) and the libraries that must be
linked with each node program.  

* 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.
    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.  (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.  Users of AIX version 3.2 MAY be able to
use the (X11R4-basaed) libraries supplied with that version of
AIX, but we haven't tried it.

In general, htool requires either X11R4 or X11R5 include files and
libraries, and at least an X11R3-based server.  The imake program and
support files, also included with X11, are required to build htool.
The HeNCE libraries and executioner 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.  
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.

[*] On a Sequent, you may have to add "HOME=$HOME" to each "make"
command line, if the definitions in your imake.defs file use the
$(HOME) variable.  (e.g. "make Makefiles HOME=$HOME", "make clean
HOME=$HOME", "make HOME=$HOME", and "make install HOME=$HOME").  On
other machines, make inherits this variable from your environment.

* 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.
In particular:

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".
			Normally this should be "$(HOME)/pvm/$(ARCH)", unless 
			you've changed it in the pvm source code.  This 
			should match 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.
			
As an example, one of the authors of htool (username "moore") has the 
following in his .Xdefaults file:

htool.includeDir: $(HOME)/src/Hence/master/include
htool.pvmHostFile: ~/.hence_pvm_hosts

The file ~/.hence_pvm_hosts contains the following:

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

These entries are necessary to 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.  Make, on the other hand, doesn't usually
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.

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.
