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
% cd jtreg-root-directory % make -C make
jtreg has a number of build dependencies. These can be set with
values on the make command line or with values in
- JDK 1.5 (or better)
JDK15HOMEto the JDK or equivalent used to build jtreg. It must be equivalent to JDK 1.5 or later.
See http://javahelp.java.net/. Unzip the javahelp zip file (e.g. javahelp2_0_05.zip) and set JAVAHELP_HOME to point to the resulting jh2.0/javahelp directory.
- JT Harness
See http://jtharness.java.net/. Set
JTHARNESS_HOMEto 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: unpacking the jtharness harness will not implicitly create a directory. It is advised to first explicitly create a jtharness directory and unzip the jtharness archive therein. JTHARNESS_HOME should point to that directory.
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 default
alltarget. 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
buildtarget, and avoid running the jtreg self tests invoked by the
testtarget in the Makefile.
See http://ant.apache.org/. Set
ANTHOMEto 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.
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.
Note: Notice that only versions smaller than 4.11 are supported. JUnit 4.11 and above do not contain the required org.hamcrest classes any more. (They are now contained in their own jar file hamcrest-core.jar but jtreg/jtharness isn't currently prepared to handle this). Set JUNIT_JAR to the junit jar file.
See http://testng.org/. The recommended version is currently 6.8.5.
Note: For TestNG it is not enough to just download the testng jar file. Instead you have to download the complete testng archive from the link for ANT users in the download section. Unzip the archive and set TESTNG_HOME to point to the created directory and TESTNG_JAR to point to the testng jar file in that directory.
See http://xml.apache.org/xalan-j/. Go to the "Download/Build" section and follow the "xalan-j distribution directory" link. From there choose "Xalan java download area" and download "xalan-j_2_7_1-bin.zip" from the "binaries/" directory. Set XALANHOME to the directory which will be created when you unzip the xalan zip archive.
The following dependencies are optional.
This uses nsgmlns, available from http://www.jclark.com/sp/, and DTDs, available from http://w3c.org/ to validate HTML documentation files. Set
HTMLCHECKto 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.
See http://www.linklint.org/. This is used to validate the links in HTML documentation files. Set
LINKLINTto 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
JDK16HOMEto run these tests. It must be equivalent to JDK 1.6 or later. It need not be set if you are just building jtreg.
- JDK 1.7
This is used when running some of the tests. Set
JDK17HOMEto run these tests. It must be equivalent to JDK 1.7 or later. 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:
- You must have a password set in $HOME/.vnc/passwd. This is the standard location used by the vncserver command.
- If you set the environment variable VNC_HOME, it will be prepended to your execution path to find vncserver.
- vncserver must be on your execution path, after VNC_HOME has been added, if set.
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
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
% 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.
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.
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
dist-doctargets instead of the default
buildtarget. 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
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.iopackage. 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.agentpackage. 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.