                              Nexus
                           Version 4.2


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 University
of Southern California's Information Sciences Institute. Other
partners in Nexus development include The Aerospace Corporation, and
the High-Performance Computing Lab at Northern Illinois University.

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 the interface specification, and
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 Nexus without threads (NexusLite)
	--enable-64bit
		SGI Irix 6.x only, compile to 64-bit object code (cc -64)
	--enable-sharedlib
		Build shared instead of static libraries.
		See note below on using shared libraries.
	--prefix=/some/install/path
		Set the installation directory
	--target=paragon
		Cross compiler for the Paragon

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
	DEC Unix 3.2
	IBM SP (AIX4 & AIX3, --without-threads only)
	Intel Paragon (--target=paragon, --without-threads --without-udp only)


Shared Libraries
----------------

When using shared libraries, some machines require that the shared
libraries be in a particular path.  That path usually contains
standard directories such as /lib and /usr/lib.  However, if you wish
to use a shared library that is not in that standard path, a special
environment variable must often be set in order for the system to find
your shared library.  The specific environment variable can often be
found in the man page for ld.  Here are some known ones:
	Solaris	2.x	LD_LIBRARY_PATH
	Irix 6.x	LD_LIBRARY_PATH


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

There is a test program in nexus/test/test_nx.c which exercises much of the
Nexus interface.  To build it, do:
	cd nexus/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_nx.c there are a variety of #defines
to turn on and off testing of various portions of the system.


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
		3) Add -DDEF_RR to Makefile.SunOS
		4) Remove __malloc_initialized = 0; from pthread_init()
		   in src/pthread.c

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.

IBM AIX 3.2.x
	This requires IBM DCE threads.

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

