README.bindist

GENESIS 2.4 Binary Distribution README

Binary distributions of GENESIS are typically released shortly after
the public release of the source distribution. These instructions
refer to the installation of Cygwin, Linux, and OSX binaries in
the form of 'genesis-2.4-<os>-bin.tar.gz' files.

Binary distributions of GENESIS 2.4 for Debian (.deb) and Fedora
(.rpm) Linux should be available from the GENESIS web site shortly
after the November 2014 GENESIS 2.4 release. Distributions for Mac OS
and Cygwin should follow. Look for updated installation instructions
in the genesis-2.4/genesis directory of the binary distribution.

CONTENTS
    1  QUICK START
    2  INTRODUCTION
    3  INSTALLATION
       3.1  Unpacking
       3.2  Site-specific Setup
       3.3  Environment Variables
       3.4  Running GENESIS
       3.5  The GENESIS Neural Modeling Tutorials
    4  OPERATING SYSTEM SPECIFIC NOTES
       4.1  Cygwin
       4.2  Linux
       4.3  OSX Darwin
    5  PROBLEMS RUNNING GENESIS
       5.1  Floating Point Variation


1  QUICK START
    cd <install_directory>
    tar xzf genesis-2.4-<os>-bin.tar.gz
    cd genesis-2.4/genesis
    ./binsetup
    cp .simrc ~
    export PATH=$PATH:/usr/local/genesis-2.4/genesis   # use 'set' for csh

    If it didn't work, you'll have to read on...


2  INTRODUCTION

This distribution includes precompiled versions of both genesis (with XODUS,
dependent on X11 installation) and nxgenesis (non-X genesis, without the XODUS
GUI, hence no X11 dependence).

If you have a pre-2.0 version of GENESIS and some custom scripts you'd like to
keep, you can use the 'convert' utility in the bin directory to update your
scripts.

The genesis executables have been linked with certain versions of dynamic
libraries. These libraries must be available at run time. See the Operating
System Specific Notes below.  If have problems running this distribution or
want to compile your own version of GENESIS, please get the source distribution
from http://genesis-sim.org/GENESIS or http://sourceforge.net/projects/genesis-sim.


3  INSTALLATION

3.1  Unpacking

Pick the place where you want to install the "genesis" directory tree.
If you are making a system-wide installation as "root" user, /usr/local is a
good choice.  For a personal installation, without root privileges, you can use
your home directory ("~").  Change to this directory and extract the genesis
directory from the archive file, e.g. genesis-2.3-linux-bin.tar.gz.  For
example,

        cd /usr/local
        tar xvzf /mnt/cdrom/genesis-2.4-linux-bin.tar.gz

or from wherever you have it (e.g.~/downloads/genesis-2.r-linux-bin.tar.gz)


3.2  Site-specific Setup

A small setup script should be run to create a GENESIS initialization file
(.simrc) which is modified to reflect your installation directory.

        cd genesis-2.4/genesis
        ./binsetup

Then copy the resulting .simrc to your home directory.

        cp .simrc ~


3.3  Environment Variables

Finally, add the genesis directory to your search path, so that "genesis"
can be found from any directory.  If your login shell is bash, do this by
editing the .bashrc file in your home directory. For example, if you have
installed genesis in /usr/local, add this line:

        PATH=$PATH:/usr/local/genesis-2.4/genesis

If you are using tcsh or csh as your command shell, add

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

to your .tcsh or .csh file.


3.4  Running GENESIS

At this point, you are ready to try running GENESIS.  Change into the
directory genesis/Scripts and try some of the tutorials suggested in
the README file.

If you have any trouble with the installation or execution of GENESIS, read
the OS-specific notes below. If you still can't get it to work, please try
downloading and installing the source distribution.


3.5  The GENESIS Neural Modeling Tutorials

The genesis/Tutorials directory in the GENESIS distribution is provided as
a "place holder" for supplemental hypertext GENESIS modeling tutorials and
documentation, including the GENESIS Neural Modeling Tutorials package.
These are an evolving set of HTML tutorials intended to teach the process
of constructing biologically realistic neural models with the GENESIS
simulator. The latest version of this package is offered as a separate
download from the GENESIS web site, http://www.genesis-sim.org/GENESIS. The
downloaded file (Tutorials.tar.gz or Tutorials.zip) should be unpacked in
the genesis directory in order to augment the files that are provided there.
The "bare bones" version that is provided with the GENESIS distribution
includes a beginner's guide to UNIX/Linux commands that may be useful
for those who are new to the command line environment used by GENESIS.


4  OPERATING SYSTEM SPECIFIC NOTES

Statically linked binaries are no longer provided for GENESIS. The main reason
for this is that many modern systems can be configured in ways that make it 
impossible or impractical to provide static executables. In particular, system
libraries may have different dependencies based on the flavor or version of the
installed operating system.

So, the GENESIS executables have been linked against dynamic libraries creating
runtime dependencies as described below.

4.1  Cygwin

Cygwin provides a UNIX-like environment for Windows that will let you run
GENESIS and other UNIX programs that have been compiled to run under Cygwin.

Go to http://cygwin.com, and install it by downloading and running
setup-x86.exe (32-bit installation). This may be used with 64 bit MS Windows,
and is recommended over the less stable setup-x86_64.exe.

Running this will let you choose what to install and
then download it.

When using Cygwin Setup for the first time, the default is to install
a minimal subset of all available packages. If you want anything
beyond that, you will have to select it explicitly.  See
http://cygwin.com/packages/ for a searchable list of available
packages, or use cygcheck -p as described in the Cygwin User's Guide
at http://cygwin.com/cygwin-ug-net/using-utils.html#cygcheck.

To build GENESIS, you will need gcc, binutils, make and probably other
packages from the ``Devel'' category. Text editors can be found under
``Editors''. For more information about selecting packages to install,
and using Cygwin, consult the docmentation links at http://cygwin.com.

More information on installing and using X windows with Cygwin can be found
at http://x.cygwin.com/. 

GENESIS can be run under Windows with the Cygwin software installed. If you want
to run GENESIS with GUI capabilities, the X windows package must be installed
under Cygwin. The instructions below assume you want GUI capabilities. You
should be able to run non-graphical GENESIS (nxgenesis.exe) with a standard
Cygwin installation.

Graphical GENESIS requires the following packages (and all their dependencies):

    Package             Cygwin Category
    -------             ---------------
    coreutils           Base*
    sed                 Base
    X-startup-scripts   X11
    xorg-x11-base       X11

*Recent versions of Cygwin roll textutils and fileutils into coreutils.
If you have an older Cygwin, you may need to install these packages; they are
in the Base category.

Go to the Cygwin site (http://www.cygwin.com) and use the "Install or update 
now!" link to install the setup.exe program.  Running setup.exe will
lead you through several dialogs and eventually to a list of packages. If there
is a version number displayed next to the package under the 'Current' column,
that package is already installed. Please see the Cygwin website for further
instructions on using the setup.exe program.

More information on installing and using X windows with Cygwin can be found in
the Cygwin/X User's Guide at http://x.cygwin.com/docs/ug/cygwin-x-ug.html

You will probably want to install a text editor for editing GENESIS simulation
scripts or modifying configuration files.  These are found in the Editors
category.  Text files that are created by UNIX have a different
End-Of-Line terminator than Windows text files.  For that reason, it is best
to use a UNIX editor instead of Windows Notepad for editing GENESIS files.  If
you are more familiar with Windows than UNIX, choose "nedit".  This is an
easy-to-use editor with built-in help that will be familiar to users of
Windows Notepad.  If you are a UNIX user, you may prefer to install emacs or
vi (Vim).

4.2  Linux

The linux executables have been linked against gnu libc6 (aka glibc2). Certain
libraries will need to be available at run time. Non-graphical GENESIS
(nxgenesis) depends on:
    libm.so.6
    libncurses.so.5
    libc.so.6
    libgpm.so.1

Graphical GENESIS (genesis) needs these additional libraries:
    libXt.so.6
    libX11.so.6
    libdl.so.2

    and possibly (but unlikely):
    libSM.so.6
    libICE.so.6

Given the variety of Linuces available each with it's own package management
system, there's no standard process for installing these libraries. Try to
get packages from your OS vendor's web site. You'll need libc6 and X.org.


4.3  OSX Darwin

The OSX executables were built using Xcode 2.2 tools, based on GCC 4.0.

The binary distribution of GENESIS will only work with OSX 10.8 and higher,
on intel architectures.  You'll have to compile the package
from source to run on earlier versions or on the PPC architecture.

The non-graphical version of GENESIS (nxgenesis) should run on any
standard OSX installation. Graphical GENESIS (genesis) relies on the
X11 libraries for it's graphical user interface (GUI). An X11 server
needs to be started before graphical GENESIS can be run.  If you can't
locate the X11 application (perhaps in Applications->Utilities->X11),
see: https://developer.apple.com/opensource/ or the XQuartz project
(http://xquartz.macosforge.org/landing/). See src/README.OSX for more
details.

Starting the X11 application should bring up an 'xterm' window. Graphical
GENESIS must be started from the xterm window; it will not work from a window
started by the 'Terminal' application.


5  PROBLEMS RUNNING GENESIS

You must be running X.org, X11R5 or X11R6 in order to successfully run the
graphical GENESIS. Earlier versions will not work.

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 <installdir>/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:  Some 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.


5.1  Floating Point Variation

Floating point computation may vary based on hardware, operating system,
and compiler versions/options. While similar system configurations should
reliably produce identical results, systems with different processors,
operating systems, and/or compiler options can be expected to show some
variation in floating point results. For the Rallpack benchmarks, this
will be after the sixth decimal place -- any larger variation should be
reported as a bug. Simulations with chaotic behavior and/or long runtimes
may potentially have much larger variations.