Skip to content
Permalink
Browse files

8243973: Clarify difference between JAVA_OPTIONS and VM_OPTIONS

Reviewed-by: erikj
  • Loading branch information
magicus committed Apr 28, 2020
1 parent 0b5f5d5 commit c03a9bc9a2988426c558b17abe62c003b7c87741
Showing with 20 additions and 14 deletions.
  1. +8 −7 doc/testing.html
  2. +12 −7 doc/testing.md
@@ -56,7 +56,7 @@ <h2 id="using-make-test-the-run-test-framework">Using &quot;make test&quot; (the
$ make test-jdk_lang JTREG=&quot;JOBS=8&quot;
$ make test TEST=jdk_lang
$ make test-only TEST=&quot;gtest:LogTagSet gtest:LogTagSetDescriptions&quot; GTEST=&quot;REPEAT=-1&quot;
$ make test TEST=&quot;hotspot:hotspot_gc&quot; JTREG=&quot;JOBS=1;TIMEOUT_FACTOR=8;VM_OPTIONS=-XshowSettings -Xlog:gc+ref=debug&quot;
$ make test TEST=&quot;hotspot:hotspot_gc&quot; JTREG=&quot;JOBS=1;TIMEOUT_FACTOR=8;JAVA_OPTIONS=-XshowSettings -Xlog:gc+ref=debug&quot;
$ make test TEST=&quot;jtreg:test/hotspot:hotspot_gc test/hotspot/jtreg/native_sanity/JniVersion.java&quot;
$ make test TEST=&quot;micro:java.lang.reflect&quot; MICRO=&quot;FORK=1;WARMUP_ITER=2&quot;
$ make exploded-test TEST=tier2</code></pre>
@@ -106,8 +106,8 @@ <h2 id="test-results-and-summary">Test results and summary</h2>
<h2 id="test-suite-control">Test suite control</h2>
<p>It is possible to control various aspects of the test suites using make control variables.</p>
<p>These variables use a keyword=value approach to allow multiple values to be set. So, for instance, <code>JTREG=&quot;JOBS=1;TIMEOUT_FACTOR=8&quot;</code> will set the JTReg concurrency level to 1 and the timeout factor to 8. This is equivalent to setting <code>JTREG_JOBS=1 JTREG_TIMEOUT_FACTOR=8</code>, but using the keyword format means that the <code>JTREG</code> variable is parsed and verified for correctness, so <code>JTREG=&quot;TMIEOUT_FACTOR=8&quot;</code> would give an error, while <code>JTREG_TMIEOUT_FACTOR=8</code> would just pass unnoticed.</p>
<p>To separate multiple keyword=value pairs, use <code>;</code> (semicolon). Since the shell normally eats <code>;</code>, the recommended usage is to write the assignment inside qoutes, e.g. <code>JTREG=&quot;...;...&quot;</code>. This will also make sure spaces are preserved, as in <code>JTREG=&quot;VM_OPTIONS=-XshowSettings -Xlog:gc+ref=debug&quot;</code>.</p>
<p>(Other ways are possible, e.g. using backslash: <code>JTREG=JOBS=1\;TIMEOUT_FACTOR=8</code>. Also, as a special technique, the string <code>%20</code> will be replaced with space for certain options, e.g. <code>JTREG=VM_OPTIONS=-XshowSettings%20-Xlog:gc+ref=debug</code>. This can be useful if you have layers of scripts and have trouble getting proper quoting of command line arguments through.)</p>
<p>To separate multiple keyword=value pairs, use <code>;</code> (semicolon). Since the shell normally eats <code>;</code>, the recommended usage is to write the assignment inside qoutes, e.g. <code>JTREG=&quot;...;...&quot;</code>. This will also make sure spaces are preserved, as in <code>JTREG=&quot;JAVA_OPTIONS=-XshowSettings -Xlog:gc+ref=debug&quot;</code>.</p>
<p>(Other ways are possible, e.g. using backslash: <code>JTREG=JOBS=1\;TIMEOUT_FACTOR=8</code>. Also, as a special technique, the string <code>%20</code> will be replaced with space for certain options, e.g. <code>JTREG=JAVA_OPTIONS=-XshowSettings%20-Xlog:gc+ref=debug</code>. This can be useful if you have layers of scripts and have trouble getting proper quoting of command line arguments through.)</p>
<p>As far as possible, the names of the keywords have been standardized between test suites.</p>
<h3 id="general-keywords-test_opts">General keywords (TEST_OPTS)</h3>
<p>Some keywords are valid across different test suites. If you want to run tests from multiple test suites, or just don't want to care which test suite specific control variable to use, then you can use the general TEST_OPTS control variable.</p>
@@ -116,10 +116,10 @@ <h4 id="jobs">JOBS</h4>
<p>Currently only applies to JTReg.</p>
<h4 id="timeout_factor">TIMEOUT_FACTOR</h4>
<p>Currently only applies to JTReg.</p>
<h4 id="vm_options">VM_OPTIONS</h4>
<p>Applies to JTReg, GTest and Micro.</p>
<h4 id="java_options">JAVA_OPTIONS</h4>
<p>Applies to JTReg, GTest and Micro.</p>
<h4 id="vm_options">VM_OPTIONS</h4>
<p>Applies to JTReg, GTest and Micro.</p>
<h4 id="aot_modules">AOT_MODULES</h4>
<p>Applies to JTReg and GTest.</p>
<h4 id="jcov">JCOV</h4>
@@ -166,9 +166,10 @@ <h4 id="options">OPTIONS</h4>
<p>Additional options to the JTReg test framework.</p>
<p>Use <code>JTREG=&quot;OPTIONS=--help all&quot;</code> to see all available JTReg options.</p>
<h4 id="java_options-1">JAVA_OPTIONS</h4>
<p>Additional Java options to JTReg (<code>-javaoption</code>).</p>
<p>Additional Java options for running test classes (sent to JTReg as <code>-javaoption</code>).</p>
<h4 id="vm_options-1">VM_OPTIONS</h4>
<p>Additional VM options to JTReg (<code>-vmoption</code>).</p>
<p>Additional Java options to be used when compiling and running classes (sent to JTReg as <code>-vmoption</code>).</p>
<p>This option is only needed in special circumstances. To pass Java options to your test classes, use <code>JAVA_OPTIONS</code>.</p>
<h4 id="aot_modules-1">AOT_MODULES</h4>
<p>Generate AOT modules before testing for the specified module, or set of modules. If multiple modules are specified, they should be separated by space (or, to help avoid quoting issues, the special value <code>%20</code>).</p>
<h4 id="retry_count">RETRY_COUNT</h4>
@@ -23,7 +23,7 @@ Some example command-lines:
$ make test-jdk_lang JTREG="JOBS=8"
$ make test TEST=jdk_lang
$ make test-only TEST="gtest:LogTagSet gtest:LogTagSetDescriptions" GTEST="REPEAT=-1"
$ make test TEST="hotspot:hotspot_gc" JTREG="JOBS=1;TIMEOUT_FACTOR=8;VM_OPTIONS=-XshowSettings -Xlog:gc+ref=debug"
$ make test TEST="hotspot:hotspot_gc" JTREG="JOBS=1;TIMEOUT_FACTOR=8;JAVA_OPTIONS=-XshowSettings -Xlog:gc+ref=debug"
$ make test TEST="jtreg:test/hotspot:hotspot_gc test/hotspot/jtreg/native_sanity/JniVersion.java"
$ make test TEST="micro:java.lang.reflect" MICRO="FORK=1;WARMUP_ITER=2"
$ make exploded-test TEST=tier2
@@ -190,11 +190,11 @@ pass unnoticed.
To separate multiple keyword=value pairs, use `;` (semicolon). Since the shell
normally eats `;`, the recommended usage is to write the assignment inside
qoutes, e.g. `JTREG="...;..."`. This will also make sure spaces are preserved,
as in `JTREG="VM_OPTIONS=-XshowSettings -Xlog:gc+ref=debug"`.
as in `JTREG="JAVA_OPTIONS=-XshowSettings -Xlog:gc+ref=debug"`.

(Other ways are possible, e.g. using backslash: `JTREG=JOBS=1\;TIMEOUT_FACTOR=8`.
Also, as a special technique, the string `%20` will be replaced with space for
certain options, e.g. `JTREG=VM_OPTIONS=-XshowSettings%20-Xlog:gc+ref=debug`.
certain options, e.g. `JTREG=JAVA_OPTIONS=-XshowSettings%20-Xlog:gc+ref=debug`.
This can be useful if you have layers of scripts and have trouble getting
proper quoting of command line arguments through.)

@@ -218,11 +218,11 @@ Currently only applies to JTReg.

Currently only applies to JTReg.

#### VM_OPTIONS
#### JAVA_OPTIONS

Applies to JTReg, GTest and Micro.

#### JAVA_OPTIONS
#### VM_OPTIONS

Applies to JTReg, GTest and Micro.

@@ -331,10 +331,15 @@ Additional options to the JTReg test framework.
Use `JTREG="OPTIONS=--help all"` to see all available JTReg options.

#### JAVA_OPTIONS
Additional Java options to JTReg (`-javaoption`).
Additional Java options for running test classes (sent to JTReg as
`-javaoption`).

#### VM_OPTIONS
Additional VM options to JTReg (`-vmoption`).
Additional Java options to be used when compiling and running classes (sent to
JTReg as `-vmoption`).

This option is only needed in special circumstances. To pass Java options to
your test classes, use `JAVA_OPTIONS`.

#### AOT_MODULES

0 comments on commit c03a9bc

Please sign in to comment.
You can’t perform that action at this time.