#
#  '$RCSfile$'
#   '$Author: jones $'
# '$Revision: 7318 $'
#     '$Date: 2008-06-12 17:54:53 -0700 (Thu, 12 Jun 2008) $'
#

NOTE: These instructions apply to developers working directly with source code. They do NOT apply to someone with an installer or zipped distribution of Kepler who just wants to execute it. See the Getting Started Guide for general usage.

BUILD AND INSTALL INSTRUCTIONS
------------------------------
To successfully compile and install Kepler, follow these steps:

1) Install a Java 1.5 compiler (javac).  You will need
   the JDK not just a JRE.  For example, download JDK 5.0 from:
     http://java.sun.com/javase/downloads/index_jdk5.jsp
   As of 08/2007, there is problem using Kepler with JDK 6 (the latest version)

2) Check out the Kepler code from SVN.  
   You will require an SVN binary.  Under Windows, either install
   TortoiseSVN (http://www.tortoisesvn.org/), 
   Cygwin (http://www.cygwin.com or
	http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/cygwin.htm),
   or use Eclipse (http://www.eclipse.org)

   Once SVN is available, check out the kepler repository using your
   graphical client or from the commandline:
    
    svn co https://code.kepler-project.org/code/kepler/trunk/ kepler

3) Checkout the source version of Ptolemy II from SVN.  Note that
   binary versions and source versions of Ptolemy are available from the
   Ptolemy web site.  This will not work -- you must use a SVN checkout.
   As of June 2008, Kepler is based on the trunk for the Ptolemy SVN tree.
   Use a checkout command like this:

     svn co svn://source.eecs.berkeley.edu/chess/ptII/trunk ptII

   Further instructions for obtaining it can be found here:
     http://chess.eecs.berkeley.edu/ptexternal/

4) Set the following environment variables:
   $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.

5) Install Apache ant (1.6.3 or later) in your path, see:
     http://ant.apache.org/
   Installation instructios are at: http://ant.apache.org/manual/index.html
   You will need to set:
   $ANT_HOME - set to the root of the Ant tree, $ANT_HOME/lib and
               $ANT_HOME/bin should exist.
   The PATH should be set to include $ANT_HOME/bin

6) 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'.

7) You should be able to install and run kepler by using the command
   'ant buildkarlib run' from within the kepler directory. To do a clean build
   of kepler, use 'ant clean run' (you need only use the buildkarlib target the
   first time you build kepler; after that, you need to use buildkarlib only if
   you change any actor code.  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'.

8) Please send any comments/suggestions to kepler-dev@ecoinformatics.org

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

# Check out the source trees
$ svn co https://code.kepler-project.org/code/kepler/trunk/ kepler
$ svn co svn://source.eecs.berkeley.edu/chess/ptII/trunk ptII

# set up the environment
# (for windows, use SET instead of export, and use backslashes)
$ cd kepler; export KEPLER=`pwd`; cd ..
$ cd ptII; export PTII=`pwd`; cd ..
$ cd $KEPLER

# FULL CLEAN build:

$ ant full-clean ptolemy
$ ant buildkarlib
$ ant 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


# ...unless you make changes to actor code or moml;
# if so, you should run:

$ rm -rf ~/.kepler  (or windows equivalent - see above)
$ ant buildkarlib
$ 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.

2) ant full-clean ptolemy: If running "ant full-clean ptolemy" returns
the list of targets and does not do anything further, then perhaps
your CLASSPATH is set incorrectly.  The way to to check this is to run
"ant --exedebug full-clean ptolemy" and check the classpath.
A workground is to clear CLASSPATH before running ant. 
Under Windows with Cygwin:
  unset CLASSPATH	
  and full-clean ptolemy
For further information about Ant problems, see:
  http://ant.apache.org/problems.html

3) ant run-dev: when running ant run-dev, if you see each actor giving
a KAR error about already being loaded, then you have probably run
ant-buildkarlib but forgotten to delete your ~/.kepler directory - see
"Example sessions", above.

4) ant run-dev: Under Windows you must have Administrative privileges 
because ant copies .dll files from $KEPLER/lib to c:/Windows/system32.
If you don't have Administrative privileges, start up wordpad, edit
build.xml and change
    <property name="javalibpath" value="c:/WINDOWS/system32"/>
to
    <property name="javalibpath" value="%HOME%/lib"/>
where %HOME%/lib is a directory in your path.  Any directory can
be used, it just needs to be in your path.

5) ant buildkarlib on Windows: when running ant buildkarlib on Windows XP, some
(not all) users have seen exceptions of the form:
--------
"[java] Could not copy the class files to the working dir.  Please check the filenames:
{kepler}\kar\actors\classes\ptolemy\actor\lib\{SomeActorsName}.class (Access is denied)
[java] java.io.FileNotFoundException:
{kepler}\kar\actors\classes\ptolemy\actor\lib\{SomeActorsName}.class (Access is denied)"
--------
This may be due to file-locking problems. A workaround hack is to edit
the file:

{kepler}/src/org/kepler/ksw/KSWCreator.java

Find the method "cleanUpDir(File dir)" and add this code just before the
method's closing brace:

  try {
    Thread.sleep(5);
  } catch (Exception e) {}

This will slow down execution of buildkarlib, but should stop the
build errors (the sleep time was chosen arbitrarily - you can experiment with
your own values - increase it if this fix doesn't alleviate the problem, or
decrease it to speed up your build)

