$Id: README 9904 2011-10-17 13:56:16Z duvigne $

Style guide: code, directories, CVS, ...
----------------------------------------

See renew2.3/src/Core/doc/internal/style.txt 
(This file is not included in the Renew source distribution.)


Used Tools (not included in the repository)
-------------------------------------------

The versions listed are the versions installed in the FBI-RZ Hamburg.
The override notes are needed if your software installation differs
from the default locations. Most probably, you will need to follow
Tip A) below before you are able to build Renew at home.

- Java-SDK: javac, rmic, javadoc, ...
    Purpose:  Code compilation and documentation
    Version:  1.5.0 (1.6.0 is working, too)
    URL:      http://java.sun.com/
    Override: $JAVA_HOME and $PATH environment variables

- ant
    Purpose:  Managing the build process
    Version:  1.7
    URL:      http://ant.apache.org/
    Override: $ANT_HOME and $PATH environment variables
              If you are using ant 1.5, you have to configure
              ant-javacc_jar=optional.jar in ant/local.properties.
              If you are using ant 1.6, JUnit task definition might
              fail.  Move junit.jar to ant/libs (ant installation).

- javacc
    Purpose:  Parser generation
    Version:  4.0
    URL:      https://javacc.dev.java.net/
    Override: bin.javacc ant property

- jalopy
    Purpose:  Source code beautification
    Version:  1.5rc3 with individual fixes
    URL:      http://jalopy.sourceforge.net/
    Override: dir.jalopy.lib ant property

- jarbundler (only AppleUI plugin)
    Purpose:  Ant task to create MacOS X application bundles
    Version:  1.9
    URL:      http://jarbundler.sourceforge.net/
    Override: file.jarbundler.jar ant property

- Subversion (svn)
    Purpose:  Concurrent version control
    Version:  1.4
    URL:      http://subversion.tigris.org/
    Override: $PATH environment variable

- LaTeX 2e
    Purpose:  Typesetting user and architecture guides
    Version:  TeX Live 2008
    URL:      http://www.tug.org/texlive/
    Override: $PATH environment variable

- JUnit
    Purpose:  Testing framework for Java
    Version:  4.4
    URL:      http://junit.org/
    Install:  copy junit.jar to renew2.3/src/lib/junit/junit.jar

- Cobertura
    Purpose:  Report source code coverage by JUnit tests
    Version:  1.9
    URL:      http://cobertura.sourceforge.net/
    Override: dir.cobertura ant property


Tips for compilation and execution (in Unix syntax)
---------------------------------------------------

A) To configure the build process:
   - Run
     ant configure
     to ensure that the file renew2.3/src/ant/local.properties
     is generated.
   - Configure the properties in renew2.3/src/ant/local.properties,
     possibly overriding properties defined in
     renew2.3/src/ant/commonproperties.xml .

B) To build from scratch: 
   - Run "ant" on top level (renew2.3/src/)
   - The distribution tree (including all plugin components) 
     will be created in renew2.3/src/dist
   Note: The default ant target is 'dist', which compiles all plugins
         intended for distribution. Developers at the FBI-RZ Hamburg
         should use 'all' to compile all experimental plugins. Similar
         distinction exists for the 'clean' and 'cleanall' targets.

C) To run the application:
   - Go to the renew2.3/src/dist directory and execute
     java -jar loader.jar gui
   - The java -jar command will not use any given classpath,
     neither from environment variable nor from -classpath option.
     If you want to use your own classes with Renew plugins or 
     within simulations, execute
     java -Dde.renew.classPath=<yourOwnClasspath> -jar loader.jar gui
   - If you want to use own classes behind the back of Renew, execute
     java -classpath loader.jar:<anyOtherClasspath> de.renew.plugin.Loader gui
     Renew can then use your classes, but your classes will not
     see any Renew classes.
   - The 'gui' command at the end of these lines can be replaced by
     any other command registered at the PluginManager. If you have
     the PromptPlugin installed, you can omit the initial command 
     at the command line and use the interactive prompt instead.

D) To configure with more than one plugin directory:
   - Create a Renew configuration file. There are two locations:
     either ".renew.properties" in your home directory (i.e. ~/.renew.properties)
     or "renew.properties" in the directory renew2.3/src/dist/config .
   - Put a line of the form
     pluginLocations=/a/path/to/plugins:/an/other/path/to/plugins
     in there. The default plugin location is automatically included.

