Building jtreg

The source code for jtreg is available from the OpenJDK Mercurial repository at http://hg.openjdk.java.net/code-tools/jtreg.

There are two ways to build jtreg. The first way uses GNU Make to build jtreg and run all the tests. The second way uses Ant, and is primarily intended for developers using an IDE such as NetBeans. Not all of the tests are available using the Ant build.

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 builds jtreg and runs the tests. 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.

JDK 1.5 (or better)

Set JDK15HOME to the JDK or equivalent used to build jtreg. It must be equivalent to JDK 1.5 or later.

JavaHelp

See http://javahelp.java.net/. Set JAVAHELP_HOME to an installed copy of JavaHelp. It should be version 2.0_01 or better.

JT Harness

See http://jtharness.java.net/. Set JTHARNESS_HOME to the installed copy of the version of JT Harness to be used. It should be version 4.1.3 or better. (Note, the license changed for 4.1.3.) See the notes below on building JT Harness from source for use in jtreg.

Note: there is a bug in JT Harness 4.1.3 which causes some of the jtreg self tests to fail. These are automatically run if you build jtreg with the the default all target. The bug affects the ability to run tests in the root directory of a test suite. (This does not apply to OpenJDK test suites.) To work around this issue, you can either download and build JT Harness 4.1.3a from source, or you can use version 4.1.3 and just build jtreg, with the build target, and avoid running the jtreg self tests invoked by the test target in the Makefile.

Xalan

See http://xml.apache.org/xalan-j/. Set XALANHOME to the installed copy of the version of Xalan to be used while building jtreg to process XML files.

The following dependencies are optional.

JUnit

See http://junit.org/. The recommended version is JUnit 4.5. There are a few tests in the jdk/test test suite that use JUnit. However, JUnit support is being phased out in favor of TestNG.

TestNG

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

HTMLCheck

This uses nsgmlns, available from http://www.jclark.com/sp/, and DTDs, available from http://w3c.org/ to validate HTML documentation files. Set HTMLCHECK to an HTML validation program. It should take a single file as argument, and exit with a zero return code for a valid file, and non-zero for an invalid one. This is optional, and if available, it will be used while building jtreg. It may be left unset to ignore the checks.

LinkLint

See http://www.linklint.org/. This is used to validate the links in HTML documentation files. Set LINKLINT to your installed copy of LinkLint. This is optional, and if available, it will be used while building jtreg. It may be left unset to ignore the checks.

The following dependencies are only required when running the tests for jtreg. (Note: this only applies to the tests for jtreg itself; these dependencies are not required when using jtreg to run the JDK regression tests.

JDK 1.6

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

Ant

See http://ant.apache.org/. Set ANTHOME to an installed copy of Ant. This is used when running some of the tests. It should be version 1.6.5. or better. 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

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 collectivly 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.)

Building JT Harness for jtreg

JT Harness has build-time dependencies on a number of components, some of which may cause issues. There are workarounds available, which allow you to build JT Harness, while not affecting its use for jtreg.

JUnit 4

If your system does not yet support JUnit 4, you can build JT Harness without needing to install JUnit 4 by executing the jar and dist-doc targets instead of the default build target. This will avoid building the jar file which references JUnit 4. The jar file (jt-junit.jar) is not required when running jtreg.

The Java Communications API (also known as javax.comm)

This API is not widely available under an OSI-approved license. There is a replacement known as "librxtx-java" which provides the same functionality in the gnu.io package. To use this package, you will have to edit the JT Harness source code so that references to javax.comm. are replaced by references to gnu.io.. These references are all in the com.sun.javatest.agent package. These changes are just required to compile JT Harness. The resulting classes are not required when running jtreg itself.

Note: if you are building jtreg with GNU Make, and want to run all the self tests for jtreg, you should make sure you use a patched version of JT Harness, available on the JT Harness 4.1.3a development branch or later. The patch fixes a bug which is exhibited when the jtreg self tests are run. It does not affect the use of jtreg to run the OpenJDK regression tests.