8348515: Add docs for -XX:AOT* options in java man pages by iklam · Pull Request #23287 · openjdk/jdk

iklam · 2025-01-24T01:49:19Z

I added docs for the following options added by JEP 483

-XX:AOTCache
-XX:AOTClassLinking
-XX:AOTConfiguration
-XX:AOTMode

For a (semi) rendered version, see https://github.com/iklam/jdk/blob/8348515-docs-for-aot-options/src/java.base/share/man/java.md#ahead-of-time-cache

(Some of the rendering by GitHub looks odd, but the java.1 and java.html pages produced by the build should look fine)

Progress

Change must be properly reviewed (1 review required, with at least 1 Reviewer)
Change must not contain extraneous whitespace
Commit message must refer to an issue

Issue

JDK-8348515: Add docs for -XX:AOT* options in java man pages (Enhancement - P4)

Reviewers

Vladimir Kozlov (@vnkozlov - Reviewer) Review applies to fce60cec
Andrew Dinn (@adinn - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/23287/head:pull/23287
$ git checkout pull/23287

Update a local copy of the PR:
$ git checkout pull/23287
$ git pull https://git.openjdk.org/jdk.git pull/23287/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 23287

View PR using the GUI difftool:
$ git pr show -t 23287

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/23287.diff

Using Webrev

Link to Webrev Comment

bridgekeeper · 2025-01-24T01:50:15Z

👋 Welcome back iklam! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2025-01-24T01:50:20Z

@iklam This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8348515: Add docs for -XX:AOT* options in java man pages

Reviewed-by: adinn, kvn

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 37 new commits pushed to the master branch:

ad01dfb: 8346920: Serial: Support allocation in old generation when heap is almost full
1d8ccb8: 8342465: Improve API documentation for java.lang.classfile
7d6055a: 8348429: Update cross-compilation devkits to Fedora 41/gcc 13.2
f1e0797: 8348586: Optionally silence make warnings about non-control variables
ffeb9b5: 8342807: Update links in java.base to use https://
afcc2b0: 8348562: ZGC: segmentation fault due to missing node type check in barrier elision analysis
175e58b: 8332980: [IR Framework] Add option to measure IR rule processing time
b8c68c0: 8348207: Linux PPC64 PCH build broken after JDK-8347909
70eec90: 8338303: Linux ppc64le with toolchain clang - detection failure in early JVM startup
a1fd5f4: 8348554: Enhance Linux kernel version checks
... and 27 more: https://git.openjdk.org/jdk/compare/7f16a0875ced8669b9d2131c67496a66e74ea36f...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

openjdk · 2025-01-24T01:51:04Z

@iklam To determine the appropriate audience for reviewing this pull request, one or more labels corresponding to different subsystems will normally be applied automatically. However, no automatic labelling rule matches the changes in this pull request. In order to have an "RFR" email sent to the correct mailing list, you will need to add one or more applicable labels manually using the /label pull request command.

Applicable Labels

build
client
compiler
core-libs
graal
hotspot
hotspot-compiler
hotspot-gc
hotspot-jfr
hotspot-runtime
i18n
ide-support
javadoc
jdk
jmx
kulla
net
nio
security
serviceability
shenandoah

iklam · 2025-01-24T16:48:51Z

/label hotspot-runtime

openjdk · 2025-01-24T16:49:39Z

@iklam
The hotspot-runtime label was successfully added.

mlbridge · 2025-01-24T17:08:28Z

Webrevs

vnkozlov

I am not sure if there is rule about ordering flags description alphabetically.
I would exactly reverse the order you have to put more important flags first.

vnkozlov · 2025-01-24T17:15:49Z

src/java.base/share/man/java.md

+-   A particular application (as expressed by `-classpath`, `-jar`, or `--module-path`.)
+-   A particular JDK release.
+-   A particular OS and CPU architecture.


What about VM's flags/settings (GCs for example)?

The impact of flags is duscissed in the "loading of an AOTCache can fail for a number of reasons" section below. Also, I chose not to enumerate all the possible flag incompatibilities, as there's a pretty exhaustive list in JEP 483.

iklam · 2025-01-27T04:59:08Z

I am not sure if there is rule about ordering flags description alphabetically. I would exactly reverse the order you have to put more important flags first.

I changed the order of flags to be: AOTCache -> AOTConfiguration -> AOTMode -> AOTClassLinking.

adinn · 2025-01-27T08:20:20Z

src/java.base/share/man/java.md

+
+-   **Assembly:** We use the AOT Configuration file to produce an AOTCache.
+
+-   **Production:** We execut the application with the AOTCache for better


typo: 'We execut' --> 'We execute'

vnkozlov

Good, except Andrew's comment.

adinn

Yes, all good and reads well.

iklam · 2025-01-28T00:12:06Z

Thanks @vnkozlov and @adinn for the review
/integrate

openjdk · 2025-01-28T00:12:59Z

Going to push as commit 46f48e4.
Since your change was applied there have been 43 commits pushed to the master branch:

1916a77: 8346923: MetaspaceShared base calculation may cause overflow in align_up
21feef3: 8348239: SA does not know about DeoptimizeObjectsALotThread
8cc1304: 8287788: Implement a better allocator for downcalls
039e73f: 8346736: Java Security Standard Algorithm Names spec should include key algorithm names
aba60a9: 8189441: Define algorithm names for keys derived from KeyAgreement
03106eb: 8344119: CUPSPrinter does not respect PostScript printer definition specification in case of reading ImageableArea values from PPD files
ad01dfb: 8346920: Serial: Support allocation in old generation when heap is almost full
1d8ccb8: 8342465: Improve API documentation for java.lang.classfile
7d6055a: 8348429: Update cross-compilation devkits to Fedora 41/gcc 13.2
f1e0797: 8348586: Optionally silence make warnings about non-control variables
... and 33 more: https://git.openjdk.org/jdk/compare/7f16a0875ced8669b9d2131c67496a66e74ea36f...master

Your commit was automatically rebased without conflicts.

openjdk · 2025-01-28T00:13:12Z

@iklam Pushed as commit 46f48e4.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

rose00 · 2025-01-28T00:15:52Z

The command line flag AOTCache is well documented, but the use of "AOTCache" as a term of art in narrative text is wrong. It should be "AOT cache".

For comparison, take any other camel-case flag like StringTableSize and ask yourself, would you like to read discussions (in email or man pages) of "the StringTableSize of the VM" or "the string table size of the VM"? Or, we speak of the LogFile command line option, but when we say what it does, it controls the "VM's output log file", not the "VM's output LogFile".

rose00 · 2025-01-28T00:16:50Z

(Oops, you just pushed; sorry about the late feedback. I still think the change should be made.)

rose00 · 2025-01-28T00:18:18Z

Also, the word "appication" is a typo. And "representitive". And "options" should be "option" in "If this options is specified".

rose00 · 2025-01-28T17:47:42Z

src/java.base/share/man/java.md

+The Ahead-of-Time Cache (AOTCache) is a container introduced in JDK 24 for
+storing artifacts produced by AOT optimizations. The AOTCache currently contains
+Java classes and heap objects. The plans is to include other types of artifacts,
+such as execution profiles and compiled methods, in future JDK releases.


s/plans/plan/ or reframe the sentence as:

In future JDK releases, the AOT cache may contain additional artifacts, such as execution profiles and compiled methods.

Sigh -- missed this one too. Sadly, English language grammar requires far more eyes than formal language grammar.

8348515: Add docs for -XX:AOT* options in java man pages

95f2f8d

openjdk bot added the hotspot-runtime hotspot-runtime-dev@openjdk.org label Jan 24, 2025

Fixed whitespaces

a9e9771

openjdk bot added the rfr Pull request is ready for review label Jan 24, 2025

vnkozlov reviewed Jan 24, 2025

View reviewed changes

iklam added 2 commits January 26, 2025 20:55

@vnkozlov comment: changed order of flags

4cef8a4

Grammar consistency

fce60ce

adinn reviewed Jan 27, 2025

View reviewed changes

vnkozlov approved these changes Jan 27, 2025

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Jan 27, 2025

@adinn comment - fixed typo

18d0a43

openjdk bot removed the ready Pull request is ready to be integrated label Jan 27, 2025

adinn approved these changes Jan 27, 2025

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Jan 27, 2025

openjdk bot added the integrated Pull request has been integrated label Jan 28, 2025

openjdk bot closed this Jan 28, 2025

openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Jan 28, 2025

rose00 reviewed Jan 28, 2025

View reviewed changes

iklam mentioned this pull request Jan 28, 2025

8348890: Fix docs for -XX:AOT* options in java man page #23343

Closed

3 tasks


		- Assembly: We use the AOT Configuration file to produce an AOTCache.

		- Production: We execut the application with the AOTCache for better

Conversation

iklam commented Jan 24, 2025 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issue

Reviewers

Reviewing

Uh oh!

bridgekeeper bot commented Jan 24, 2025

Uh oh!

openjdk bot commented Jan 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openjdk bot commented Jan 24, 2025

Uh oh!

iklam commented Jan 24, 2025

Uh oh!

openjdk bot commented Jan 24, 2025

Uh oh!

mlbridge bot commented Jan 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

vnkozlov left a comment

Choose a reason for hiding this comment

Uh oh!

vnkozlov Jan 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

iklam Jan 27, 2025

Choose a reason for hiding this comment

Uh oh!

iklam commented Jan 27, 2025

Uh oh!

adinn Jan 27, 2025

Choose a reason for hiding this comment

Uh oh!

vnkozlov left a comment

Choose a reason for hiding this comment

Uh oh!

adinn left a comment

Choose a reason for hiding this comment

Uh oh!

iklam commented Jan 28, 2025

Uh oh!

openjdk bot commented Jan 28, 2025

Uh oh!

openjdk bot commented Jan 28, 2025

Uh oh!

rose00 commented Jan 28, 2025

Uh oh!

rose00 commented Jan 28, 2025

Uh oh!

rose00 commented Jan 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rose00 Jan 28, 2025

Choose a reason for hiding this comment

Uh oh!

adinn Jan 29, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

iklam commented Jan 24, 2025 •

edited by openjdk bot

Loading

openjdk bot commented Jan 24, 2025 •

edited

Loading

mlbridge bot commented Jan 24, 2025 •

edited

Loading

vnkozlov Jan 24, 2025 •

edited

Loading

rose00 commented Jan 28, 2025 •

edited

Loading