Building a GENESIS Distribution September 11, 2000 (version 2.2) 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). Users have also successfully compiled GENESIS on DEC Alphas (OSF1 v2, v3, and UNIX 4), IBM RS6000s (AIX), and HPs (HPUX), but our experience with these platforms is limited. We have received reports of the use of GENESIS on the Power Macintosh with Linux for the Power PC, but have not tested it ourselves. 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. 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= Specify the directory in which the X11 libraries reside. XINCLUDE= 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, 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. 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. 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. 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 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.