                       Building a GENESIS Distribution
			   August 15, 1997 (2.1)

This file contains information necessary to successfully build, install
and run GENESIS.  Please read the entire document carefully.

You must be running X11R4, X11R5, X11R6 on a Sun (SunOS 4.x or Solaris
2.x), DECstation (Ultrix), Silicon Graphics (Irix 4.x, 5.x or 6.x) or
x86 PC (Linux, FreeBSD).  DEC Alphas (OSF1 v2 and v3), IBM RS6000s
(AIX) and HPs (HPUX) have been successful in compiling and running,
though our experience is limited.  We have received reports of use of
GENESIS on the Power Macintosh with the current (ver. 2.1) developers
release of Mac Linux, but have not tested it ourselves.  We've had
consistent reports of problems compiling and running GENESIS on DEC
Alphas under the new UNIX 4 operating system specifically related to
X-Windows.  We welcome feedback on experiences with these platforms.
Other platforms may be capable of running GENESIS, but the software has
not been tested by Caltech outside of these environments.  No
guarantees on platforms or operating systems outside of these
parameters!   Note that all of our code has been built using X11 from
MIT.  In testing, GENESIS 2.x compiled and ran under the vendor
supplied X11 products.  Should you encounter problems with a vendor's
X11 product, we suggest you obtain the MIT distribution and install the
libraries (its free).

The GENESIS distribution may be installed in whatever directory is most
convenient.  The place where you unpack the distribution is the
installation directory.  In the instructions that follow, directory and
file names are given relative to the installation directory.  Thus,
this file is src/README.

To build the distribution follow the instructions below.   

REQUIRED MODIFICATIONS:

Make a copy of src/Makefile.dist to src/Makefile and edit src/Makefile
uncommenting the appropriate Makefile variables for your system.  Do
NOT edit the files called 'Makefile.machine-name' or rename them to
Makefile. It is critical that parameters be set correctly for a clean
compile and install to occur.

CUSTOM MODIFICATIONS:

If for some reason your X11 include and library files are located in
non-standard directories (e.g. not in /usr/include and /usr/lib) you
can set the following parameters in src/Makefile:

	XLIB=		<dir>
			Specify the directory in which the X11 libraries
			reside.

	XINCLUDE=	<dir>
			Specify the directory in which the X11 include
			hierarchy resides.  Note that the directory
			specified must have a subdirectory named X11 in
			which the include files reside.

For example, if you have openwin fully installed on your SUN, you can use
the following parameter settings:

	XLIB =		/usr/openwin/lib
	XINCLUDE =	/usr/openwin/include

to compile using openwin includes and libraries.  (Note the comments in
src/Makefile about using openwin.)


YACC AND LEX

GENESIS uses the yacc and lex programs to generate a parser for SLI.  If
your system does not have yacc or lex or the system does not compile
properly due to the yacc or lex generated code, the GNU versions of these
programs (bison and flex) may be obtained from the anonymous FTP site
at prep.ai.mit.edu as well as other locations.  On prep.ai.mit.edu the
current releases of bison and flex are in the /pub/gnu directory.
src/Makefile has instructions for using bison and flex.

SGI users NOTE: The SGI version of lex allocates a relatively small
input buffer of 200 characters.  If this buffer overflows, GENESIS
will exit.  This can happen with very long arguments to commands.
We have made changes elsewhere in the distribution to avoid this
situation.  However, should you encounter this you might consider
using the GNU flex.


BUILDING THE DISTRIBUTION:

	From the src directory type:

		make clean
		make all > & ! make.out &
		(or for the Bourne shell: make all > make.out 2>&1 & )


	This will take between 10 to 30 minutes, depending on machine
	type.   The compile process can be viewed by typing:

		tail -f make.out 	[ hit ^C to exit the tail ]

	If you want to build a version of GENESIS to be run without
	XODUS, type "make nxall".  To compile a minimum version of
	GENESIS with none of the object libraries included, type
	"make minall".
	
INSTALLATION:
	
	After a successful compile the distribution can be installed by 
	typing:

		make install

	This will copy all important files and binaries to the installation
	directory and the subdirectories startup, lib and include.  GENESIS
	initialization commands in .simrc will be modified to refer to the
	installation directory as part of the installation process.  Finally,
	type:

		make clean

	to remove temporary files which were created during the compilation.

KNOWN PROBLEMS RUNNING GENESIS:

	SGI users: if your X11 server is set up to default to a
	TrueColor visual and you get X protocol errors running GENESIS,
	try using the -defaultcolor option on the GENESIS command line.

	SGI and HP users: the default font used by some Irix and HPUX X
	windows implementations is too large for the widgets in many of
	the simulations.  You may modify this by setting X resources,
	as described in genesis/startup/Xdefaults.example.

	SUN Openwin users: you may need to add /usr/openwin/lib to the
	LD_LIBRARY_PATH environment variable when compiling and/or
	running GENESIS.  If when running GENESIS you get a complaint
	that libX11.so.4.2 can't be found (or something similar)
	LD_LIBRARY_PATH is likely to be the problem.

TESTING THE DISTRIBUTION:

	After a successful 'make install' the distribution can be
	tested by cd'ing to Scripts/{MultiCell, neurokit, squid or
	orient_tut} and following the directions found in the README
	files found in those directories.  Make sure that you've added
	the installation directory to your path and copied .simrc to
	your home directory before running any of the demos.  .simrc
	files from previous versions of GENESIS should be replaced by
	the one in the installation directory.  If you are using
	GENESIS without XODUS (nxgenesis) or a minimal version of
	GENESIS (mingenesis), copy .nxsimrc or .minsimrc to .simrc in
	your home directory.
