Building jtreg

The source code for jtreg is available from the OpenJDK repository at https://git.openjdk.org/jtreg.

jtreg depends on a number of external components: JT Harness, TestNG, JUnit, AsmTools. Ant, and JCov.

The fundamental way to build jtreg is with GNU make, specifying where to find those external components, but a script is also available that will download appropriate copies of those components before building jtreg.

Building jtreg with the build-all.sh script

This is the recommended way to build jtreg, for those that want a simple, basic way to build jtreg.

The script is intended to be run in a Unix-like shell, such as bash on Linux or MacOS, or with Cygwin on Windows. It takes one argument which is the installation of JDK to be used to build jtreg. In addition, Ant must be on your execution path as well as a suitable version of Java to run Ant. The version of JDK must be either JDK 7 or JDK 8.

    % cd jtreg-root-directory
    % sh make/build-all.sh JDK-directory

The script will create a build sub-directory, download and build dependencies, and finally build jtreg itself. The resulting image will be in build/images/jtreg.

Building jtreg with GNU Make

The Makefile is in make/Makefile, and creates deliverables in the build/ directory, similar to OpenJDK. By default, the build file just builds an image for jtreg. You can build jtreg from a Unix-like command shell with the following commands:

    % cd jtreg-root-directory
    % make -C make

Dependencies

jtreg has a number of build dependencies. These can be set with values on the make command line or with values in make/Defs.gmk. You can also include the appropriate license files in the jtreg image, by setting the appropriate make variables. These are documented in make/Defs.gmk

JDK 1.7 (or better)

Set JDKHOME to the JDK or equivalent used to build jtreg. It must be equivalent to JDK 1.7 or later.

JT Harness

See https://wiki.openjdk.org/display/CodeTools/JT+Harness.
Set JTHARNESS_HOME to the installed copy of the version of JT Harness to be used. It should be version 5.0 or better.

Ant

See http://ant.apache.org/. Set ANTHOME to an installed copy of Ant. It should be version 1.9.x. or better.

AsmTools

See https://wiki.openjdk.org/display/CodeTools/asmtools.
Set ASMTOOLS_HOME to the installed copy of the version of AsmTools to be used. It should be version 6.0 or better.

Note: Do not confuse this component with ASM bytecode engineering library available at http://asm.ow2.org/

JUnit

See http://junit.org/. The recommended version is currently JUnit 4.10.

TestNG

See http://testng.org/. The recommended version is currently 6.9.5.

The following dependencies are optional.

JCov

See https://wiki.openjdk.org/display/CodeTools/jcov.
Set JCOV_HOME to the installed copy of the version of JCov to be used. It should be version 2.0 or better.

JDK 1.5

This is used when running some of the tests. Set JDK15HOME to run these tests. It need not be set if you are just building jtreg.

JDK 1.6

This is used when running some of the tests. Set JDK16HOME to run these tests. It need not be set if you are just building jtreg.

JDK 1.7

This is used when running some of the tests. Set JDK17HOME to run these tests. It need not be set if you are just building jtreg.

JDK 1.8

This is used when running some of the tests. Set JDK18HOME to run these tests. It need not be set if you are just building jtreg.

JDK 1.9

This is used when running some of the tests. Set JDK19HOME to run these tests. It need not be set if you are just building jtreg.

Running jtreg Self-Tests

The tests can be invoked with individual make targets, or collectively via the "test" target.

Some of the tests need to pop up windows while they execute. No interaction with these windows is normally required. Since this can be a problem on a headless server machine, and an annoyance on a personal workstation, the tests will attempt to use VNC to create a dummy X-server for use by the tests while they are running. Various implementations of VNC are available, such as from http://www.realvnc.com/. Using VNC is optional; it is not required in order to run the tests.

By default, VNC will be used if vncserver is found on your execution path, or if VNC_HOME points to an installed copy of VNC. To explicitly disable the use of VNC, set the VNC environment variable to one of false, off, no, or 0. Unless explicitly disabled, the tests will check the following:

If the tests find any issue with using VNC, it will not be used. If VNC is used to create a dummy X server, the server will be terminated when the test is complete.

The logic for using VNC is encapsulated within the script make/display.sh.

Building jtreg with Ant

It is possible to build jtreg with Ant, but this is primarily intended as a convenience while working on the jtreg source code. If you are building jtreg to run OpenJDK tests, it is recommended that you build jtreg using the Makefile, perhaps via the build-all.sh wrapper script.

The build file is in make/build.xml; it creates intermediate files in the build/ directory and deliverables in the dist/ directory. By default, the build file just builds jtreg, but does not run any tests. You can build jtreg from a Unix-like command shell with the following commands:

    % cd jtreg-root-directory
    % ant -f make/build.xml

You can also use this build file when creating a NetBeans free form project with an existing build file.

Dependencies

Some of the tasks that are used are listed as "Optional Tasks" in the Ant manual. You may need to make sure that these tasks are available for use by Ant. For example, on Ubuntu Linux these tasks are in the ant-optional package.

Running Tests

Some of the tests can be invoked with individual targets beginning "-jtreg-test-", or collectively via the "jtreg-test" target. (The use of "jtreg-test" rather than "test" is to protect against interactions with JUnit in older versions of NetBeans.)