		    Building a GENESIS Distribution
		      May 27, 2003 (version 2.2.1)

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

You must be running X11R5 or X11R6 on a Sun SPARC (SunOS 4.x or Solaris
2.x), Linux on an Intel x86 PC (Linux, FreeBSD), SGI (IRIX 4.x, 5.x or 6.x)
or IBM SP2.  Users have also successfully compiled GENESIS on Macintoshes
running LinuxPPC, but our experience with this platform is limited.
Experimental versions of GENESIS for Mac OS X are available through the
GENESIS Users Group, BABEL.  We welcome feedback on experiences with these
platforms.  Other platforms may be capable of running GENESIS, but the
software has not been tested by the GENESIS developers outside of these
environments.  We offer no guarantees on hardware 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 (it is free).

The GENESIS distribution may be installed in whatever directory is most
convenient.  The distributed compressed tar file unpacks to produce the
directory named "genesis" and its subdirectories.  In the instructions
that follow, we refer to the genesis directory as the "installation
directory".  For example, if you unpack the distribution in /usr/local
(as is often done to make GENESIS accessible to multiple users on a
single computer), the installation directory will be /usr/local/genesis.
In what follows, directory and file names are given relative to the
installation directory.  Thus, the file you are reading 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
to uncomment 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
compilation and installation to occur.

Instructions about what must be modified in src/Makefile are included at
the beginning of the file.

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 are using a Sun Microsystems workstation and have
fully installed the OpenWindows package (which is the vendor-supplied
implementation of the X Window System on this platform), 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, the
script language of GENESIS.  If your system does not have yacc or lex or
GENESIS does not compile properly due to problems with the code
generated by yacc or lex, your best bet is to obtain the GNU versions of
these programs (bison and flex) from the anonymous FTP site at
ftp.gnu.org as well as other locations.  On ftp.gnu.org, 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 GNU flex instead of the SGI lex.

BUILDING THE DISTRIBUTION:

	From the src directory type:

		make clean
		make > & ! 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
	(nxgenesis), type "make nxall".  If you have previously built
	genesis with "make" or "make all", do a "make clean" before building
	nxgenesis.  To compile a minimum version of GENESIS with none of the
	object libraries included (mingenesis), type "make minall".
	
INSTALLATION:
	
	After a successful compile, the distribution can be installed by
	typing:

		make install
		(or for nxgenesis "make nxinstall")

	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.  The "convert" program will be installed
	in the subdirectory "bin" of the installation directory.  This
	"bin" subdirectory is for standalone programs that are used with
	GENESIS.  You may move the programs to another location, such as
	one that is on your shell's command search path, but be sure
	that the programs names do not conflict with other existing
	programs on your computer system.

	Finally, type:

		make clean

	to remove temporary files which were created during the compilation.

        Next, copy the .simrc file to your home directory.  .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.

        The .simrc file created after the "make install" step should have the
        correct path names to scripts needed by GENESIS.  If you should move
        the genesis directory tree from where it was originally installed
        to someplace else, you will have to edit this file.  Note that it
        requires full pathnames, e.g "/home/joeuser/genesis/startup", NOT
        "~joeuser/genesis/startup".

        Finally, add the installation directory to your path.  For example,
        if the installation directory is /usr/local/genesis and your shell
        is tcsh or csh, use:

                set path=($path /usr/local/genesis)

        If you are using bash as your shell, use

                PATH=$PATH:/usr/local/genesis

        These lines should be added to your .cshrc or .tcshrc file (for
        csh/tcsh) or your .bashrc (for bash) in your home directory.

PROBLEMS COMPILING GENESIS:

In general, if the compile fails to end with the message "Full GENESIS
Compiled -- All Done", search the "make.out" file for the first mention of
"Error" (other than the compilation of "Error.c") and look for the cause of
the failure.  This will likely cause another Error message at the end of
the compile that will be less useful in diagnosing the problem.
Most problems in compiling GENESIS arise from these sources:

(1) You have not properly set the various compiler options in the Makefile.
    Check the the comments in the Makefile for your operating system.

(2) Some necessary library or directory of include files (e.g. the X11
    libraries) has been installed in a non-standard place on your system,
    or were not installed.  For example, be sure that all the C and X11
    development libraries and tools have been installed.  If a file or
    library is not being found during the make, look through the make.out
    file to find out which library is not being found.  After you have
    determined where it actually is, or have installed it, make any needed
    changes to the path given in XLIB, XINCLUDE, or LIBS.  You may have to
    specify an additional library search path with the "-L" option, for
    example "LIBS= $(LEXLIB) -lm -L/usr/pubsw/lib"

(3) New versions of the operating system may require changes in the GENESIS
    source code or Makefile options.  If you do not find a fix in the
    Bug-fixes directory on the GENESIS web site, please give us as much
    information as posssible about the error messages and your operating
    system.  You may send detailed reports of problems to
    genesis@genesis-sim.org.  If we are not able to help, and you are a
    member of BABEL, a short summary posted to babelnews may elicit a
    response from someone else who has encountered a similar problem.

	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.

        Sun Solaris with the GCC compiler: There have been reports
	that GCC versions 3.x produce errors when the code_g program
	is compiled using opimization level O2.  If you encounter this
	problem, change the CFLAGS line to read
	'CFLAGS=-O -DBIGENDIAN'.

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.

        Problems with XODUS colors:  By default, XODUS widgets should
        have a LightSteelBlue background, with black foreground (text
        and graphics).  If you are getting something else (or want to
        change these defaults), you can use the Xdefaults.example
        file described above.

        FreeBSD users:  Recent versions of FreeBSD (ver. 4.3) will run
	GENESIS simulations and accept input from XODUS dialog boxes, but
	will not accept input at the genesis prompt in the terminal
	window.  At present, we do not have a solution for this problem.

TESTING THE DISTRIBUTION:

        After a successful installation, the distribution can be tested by
        cd'ing to Scripts/{neuron, squid, neurokit, 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 as
        described above, before running any of the demos.
