Eclipse OpenJ9
Eclipse Incubation

Build your own

Building OpenJDK with OpenJ9 will be familiar to anyone who has already built OpenJDK.
We're going to use a Docker file to create a Docker container where you'll build a binary from source code and run some tests on it. Just follow these steps:

Prepare your system

If you don't already have Docker on your system, download and install it now.

We'll start by building a Dockerfile. Pick one of the following Dockerfiles for the platform you want to work on:

Save the Dockerfile to your current directory and specify these commands to build and run the Docker image:

docker build -t openj9 -f Dockerfile .
docker run -it openj9

Depending on your Docker system configuration, you might need to prefix these commands with sudo.

Now that you have the Docker image running, you are ready to move to the next step.

Get the source

First you need to clone the Extensions for OpenJDK for OpenJ9 project. This repository is a git mirror of OpenJDK without the HotSpot JVM, but with an openj9 branch that contains a few necessary patches. Run the following command:

git clone https://github.com/ibmruntimes/openj9-openjdk-jdk9

Cloning this repository can take a while because OpenJDK is a large project! When the process is complete, change directory into the cloned repository:

cd openj9-openjdk-jdk9

Now fetch additional sources from the Eclipse OpenJ9 project and its clone of Eclipse OMR:

bash ./get_source.sh

Configure

When you have all the source files that you need, run the configure script, which detects how to build in the current build environment. You must specify one extra jar file, which has already been installed into the Docker container.

bash ./configure --with-freemarker-jar=/root/freemarker.jar

Note that you must give an absolute path to freemarker.jar

Build

Now you're ready to build OpenJDK with OpenJ9:

make all

Two Java builds are produced: a full developer kit (jdk) and a runtime environment (jre):

  • build/<platform>/images/jdk
  • build/<platform>/images/jre

where <platform> reflects the Dockerfile you chose.

For example, the Linux 64-bit (x86-64) Dockerfile directory is: linux-x86_64-normal-server-release

Test

For a simple test, try running the java -version command.

cd build/<platform>/images/jre
./bin/java -version

Here is a sample of the output from a Linux x-86 binary:

openjdk version "9-internal"
OpenJDK Runtime Environment (build 9-internal+0-adhoc..openj9-openjdk-jdk9)
Eclipse OpenJ9 VM (build 2.9, JRE 9 Linux amd64-64 Compressed References 20170912_000000 (JIT enabled, AOT enabled)
J9VM - e6ca543
JIT  - e6ca543
OMR  - a0813c2
OpenJDK  - 8593b2f based on )

There are a large number of test cases that you can run to test your binaries and to support continuous integration. All of these tests are run automatically as part of the Eclipse OpenJ9 build and test pipeline. The tests are triggered by pull requests and by successful OpenJ9 builds. You can see the latest results on this Jenkins instance: https://ci.eclipse.org/openj9/.

You can also download and run some or all of these tests manually on your own machine.

Tests from the OpenJDK and AdoptOpenJDK projects

These tests inspect the Java implementation via the commands and APIs available to the end user. The tests are separated according to their function:

  • Functional verification tests from the OpenJDK project, often referred to as the OpenJDK regression tests, most of which are applicable to Eclipse OpenJ9. Both the AdoptOpenJDK project and the Eclipse OpenJ9 project run these tests. At Eclipse OpenJ9, a curated subset of these regression tests is run. At the AdoptOpenJDK project, the entire suite of tests is run against Eclipse OpenJ9, with the exception of the Hotspot tests. For more information, see https://github.com/AdoptOpenJDK/openjdk-tests/README.md
  • System tests from the AdoptOpenJDK project, which consist of load tests and simple user scenarios, such as debugging and dynamic class replacement. Learn how to obtain and run the tests here: https://github.com/AdoptOpenJDK/openjdk-systemtest/README.md

The hierarchy of make targets is as follows:

  • test: the top-level target
    • sanity: a subset of OpenJDK regression tests, some implementation-general functional and system verification tests
    • extended: the remaining implementation-general system verification tests
    • openjdk: most OpenJDK regression tests, excludes Hotspot tests
    • external: third-party application tests
    • perf: open source benchmarks

Tests from the Eclipse OpenJ9 project

These tests also inspect the Java implementation via the commands and APIs available to the end user.

  • Functional verification tests that target the Eclipse OpenJ9 virtual machine, garbage collector, just-in-time compiler, and class libraries. Learn how to obtain and run the tests here: https://github.com/eclipse/openj9/test/README.md.
  • System tests that logically extend the AdoptOpenJDK tests, which are run as a prerequisite. The tests target unique Eclipse OpenJ9 features such as shared classes and extensions to the Java class libraries. Learn how to obtain and run the tests here: https://github.com/eclipse/openj9-systemtest/README.md.

The hierarchy of make targets is as follows:

  • test: the top-level target
    • sanity: most functional verification tests, some OpenJ9-specific system verification tests
    • extended: long-running functional verification tests and the remaining system verification tests
    • openjdk: a subset of OpenJDK regression tests