Avida   http://avida.devosoft.org/
--------------------------------------------------------------------------------
Digital Evolution Laboratory at Michigan State University
(http://devolab.msu.edu)


The top-level repository/distribution of Avida consists of multiple submodules.


I.   REQUIREMENTS
II.  GETTING STARTED
III. CMAKE CONFIGURATION OPTIONS
IV.  CONFIGURING THE CMAKE BUILD
V.   RUNNING CONSISTENCY TESTS
VI.  DOCUMENTATION



I. REQUIREMENTS
--------------------------------------------------------------------------------

General System Requirements

  avida:
   - CMake 2.6.x or greater (http://www.cmake.org/)
   - C++ Compiler and Make system supported by CMake


Additional Requirements for Specific Targets

  avida-viewer (on Linux/Unix Platforms):
   - ncurses

  avida-viewer/Avida.exe (on Windows using included Visual Studio Project):
   - Visual Studio 2008 or greater


  run_tests (testrunner):
   - python 2.6 or greater


  Mac OS X Development (using included Xcode Workspace and Projects):
   - Xcode 4


II. GETTING STARTED
--------------------------------------------------------------------------------

Building Avida on Linux/Unix Platforms (including Mac OS X):

  To compile and install Avida, using default settings run:
  $ ./build_avida

  By default, you will get an optimized version of the code, as well as the
  ncurses avida-viewer. The installation goes into a directory called 'work'
  that is created in a subdirectory named 'cbuild' directory.  See below how to
  change that.


Building Avida on Windows:

  Open CMake, then select the Avida source code directory (containing
  CMakeLists.txt) and a desired output directory.  Click the configure button.
  In the options panel you MUST turn AVD_GUI_NCURSES 'Off'.  Click the
  configure button again.  You should now be able to press the generate button.
  Open the Visual Studio project generated by CMake in the selected target
  directory.  In Visual Studio select the desired build mode (the default is
  generally 'Debug', 'Release' is recommended).  Build the 'All Build' target.


III. CMAKE CONFIGURATION OPTIONS
--------------------------------------------------------------------------------

Here are the main options available when configuring and building
Avida with cmake :

AVD_CMDLINE
 -  This is a BOOL, either ON or OFF, to enable building interface-less Avida
 ON by default.

AVD_GUI_NCURSES
 -  This is a BOOL, either ON or OFF, to enable building Avida console interface
 ON by default.

AVD_UNIT_TESTS
 -  This is a BOOL, either ON or OFF, to enable building unit test suites
 OFF by default.

CMAKE_BUILD_TYPE
 -  This is a STRING, one of "None", "Debug", "Release", "RelWithDebInfo", 
    "MinSizeRel", to vary optimization levels and debugging information
 "Release" by default.


AVD_GUI_PROTOTYPE_TEXT
 -  This is a BOOL, either ON or OFF, to enable building the prototype ncurses
    THIS IS EXPERIMENTAL AND MAY NOT BUILD!
 OFF by default.


IV. CONFIGURING THE CMAKE BUILD
--------------------------------------------------------------------------------

The following directions pertain to Linux/Unix usage of CMake.  Windows users
should see CMake documentation for using the GUI on Windows. There are three
ways by which you can set the various options.


For a simple 'gui' like interface, from the build directory run:
$ ccmake ../

Pressing 'c' will configure 
Pressing 'g' will generate the make files and exit


If you'd like to be prompted with questions for each option, execute the
following from the build directory:
$ cmake -i ../


From the command-line option, the cmake option -D allows setting Avida
configuration options with the following syntax:
-D<variable name>:<type>=<value>

To completely specify each of the above Avida options, cd into your build
directory and type something like:
$ cmake -DAVD_GUI_NCURSES:BOOL=ON \
  -DAVD_CMDLINE:BOOL=ON \
  -DAVD_UNIT_TESTS:BOOL=OFF \
  -DCMAKE_BUILD_TYPE:STRING=Release \
  path-to-source-directory


V. RUNNING CONSISTENCY TESTS
--------------------------------------------------------------------------------

With Avida built and 'installed' using CMake (the default for the 'build_avida'
script), simply execute the 'run_tests' script:

$ ./run_tests


For a list of useful options accepted by the TestRunner script, supply the -h
option on the command line:

$ ./run_tests -h


The 'builddir' option will be particularly for Xcode users.  This option will
allow the tests to be run on Xcode products without having to move the files to
where the CMake outputs are placed by default. For example, the default
Deployment build can be tested as follows:

$ ./run_tests --builddir=build/Deployment/


VI. DOCUMENTATION
--------------------------------------------------------------------------------

Helpful usage and code documentation can be found in the HTML files in the
'avida-core/documentation' directory.  See index.html.


Revised 2011-05-05 DMB