                              Nexus
                           Version 4.0b4


About Nexus
-----------

Nexus is a portable library providing the multithreading,
communication, and resource management facilities required to
implement advanced languages, libraries, and applications in
heterogeneous parallel and distributed computing environments. Its
interface provides multiple threads of control, dynamic processor
acquisition, dynamic address space creation, a global memory model via
interprocessor references, and asynchronous events. Its implementation
supports multiple communication protocols and resource
characterization mechanisms that allow automatic selection of optimal
protocols.

Nexus is intended for use by compiler writers and library developers,
rather than application programmers. Systems that rely on Nexus
mechanisms include compilers for the parallel languages CC++ and
Fortran~M; the implementation of the Message Passing Interface (MPI)
standard used in the I-WAY wide-area computing experiment; nPerl, a
communication library for the Perl scripting language; the CAVEcomm
library for the CAVE virtual reality environment; and MTIO, a
multithreaded I/O library. Finally, the Globus project builds on Nexus
mechanisms to provide software infrastructure for high-performance
distributed computing.

Nexus is a joint project of Argonne National Laboratory and USC
Information Sciences Institute. The Aerospace Corporation is also a
partner in Nexus development.

For more information on Nexus (including the Nexus 4.0 specification,
API documentation, and other useful material), see the World Wide Web at:
	http://www.mcs.anl.gov/nexus

Also, several Nexus related documents can be gotten by anonymous ftp from:
	ftp://ftp.mcs.anl.gov/pub/nexus/reports

Both of these locations contain a User's Guide, and interface
specification, and a papers describing various aspects of Nexus.

If you have questions, please send them to:
	nexus@mcs.anl.gov

If you have bug reports, please send them to:
	nexus-bugs@mcs.anl.gov

There is also a Nexus user's mailing list, "nexus-users@mcs.anl.gov",
which is for Nexus related announcements and discussions.  To be added
to this list, send mail to "nexus-users-request@mcs.anl.gov" with a
message body of "subscribe".


Building Nexus
--------------

Nexus can be automatically configured, built, and installed on a wide
variety of Unix based workstations and parallel computers.  For a
default installation, do:
	./configure
	make
	make install

To see a complete list of available configuration options, run:
	./configure --help

Particularly useful options include:
	--enable-debug
		Compile Nexus with debugging
	--without-threads
		Compile NexusLite (Nexus without threads).
	--enable-64bit
		SGI Irix 6.x only, compile to 64-bit object code (cc -64)
	--prefix=/some/install/path
		Set the installation directory

Nexus can also be built from within a shadow directory.  This allows
multiple configurations and/or architectures to be built from the same
source tree.  For example, to build the debug version of Nexus in a
shadow directory, you can do:
	mkdir BUILD
	mkdir BUILD/debug
	cd BUILD/debug
	../../configure --enable-debug
	make
	make install

Nexus has been tested on the follow architectures (see below for
architecture specific build hints):
	Solaris 2.5.1
	SunOS 4.1.4
	SGI IRIX 6.2
	IBM AIX 3.2.5
	IBM AIX 4.1.4
	DEC Unix 4.0


Testing Nexus
-------------

There is a test program in test/test_nx.c which exercises much of the
Nexus interface.  To build it, do:
	cd test
	make test_nx
	./test_nx

When run, this test will print out many messages.  However, if it runs
to completion and does not print out any messages with "ERROR" in them,
then it ran successfully.

Near the beginning of test/test_nx.c there are a variety of #defines
to turn on and off testing of various portions of the system.

Note: The other test/test_*.c programs have NOT yet been updated from
nexus-3.0 to nexus-4.0, so they will not compile or run.


Some Requirements
-----------------

SunOS 4.1.x
	This requires a slightly modified version of Florida State
	University pthreads package, which can be obtained from:
		ftp://ftp.cs.fsu.edu/pub/PART/PTHREADS
	The required modifications are:
		1) Comment out the start_float() functions in disp.c
		   and p_aux.S.  (This means pthread_init() must be
		   called explicitly, rather than implicitly from crt0.o.)
		2) Remove -DIO from Makefile.SunOS
	If you have ot installed the FSU pthreads, you can build
	it against the Quickthreads library that is included in the
	release.  However, you must first build libqt.a before
	running the configure.  If you do not, the configure will
	fail with a wierd error about cross-compilation.
	Warning: nexus-4.0beta using Quickthreads has not been thoroughly 
	tested.

Solaris 2.x
	You cannot use /usr/ucb/cc to build Nexus, as this compiler
	does not support ANSI C preprocessor syntax.  You need to use
	the SunPro compiler directly.  This can be done by doing
	either of the folling before running configure;
		- set your path to use the proper compiler
		- set the CC environment variable to the right value, i.e:
			setenv CC /opt/SUNWspro/bin/cc

SGI IRIX 6.x:
	This requires SGI pthreads.
	The --enable-64bit flag can be passed to configure to have
	Nexus built using "cc -64", which produced 64-bit object code.

SGI IRIX 5.3:
	This requires Quickthreads to be installed before Nexus.
	Quickthreads is included in the quickthreads subdirectory.
	See quickthreads/INSTALL for instructions on its installation.
	Use a *machtype* of "mips-irix5".

IBM AIX 3.2.x
	This requires IBM DCE threads.

HP-UX 9.x
	This requires HP DCE threads.

