Apache Harmony is retired at the Apache Software Foundation since Nov 16, 2011.

The information on these pages may be out of date, or may refer to resources that have moved or have been made read-only.
For more information please refer to the Apache Attic

Getting Started For Contributors

Follow these instructions to get configured to build and work with the Apache Harmony source code. To get the Harmony code and build it, follow these steps:

  1. Get all required prerequisites.
  2. Check out the source code.
  3. Build the source code.

After successfully building the source code, you will be able to run Java applications with Harmony.

If you only need building specific parts of the source code and not the whole JDK, you can download a HDK (Harmony Java Developer's Kit) bundle, obtain the source code and follow component-wise instructions.


The build is evolving. If you come across a problem, double-check the mailing list archives, FAQ and the build troubleshooting page : your issue may have been already discovered and resolved. Otherwise, you can write a new mail to ask for help and support.

1. Prerequisites

Basic Prerequisites

The tools you must have to be able to work with Harmony are:


If you are working from behind a firewall, you may need to configure the proxy setting for ant and svn tools.
For the ant tool, set the ANT_OPTS environment variable to point to:

For the svn tool, follow the instructions appropriate to the version of the tool you use. For example, edit ~/.subversion/servers file for console version of svn.

Optional (but recommended) prerequisite is an Eclipse™ Java Compiler (ECJ), version 3.2 or higher. You need to download standalone ecj.jar and put it to ANT_HOME/lib directory. Alternatively, you can switch to any other Java 1.5 compiler supported by Ant via overriding hy.javac.compiler property.

The other prerequisites for building Harmony differ by platform. For examples of platform-specific setup instructions, please see these community maintained descriptions. Below is a generic guideline for each platform.
To learn which platforms are currently supported, see the Porting Matrix.

On Windows On Linux
  • gcc compiler, version 3.3.3 or higher
    Versions below 3.3.3 have not been tested but might work.
  • g++ compiler
  • make
  • liblcms1-dev
  • libpng12-dev
  • libjpeg62-dev
  • libx11-dev
  • libxft-dev
  • binutils-dev
  • libxml2-dev
  • x11proto-xext-dev
  • libxtst-dev


You have to ensure you properly configured the tools in the user environment, please refer to corresponding manuals as needed. In particular, the working environment should be such that the PATH environment variable contains all of the directories where the executables of the tools are located and that all of those executables can be successfully invoked from the command line.
For example, for using a C++ compiler on Windows you'd typically need to launch a specific batch script, such as "Visual Studio .NET 2003 Command Prompt", prior to building.

Additional Prerequisites

The build system requires additional software and libraries shared across different parts of the build or specific for individual build parts. The list is evolving, so the safest way to get and configure all the required software is to let the build download it from the Internet.

Here is the list of additional tools required for one of the build parts, DRLVM. The list applies to Windows and Linux users.

You can download these resources prior to building a component, and specify the resulting locations (e.g. by editing make/depends.properties in component's workspace). However, because the list of software is subject to change, we do not recommend that you download the software and not let the build do that for you.

2. Checking out the Federated Build Tree

The Harmony codebase is divided into many separate parts. To create a working JDK, you need a class library, a virtual machine and jdktools. To obtain these parts, use the federated build tree and then work within the class library directory and the VM directory as you choose. Currently, the federated build uses the DRLVM virtual machine.

To check out the federated build, use the following command:

$ svn co http://svn.apache.org/repos/asf/harmony/enhanced/java/trunk 

This command checks out a directory structure that contains classlib, drlvm and jdktools directories.


If the root of the federated build is multiple levels deep in your file system, the very long paths within class library might result in a SVN checkout failure on Windows. The solution is to move the tree upwards in your file system or switch operating systems.

3. Starting the Federated Build

Now you should be ready to build the code. For the first time you build, you might want to fetch all the dependencies. If you do not, or if in the future a new dependency is added, the build will tell you what to do, so that you can do this step periodically. To fetch the dependencies and check out, build, and package snapshots of the JRE, JDK and HDK, type the following command in the root directory of the federated build:

$ ant -Dauto.fetch=true all

This variant of command downloads all the required third-party components that can be distributed under licences different from the Apache license; see THIRD_PARTY_NOTICES.txt in the root directory for details. This is only needed during your first build. For subsequent builds, just type:

$ ant

If you have a Linux system with libstdc++.so.5 instead of libstdc++.so.6, please use the use.libstdc++5=true option. Using the proper version of C++ Standard Library is a requirement of the ICU libraries used.

$ ant -Duse.libstdc++5=true


If you choose to build from the federated build root, you may need to increase the Java heap available to Ant. We suggest setting the "ANT_OPTS" environment variable as ANT_OPTS='-Xms256m -Xmx512m' in the manner appropriate for your operating system.
This recommendation is especially actual if you're building on Windows: otherwise Ant can crash in obscure way (e.g. with a mysterious InvocationTargetException).

Because running Ant in the root directory builds the full JDK, it can be inconvenient for a developer focused on a specific area. If you are not interested in building the full HDK, follow the detailed instructions to build each component of JRE separately.

Back to top

Detailed Building Instructions for Components

If you do not need to build the whole HDK and did not execute ant in step 3, follow these instructions to build each component in turn and assemble the JRE from them. The building procedure consists of the following steps:

  1. Update the source trees.
  2. Build the JDK components.
  3. Combine class libraries and VM into JRE.

1. Updating the Source Trees

Any time going forward, you can bring any directory to current SVN revision simply by doing svn update in any directory.

$ cd classlib
$ svn update

After executing svn update, your tree will reflect any modifications made to the SVN repository. If you are a project committer, you can make commits from within this tree, as it is a normal SVN checkout.


If you fail to rebuild class library after the svn update command, clean previous build results:

$ ant clean

2. Building the Components

Now you should be ready to build the code. You need to build components in this order: first the class library, then DRLVM and last jdktools, to satisfy their build dependencies. Each next component takes necessary artifacts from it's predecessor and assembles a working JRE/JDK as part of its build.

All components have unified build interfaces, i.e. they support the same basic set of Ant targets and properties. Thus the following instructions are given by the example of class library, but apply to any other component.

For the first time you build, you might want to fetch all the external component dependencies. If you do not, or if in the future a new dependency is added, the build will tell you what to do, so that you can do this step periodically. To fetch the dependencies and then build the component, use the following commands:

$ cd classlib
$ ant fetch-depends
$ ant

Move on to validate the build. Each component provides a decent set of unit and functional tests and normally should pass 100% of them. Note, you can only test the class libraries in case you have a virtual machine. You can use a VM other than DRLVM, see Combining JRE from Built Components. If you want to use DRLVM, proceed with the instruction to build it.
Run the following command to build and run the full test suite for the component:

$ ant test

At this point, the build is complete. A produced JRE is in the deploy/jdk/jre subdirectory of the component workspace.


DRLVM creates the deploy subdirectory only if deploy.canonical.flag property was set to TRUE. Otherwise you can find the build artifacts deeper in build/<platform-specific>/deploy/jdk/jre directories.

You can get more information on build nuances of each component by running:

$ ant help

3. Combining JRE from Built Components

Class library developers can work with DRLVM or install another compatible VM. For example, you can use the IBM® virtual machine that has been generously made available for the project's development needs by IBM under a non-open source, binary evaluation license. To install the VM, follow the instructions that accompany that VM. You can expand the class library code over the top of the Harmony directory (so that the 'jdk' directories line-up)

On Windows:
$ unzip <path_to_vm_zip> -d ../..

On Linux:
$ tar xzf <path_to_vm_tarball> --directory ../..

To work with the Harmony class library, refer to the class library subcomponent .

DRLVM developers work with the result of the DRLVM build step, which is a JRE containing DRLVM and the class library.

Back to top

Running Java Applications

Ensure that the JAVA_HOME environment variable is unset, or pointing to the Harmony build directory (deploy/jdk/jre if you've built it as described above).

Run Java applications normally using the launcher in deploy/jdk/jre/bin:

$ deploy/jdk/jre/bin/java -showversion -jar helloworld.jar
Apache Harmony Launcher:
(c) Copyright 1991, 2006 The Apache Software Foundation or its licensors, as applicable.
java version "1.5.0"
pre-alpha : not complete or compatible
svn = r479551, (Nov 27 2006), Windows/ia32/msvc 1310, debug build
Hello world!

Eclipse IDE users can install the Harmony plug-in for developing and running with the Apache Harmony VM.

Back to top