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
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:
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.
Note:
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.
Basic Prerequisites
The tools you must have to be able to work with Harmony are:
Note
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:
-Dhttp.proxyHost=<host>
-Dhttp.proxyPort=<proxy>
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 |
|---|---|
|
|
Note:
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.
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.
Note
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.
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
Note
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.
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:
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.
Note
If you fail to rebuild class library after the svn update command,
clean previous build results:
$ ant clean
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.
Note
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
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.
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 http://harmony.apache.org Hello world!
Eclipse IDE users can install the Harmony plug-in for developing and running with the Apache Harmony VM.