Using JVM and javac options with jtreg

jtreg provides a number of command line options which specify options to be used when running java and javac commands. These options are available in shell scripts (as environment variables) and in Java code (as system properties) so that these values can be correctly propagated to child processes.

Environment Variables and System Properties for Command Line Options
Additional environment variables and system properties
Running JDK and JRE commands from within a test

Environment Variables and System Properties for Command Line Options

The following table identifies which options affect the use of java and javac commands, and the corresponding environment variables and system properties for each option.

jtreg Command Line Options	Affects javac	Affects java	Environment Variable (in shell scripts)	System Property (in java code)
`-agentlib` `-agentpath` `-classic` `-client` `-D` `-d32` `-d64` `-da` `-disableassertions` `-disablesystemassertions` `-dsa` `-ea` `-enableassertions` `-enablesystemassertions` `-esa` `-green` `-hotspot` `-javaagent` `-native` `-server` `-X` `-Xbootclasspath` `-Xcomp` `-Xint` `-Xm` `-Xmixed` `-Xms` `-XX`	Equivalent to: `-vmoption:`option
`-vmoptions:`"option1 option2 option3 ..."	Equivalent to: `-vmoption:`option1 `-vmoption:`option2 `-vmoption:`option3 ...
`-vmoption:`option	YES	YES	TESTVMOPTS	test.vm.opts
`-vmoption:`option	YES	YES	TESTTOOLVMOPTS Each option is automatically prefixed with -J	test.tool.vm.opts Each option is automatically prefixed with -J
`-javaoptions:`"option1 option2 option3 ..."	Equivalent to: `-javaoption:`option1 `-javaoption:`option2 `-javaoption:`option3 ...
`-javaoption:`option	NO	YES	TESTJAVAOPTS	test.java.opts
`-javacoptions:`"option1 option2 option3 ..."	Equivalent to: `-javacoption:`option1 `-javacoption:`option2 `-javacoption:`option3 ...
`-javacoption:`option	YES	NO	TESTJAVACOPTS	test.compiler.opts

Notes

jtreg Command Line Options

The options in the first row of the table are just supported for backwards compatibility. In general, direct use of these options is discouraged in favor of using the more explicit form -vmoption:option.

Affects javac

If "yes", then the option will affect direct use of the Java compiler via the @build and @compile tags. In addition, it would typically be appropriate to honor the option when starting the Java compiler, javac, in a subprocess, such as in a shell test or in Java code.

Affects java

If "yes", then the option will affect direct use of the Java runtime via the @run main or @run applet tags. In addition, it would typically be appropriate to honor the option when starting a Java virtual machine in a subprocess, such as in a shell test or in Java code.

Environment Variables

When executing a shell test, jtreg will make the various different groups of options available in environment variables. In general, it is typically appropriate to progagate these options to any JDK tools or virtual machines that may be invoked from the shell test.

The environment variables are not set when executing the actions other than @run shell.

System Property

When executing Java code, (i.e. with @run main, @run compile or @run applet) jtreg will make the various different groups of options available in system properties. In general, it is typically appropriate to propagate these options to any JDK tools or virtual machines that may be invoked from the Java code.

All file system paths contained within these environment variables and system properties will be absolute paths.

Additional environment variables and system properties

Environment Variable	System Property	Description
TESTJAVA	test.java	The directory containing the JDK or JRE to be tested. This is typically specified on the command line with either the `-jdk:`dir or `-testjdk:`dir options.
COMPILEJAVA	compile.java	The directory containing the JDK to use to compile code when a JRE is being tested: i.e. when TESTJAVA just contains a JRE. This is either specified on the command line with the `-compilejdk:`dir option, or defaults to TESTJAVA if the option is not given.
TESTSRC	test.src	The directory containing the defining file for the test. The defining file is the file containing the test description: the comment beginning `@test ...`
TESTSRCPATH	test.src.path	The path containing the TESTSRC directory, and any library directories that may have been specified with `@library`.
TESTCLASSES	test.classes	The directory containing the compiled classes for files in the TESTSRC directory.
TESTCLASSPATH	test.class.path	The path containing the TESTCLASSES directory, and any library directories that may have been specified with `@library`.
–	java.home	The location of the current JRE. If the JRE is part of a JDK, the last component of the filename will normally be "`jre`" and the location of the JDK will be the parent directory.
–	sun.boot.class.path	The boot class path of the current JRE. If you want to start a child JVM with the same boot class path, you may want to set this value as the value for the `-bootclasspath` option for the child JVM.

Notes

Environment Variables: As before, environment variables are only set when running shell scripts via @run shell ....
System Properties: As before, system properties are only set when running Java code via the @run main, @run compile or @run applet tags.

All file system paths contained within these environment variables and system properties will be absolute paths.

Running JDK and JRE commands from within a test

In general, unless there is a specific reason to do otherwise, if a test needs to run a JDK or JRE command in a subprocess, it should honor the options set on the command line and propagate them as needed to those subprocesses. As much as is possible, this ensures consistent behavior between commands invoked by jtreg directly, and commands invoked from a shell script or Java code that is run as part of a test.

Running javac from within a shell script

Although individual tests may differ, the following is a template for how to execute javac in a shell script started by jtreg. ${FS} is assumed to have been specified as the platform specific file separator.

${COMPILEJAVA}${FS}bin${FS}javac ${TESTTOOLVMOPTS} ${TESTJAVACOPTS} \
    -d ${TESTCLASSES} -classpath ${TESTCLASSPATH} ${TESTSRC}${FS}MyTestClass.java ...

Running java from within a shell script

Although individual tests may differ, the following is a template for how to execute java in a shell script started by jtreg. ${FS} is assumed to have been specified as the platform specific file separator.

${TESTJAVA}${FS}bin${FS}java ${TESTVMOPTS} ${TESTJAVAOPTS} \
    -classpath ${TESTCLASSPATH} MyTestClass args...

Running javac from within Java code

In general, it should not be necessary to fork a new process to run javac. Use the public Java Compiler API instead. More advanced users may want to use the Compiler Tree API.

Running a new Java virtual machine from within Java code

This is not common. You should only consider doing this when you need to change the characteristics (JVM options) of the JVM that is currently in use. If you do need to start a child JVM, you may need to use the sun.boot.class.path property, so that the child JVM can inherit the bootclasspath you are using, including any additions to the bootclasspath specified by the user with the -Xbootclasspath/p: or -Xbootclasspath/a: options.