RFR: 8273853: Update the Java manpage for automatic CDS archive updating

[David Holmes]

On Fri, 3 Jun 2022 20:45:24 GMT, Ioi Lam <iklam at openjdk.org> wrote:

> Added description of the new flag `-XX:+AutoCreateSharedArchive` to the `java` man page.

Some aspects of the description are not clear to me.

Thanks,
David

src/java.base/share/man/java.1 line 5379:

> 5377: .SS Manually Creating CDS Archives
> 5378: .PP
> 5379: CDS archives can be created manually with several methods:

Pre-existing nit: s/with/using/

src/java.base/share/man/java.1 line 5555:

> 5553: Otherwise the JVM will not load the specified archive.
> 5554: Instead, it will automatically create (or update) the archive file at
> 5555: exit.

The use of "otherwise" and "instead" is unclear in the context of an existing archive file. What exactly will happen?
1. If the file exists and was created by the same JDK version then it will be used.
2. Regardless of (1) the named archive file will be written at VM exit, ready for use the next time?
Is (2) correct even if the file exists and is from a different JDK version? Or do we only write the file if it either didn't exist, or is from the same JDK version?

src/java.base/share/man/java.1 line 5563:

> 5561: Therefore, if you upgrade to a newer JDK,
> 5562: \f[CB]\-XX:+AutoCreateSharedArchive\f[R] will automatically recreate the
> 5563: archive.

But the first time you run it won't be able to use the existing archive file. This also suggests that the answer above is that the file will always get written at exit, regardless of the version or whether it pre-existed.

-------------

PR: https://git.openjdk.java.net/jdk/pull/9024