#
#  '$RCSfile: INSTALL,v $'
#   '$Author: higgins $'
# '$Revision: 1.17 $'
#     '$Date: 2006/02/28 21:36:39 $'
#

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.

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

1) A Java 1.4 compiler (javac) must be installed.  You will need
   the JDK not just a JRE.  For example, download j2se v1.4.2_10 from:
     http://java.sun.com/j2se/1.4.2/download.html
   As of 12/05, Java 1.5 (aka j2se 5.0) will not work, a possible fix
   would be to add source='1.4' to the java targets in build.xml.

2) You will require a CVS binary.  Under Windows, either install
   TortoiseCVS (http://www.tortoisecvs.org/), 
   Cygwin (http://www.cygwin.com or
	http://ptolemy.eecs.berkeley.edu/ptolemyII/ptIIlatest/cygwin.htm),
   or use Eclipse (http://www.eclipse.org)

3) 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/

   Under Windows, the Cygwin Bash commands to run would be:
     cd c:/directoryofyourchoice
     cvs -d :pserver:anon@source.eecs.berkeley.edu:/home/cvs/cvsanon login
     # No password needed, hit enter
     cvs -d :pserver:anon@source.eecs.berkeley.edu:/home/cvs/cvsanon co ptII

4) 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.

5) Apache ant (1.6.3 or later) must be installed and 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.

# set up the environment
# (for windows, use SET instead of export, and use backslashes)

$ export KEPLER=/home/jones/development/kepler
$ export PTII=/home/jones/development/ptII4.0.1
$ cd $KEPLER

# FULL CLEAN build:

    $ ant full-clean ptolemy

    # Mac OS X/Linux:
    $ rm -rf ~/.kepler

    # windows:
    rmdir /Q /S "C:\Documents and Settings\<yourUserName>\.kepler

    $ 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)

