Documenting options; was Re: RFR: JDK-8220639 Need a way to augment JTREG_LAUNCHER_OPTIONS from command-line

[Magnus Ihse Bursie]

On 2020-06-15 23:23, Erik Joelsson wrote:
> The makefile test documentation is in the repo, so you could link 
> directly to it:
>
> https://hg.openjdk.java.net/jdk/jdk/raw-file/87828d2e32fe/doc/testing.html 
>
>
> Which reminds me that Magnus should update that documentation with 
> these new options.
Ok, I have now added the new options to the documentation. I double 
checked to see that all other options were documented. Almost all were, 
but not FAILURE_HANDLER_TIMEOUT, so I added that as well.

When looking into testing.md I noticed that it had diverged quite far 
from our normal standards of code quality, so I made some adjustments to 
get it back to consistency, including fixing line length and adding 
empty lines after headings. I also fixed the "keword" typo that Jon noticed.

There are no other changes except for testing.md/.html in this webrev:

http://cr.openjdk.java.net/~ihse/JDK-8220639-add-jtreg-launcher-options/webrev.02

/Magnus
>
> /Erik
>
> On 2020-06-15 14:19, Jonathan Gibbons wrote:
>> Magnus,
>>
>> Would it be worth while adding something to the jtreg documentation, 
>> such as a new page describing these options for the JDK makefile 
>> support, giving due deference to the makefile (like "If in doubt, 
>> consult `make test JTREG=help`")
>>
>> I can write the page, with your help, if you think this would be a 
>> good idea.
>>
>> -- Jon
>>
>> On 6/15/20 8:56 AM, Magnus Ihse Bursie wrote:
>>> It turned out that it was not possible to send arguments directly to 
>>> the java that launches jtreg, something that was needed, especially 
>>> to change the output limit using Djavatest.maxOutputSize.
>>>
>>> This patch adds JTREG=LAUNCHER_OPTIONS=xxx to pass generic options 
>>> to the launcher. Also, for the specific case of changing the max 
>>> output size, it adds JTREG=MAX_OUTPUT=nnn.
>>>
>>> All these new options made me realize there's no way apart from 
>>> reading the code to know what options are available, so I added a 
>>> help system, and documented this in "make help". Now you can get:
>>>
>>> $ make test JTREG=help
>>> Building target 'test' in configuration 'linux-x64'
>>> Valid keywords for JTREG:
>>> JOBS TIMEOUT_FACTOR FAILURE_HANDLER_TIMEOUT TEST_MODE ASSERT VERBOSE 
>>> RETAIN MAX_MEM RUN_PROBLEM_LISTS RETRY_COUNT MAX_OUTPUT OPTIONS 
>>> JAVA_OPTIONS VM_OPTIONS KEYWORDS EXTRA_PROBLEM_LISTS AOT_MODULES 
>>> LAUNCHER_OPTIONS.
>>> RunTests.gmk:292: *** Re-run without 'help' to continue. Stop.
>>>
>>> Finally, I fixed some broken comments regarding AOT that I noticed 
>>> while fixing this.
>>>
>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8220639
>>> WebRev: 
>>> http://cr.openjdk.java.net/~ihse/JDK-8220639-add-jtreg-launcher-options/webrev.01
>>>
>>> /Magnus