Top | Web home | SourceForge home
$Id: //open/dt/dev/saffron/doc/install.html#2 $
(C) Copyright 2002-2003 Disruptive Tech
Author	Julian Hyde
Created	February 15th, 2002

How to build and install Saffron

1. Contents

1. Contents
2. Modification history
3. Setup build environment
4. Get the source code
5. Build
6. Run the unit tests
7. Run Walden
8. Appendix A: Product installation instructions
9. Appendix B: Coding guidelines
10. Appendix C: How to
    1. How to debug Tomcat in Intellij

2. Modification history

3. Setup build environment

Here are the steps to setup a build environment.

1. Install JDK 1.4.2.
2. Install Ant.
3. If you want to run the saffron web server, install Tomcat.
4. Install JUnit.
5. Install JavaCC.
6. Modify build.bat, setting JAVACC_HOME, ANT_HOME, JUNIT_HOME, TOMCAT_HOME. (It may be sufficient to just change HOME_DRIVE.) On Linux, edit the bash script named build instead.

Optional:

1. Install Jikes.

4. Get the source code

Releases are available from Sourceforge.

Developers should define a client to the Perforce server.

5. Build

As follows:

cd ${project.location}
build

6. Run the unit tests

To run the JUnit regression test:

build test

The detailed results of the tests are stored in the testlog directory. Tracing (via java.util.logging) is automatically configured. By default, the trace file is trace/SaffronTrace.log. You can change the tracing level and trace file location by editing trace/SaffronTrace.properties.

Or you can run class saffron.test.Main using any JUnit test harness. You can control the behavior of the test by creating a file called saffron.properties. Here is an example:

saffron.Statement.printBeforeCompile=false
saffron.debug.level=0
saffron.package.name=saffron.runtime
saffron.java.dir=D:/saffron/src/examples
saffron.class.dir=D:/saffron/classes
saffron.java.compiler.args=-classpath D:/saffron/classes -d D:/saffron/classes -verbose
saffron.test.Class=sales.InMemorySalesTestCase
saffron.test.Name=testIteratorJoin
#saffron.test.Suite=saffron.runtime.ThreadIterator$Test

You'll need an ODBC datasource called empdept in order to run the JDBC flavor of the tests.

To generate Sales2.java from Sales2.oj and compile it to Sales2.class; and to compile Test.java to Test.class:

cd ${project.location}
build compile.examples

(There is a bug in the ojavac Ant task. If you get an IOException, remove Sales2.java and try again.)

To run Sales2:

build run.sales.Sales2

7. Run Walden

Walden is a web application which runs inside Tomcat.

1. Install Tomcat.
2. Edit ${project.location}/deploy_env.properties and ${project.location}/web/walden/WEB-INF/web.xml for your environment.
3. Build and deploy walden.war, and start Tomcat:

   build run.walden

4. Hit http://localhost:8080/walden.

To stop Tomcat cleanly, go to ${tomcat.home}/bin and run shutdown.

Appendix A. Product installation instructions

These are the products I used to build saffron. Install all of the products marked 'required'. (I use /-es in paths because I am running MKS on Windows 2000, and it makes things simpler.)

In the following, the symbol ${project.location} means the root of your source tree.

Where the instructions suggest setting an environment variable, it is often sufficient to edit the corresponding line in ${project.location}/build.bat.

Appendix B: Coding guidelines

• Indentation 4.
• Use spaces, not tabs. (It may help to set your tab stop to 8, since this is the setting used by OpenJava source code.)
• Put open braces on the same line as the preceding 'if', 'else', 'while' statement or 'class' declaration.
• Use braces even for single-line blocks.
• Declare variables as near to their first use as possible.
• Don't initialize variables with 'dummy' values just to shut up the compiler.
• Try to keep lines shorter than 80 characters.
• Javadoc comments on methods are written in the active ('Collects garbage.') not imperative ('Collect garbage.')
• When editing HTML documents, don't use an editor which reformats the HTML source (such as Word).

Appendix C: How to

C.1. How to debug Tomcat using IntelliJ

1. add ${tomcat.home}/webapps/walden.war to intellij's classpath
2. edit ${tomcat.home}/bin/catalina.bat as follows:

   :doJpda
   if not "%SECURITY_POLICY_FILE%" == "" goto doSecurityJpda
   %_EXECJAVA% %JAVA_OPTS% %CATALINA_OPTS% -Xdebug -Xnoagent
     -Xrunjdwp:transport=dt_socket,address=%JPDA_ADDRESS%,server=y,suspend=n %DEBUG_OPTS%
     -Djava.endorsed.dirs="%JAVA_ENDORSED_DIRS%" -classpath "%CLASSPATH%"
     -Dcatalina.base="%CATALINA_BASE%" -Dcatalina.home="%CATALINA_HOME%"
     -Djava.io.tmpdir="%CATALINA_TMPDIR%" %MAINCLASS% %CMD_LINE_ARGS% %ACTION%
   goto end

3. create ${tomcat.home}/bin/setenv.bat as follows:

   set JPDA_ADDRESS=5000

4. build debug.walden
5. attach intellij's debugger to port 5000