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 |
|
|
TESTVMOPTS | test.vm.opts |
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 |
|
|
TESTJAVAOPTS | test.java.opts |
-javacoptions: "option1 option2
option3 ..." |
Equivalent
to:-javacoption: option1
-javacoption: option2
-javacoption: option3 ... |
|||
-javacoption: option |
|
|
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.