#
#  '$RCSfile: INSTALL,v $'
#   '$Author: jones $'
# '$Revision: 1.7 $'
#     '$Date: 2005/06/15 17:07:15 $'
#

BUILD AND INSTALL INSTRUCTIONS
------------------------------
To successfully compile and install Kepler the following criteria must be met:

1) A source version of ptolemy II from CVS must be installed.  Note that
   a binary versions and source versions of ptolemy are available from the ptolemy
   web site.  This will not work -- you must use a CVS download. 

   As of June 2005, Kepler is based on the HEAD for the Ptolemy CVS tree.
   Instructions for obtaining it can be found here:
   http://chess.eecs.berkeley.edu/ptexternal/

2) The following environment variables must be set:
   $KEPLER - set to the kepler directory where the build.xml file exists
   $PTII - set to the root of the ptolemy tree
   $JAVA_HOME - set to the root of your java installation.  Note that this must
                be a JDK installation not just a JRE.
3) Jakarta ant must be installed and on your path.
4) Change the current directory to the top level kepler directory. There should
   be a 'build.xml' file in that directory. You can just type 'ant' to see 
   the various build choices (once ant is installed). First, compile the Ptolemy
   source by entering the command 'ant ptolemy'.  You may want to clean the
   ptolemy tree before building, in which case you can use the command
   'ant ptolemy-clean'.
5) You should be able to install and run kepler by using the command 
   'ant run' from within the kepler directory. To do a clean build of kepler,
   use 'ant clean run'.  There is also a "quick" version of the compile-run
   cycle that works well for faster development (skipping some of the time
   consuming steps).  To use it, use 'ant run-dev'.
6) Please send any comments/suggestions to kepler-dev@ecoinformatics.org

Example session
---------------
The following session illustrate all of the steps necessary to do a 
completely clean build of the Kepler and Ptolemy source.

$ export KEPLER=/home/jones/development/kepler
$ export PTII=/home/jones/development/ptII4.0.1
$ cd $KEPLER
$ ant full-clean ptolemy run-dev
...
# from this point forward a clean build is usually not necessary, so
# make your changes and then you can run
$ ant run-dev

COMMON PROBLEMS
---------------
1) Eclipse: if you have followed the instructions on the kepler web site for 
using Eclipse to build kepler, then you CAN NOT use that copy of Ptolemy sources
in the ant build.  The ant and Eclipse builds are incompatible, and you must use
separate copies of the ptolemy source for the ant and eclipse builds.

