Introduction

The current page provides instructions on how to set up Eclipse™ to develop Java code in Apache Harmony, with sections for both DRLVM and class library development.

DRLVM specific instructions are only emerging, while class library specific instructions are in two sets: the fast path for people familiar with Eclipse and the source code layout in Harmony's Subversion® repository; and the step-by-step guide for novices who want to follow the details of a setup and see a brief development example.

All instructions assume you satisfy the same Eclipse-based development prerequsities, as described in the following section.

Prerequisites

To develop Apache Harmony Java code with Eclipse JDT, you need:

Eclipse: version 3.2 or later, from eclipse.org
A Subversion plug-in: Either Subclipse from tigris.org or Subversive from Eclipse.org

Optionally, you may wish to use one of the external, production-grade virtual machines that work with the Apache Harmony class library. These can be found on our Other Projects page.

Getting the Code

Next you will need the code to work with. For class library development, you will need a compatible VM, such as DRLVM or IBM® virtual machine (the latter available under a non-open source, binary evaluation license). Install the VM following the instructions that accompany that VM in the same location as the class libraries build (or the location you will be building to if you are building the class libraries yourself).
You will also need a class libraries build if you want to work on an individual module.

Analogously, you will need the class libraries for DRLVM development. Follow one of these ways depending on your needs:

Get a pre-built snapshot from the download page.
Download the source code to be built manually. For that, create an SVN repository location using the URL:
```
///for the class libraries
http://svn.apache.org/repos/asf/harmony/enhanced/classlib

///for DRLVM
http://svn.apache.org/repos/asf/harmony/enhanced/drlvm
```
Check out the code from SVN selecting Checkout... from the context menu of trunk.

DRLVM Development

For details on how to build DRLVM and other related documentation, please see the DRLVM web pages.

Class Library Development: Fast Path - for Experienced Eclipse developers

If you know your way around Eclipse JDT, then following these steps will have you hacking Harmony Java code in no time at all!

Configuring Eclipse

Ensure that you have the development prerequisites in place. Then if you are using Linux start Eclipse as normal with the arguments -vmargs -Dpde.jreProfile=none -Dpde.allowCycles=true and skip to step 4. If you are using Windows do the following:

Copy the vsvars32.bat file from your Visual Studio install directory to any convenient location. If you have chosen the defaults when installing, you will find the given file in the C:\Program Files\Microsoft Visual Studio.NET 2003\Common7\Tools directory.
Edit the vsvars32.bat file adding the following line right after the last line beginning with @set...:
```
start C:\...\eclipse\eclipse.exe -vmargs -Xmx512M -Dpde.jreProfile=none -Dpde.allowCycles=true
```
In the line above, "..." is the path to your Eclipse installation directory.
Note

Using -vmargs -Xmx512M is optional, but helpful to stop Eclipse running out of memory.
To start Eclipse, double click on the vsvars32.bat file.
Configure the following settings in Window > Preferences:

Change the Java compiler settings:
1. In the Java > Compiler preferences ensure the Compiler compliance level is set to 1.4.
2. In the Java > Compiler > Building preferences, open the Build Path Problems section and change Circular Dependencies from Error to Warning.
Change the PDE settings:
1. In the Plug-in Development > Compilers preferences change Unresolved Dependencies from Error to Warning.
2. In the Plug-in Development > Target Platform preferences, change the Location box to be the jre/lib/boot directory of the classlib snapshot.

Copy the ecj_3.2.jar file into the ...\eclipse\plugins\org.apache.ant_1.6.5\lib directory.
To include the given file, configure the following Ant settings in Window > Preferences > Ant > Runtime:

Select Global Entries
Select Add External Jars
Add the ecj_3.2.jar file from the org.apache.ant_1.6.5\lib directory.

Developing and Testing Code

The Apache Harmony class library is structured to allow developers to work on individual modules in the class library without having to load and compile the entire project source tree.

This is best illustrated by a worked example. In this example, assume you want to make a change to the NIO module. This is how you would proceed:

Go to the SVN repository view, open the Harmony URL and browse to trunk > modules. Select nio and from the context menu select Checkout..., and on the checkout dialog box click Finish.
In the resulting project in your workspace the implementation code is in the source folder src/main/java and the unit tests are in the source folder src/test/java.
Hack away! Developers are encouraged to produce JUnit tests for new implementation code.
To test the code you need to set-up a JUnit Run Configuration for the unit test. You can either run a single test case, or run the AllTests suite for all tests in a package or module. For example, to run the test suite org.apache.harmony.tests.nio.AllTests set up a run configuration with the following characteristics:
- bootclasspath: the folder nio/bin/main, followed by the Harmony JRE library.
- classpath: the folder nio/bin/test, followed by the JUNIT JAR file.
- VM: the Harmony JRE as the launching VM.
If everything looks good, go ahead and contribute a patch.

Class Library Development: Step-by-Step Guide

We have produced a brief webcast for those who want to see a step-by-step guide to configuring Eclipse, and developing a patch to the classlibrary code. The webcast starts assuming you have already installed the pre-requisites for Eclipse-based development, and launched Eclipse with the following commandline:

eclipse -vmargs -Dpde.jreProfile=none -Dpde.allowCycles=true

We pick up the story here... (Warning 8Mb flash download!)