JDK-8354350 : [CSR draft] Add AOT command line options for ergonomic train-and-assemble command
  • Type: Enhancement
  • Component: hotspot
  • Sub-Component: runtime
  • Priority: P4
  • Status: Open
  • Resolution: Unresolved
  • Submitted: 2025-04-11
  • Updated: 2025-04-26
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 25
25Unresolved
Related Reports
Relates :  
JDK-8350022 - Ahead-of-time Command Line Ergonomics
Description
<!-- v.2 2025-04-25 -->

Summary
-------

Add flags to further control AOT operations, as initially defined in [JEP 483].  The new flags will allow a single command (invocation of the JVM) to perform a combined "train and assemble" function.

[JEP 483]: <https://openjdk.org/jeps/483>

Problem
-------

In [JEP 483] an AOT cache must be requested by issuing a pair of commands (invocations of the JVM), which communicate by a temporary file which the user must name and manage (ie., delete after completion).

We define a new JVM invocation mode, a _combined training and assembly_ operation.

The additional flags of this CSR are necessary to trigger the new combined operation, and to control its details.

See the JEP <https://bugs.openjdk.org/browse/JDK-8350022> for more details on the new operation, including its motivation and envisioned usage.

See the CSR <https://bugs.openjdk.org/browse/JDK-8338243> for details on the pre-existing flags of [JEP 483].

Solution
--------

Extend the existing `AOTCache` command option with one directional inflection, `AOTCacheOutput`.

Then, adjust default behaviors (under `AOTMode=auto` and `AOTMode=record`) to invoke an extra _sub-command_ of the JVM (with `AOTMode=create`), when the user runs a Java application with `AOTCacheOutput`.  This will assist the user by orchestrating the steps necessary to creating an AOT cache in one command invocation.

Also, add a new environment variable `JAVA_AOT_OPTIONS`, closely akin to `JAVA_TOOL_OPTIONS`, to control fine details of the second sub-command (AOT cache assembly).  All initial VM options are passed to both sub-commands, and `JAVA_AOT_OPTIONS` is picked up only by the second sub-command.

Specification
-------------

[1] The new `ccstr` option `AOTCacheOutput` supplies the same data as `AOTCache`, but is always interpreted in the output direction.  As such, it is illegal for operation modes which read an AOT cache file, notably `AOTMode=on` (a production run).  It is illegal to specify both `AOTCache` and `AOTCacheOutput` on the same command line.

[2] `AOTCacheOutput`, when no `AOTMode` option is present (or either `AOTMode=auto` or `AOTMode=record` is explicitly present), requests the new behavior, of combined training and assembly.  The presence of an AOT output option switches on `AOTMode=record`, which operates as before, after which a second sub-command operates with `AOTMode=create`.

During combined training and assembly, the VM invocation is automatically split (transparently to the user) into two VM invocations.  One sub-command operates with `AOTMode=record`, and the second sub-commmand operates with `AOTMode=create`.  They share all other options passed into the original command.

_Rationale:_ It is much easier to explain one command splitting into two sub-commands running under two pre-existing modes, than to explain the interactions of a new combined mode with all other VM features.  That is why we choose not to invent a new mode such as `record+create`.

[3] During combined training and assembly, any `AOTConfiguration` option present (from [JEP 483]) works as previously documented.  That is, the named file is written, then read, and not deleted.  But as a new behavior, if `AOTConfiguration` is not specified on the command line, the VM chooses a temporary file name, not interfering with any existing file, and uses it to transmit AOT configuration from the first sub-command to the second.  This file is deleted after use.  Indeed, the VM implementation is free to use any appropriate means, instead of a temporary file, for transmitting this data between sub-commands.

[4] During combined training and assembly, the training sub-command (`AOTMode=record`) does not act on the `AOTCacheOutput`; it applies only to the sub-command (`AOTMode=create`).

[5] The pre-existing environment variable `JAVA_TOOL_OPTIONS` takes effect as usual when the VM starts up.  Sub-commands may be thought of as receiving edited versions of the original VM options, as if via `JAVA_TOOL_OPTIONS`, and debugging mechanisms (based on `-Xlog`) will provide a view of the flags being passed to the sub-commands.  Note that only the training sub-command receives the Java application main class and arguments.

[6] If the new environment variable `JAVA_AOT_OPTIONS` is present and non-empty, and the option `AOTMode=create` is present in either the command line or `JAVA_TOOL_OPTIONS`, then `JAVA_AOT_OPTIONS` is scanned, as if it were (logically) appended to `JAVA_TOOL_OPTIONS`.  In this way, an advanced user can adjust the configuration of the second sub-command, or (in fact) of any `AOTMode=create` command that may execute under the influence of that environment variable.

_Rationale:_ Maintainers of the `jruby` launcher have requested that the JVM handle the details of AOT configuration management and sub-command launching, but launchers sometimes need fine control over sub-commands that they invoke directly or indirectly.  This environment variable gives a necessary hook for such fine control.  The same argument applies more generally to script-based use of the JVM, where both `$JAVA_TOOL_OPTIONS` and `$JAVA_AOT_OPTIONS` environment variables are likely to be useful for injecting common options used by the whole script.  The specific use of `$JAVA_AOT_OPTIONS` is also likely to be useful for testing, diagnosis, and research related to AOT technologies.

[7] In many file options of the HotSpot JVM, the special string `%p` (percent-p) is replaced by a representation of the process identification number of the JVM which the user launches.  (It is always the user’s job to find such unpredictably-named files after they are produced.)  This replacement occurs on the `AOTCache`, `AOTCacheOutput`, and `AOTConfiguration` options as well.  The replacement is done in the parent sub-command, not the child sub-command, so that the number N always corresponds to the JVM process that the user launched.  This expansion rule applies to all AOT modes, not just the new behavior.

_Note:_ This is a slightly incompatible change from JDK 24, in that some file names containing the substring `%p` are not currently expanded.  This substring `%p`, standard to HotSpot, is chosen so as to be unlikely to occur unintentionally.

With these changes in place, the combined AOT story runs as follows.

If the `AOTMode` option is not mentioned, it starts with a default setting (of `auto`, as documented in [JEP 483]), and is then ergonomically reset to be consistent with the other AOT options.  If `AOTCacheOutput` is present, the mode is ergonomically set to `record` and then `create`, implementing combined training and assembly.  Also, in this case, if no `AOTConfiguration` name is given, the configuration output and input is managed as a temporary file.

Note that while `AOTCache` denotes either input or output (depending on `AOTMode`), the new options `AOTCacheOutput` fully disambiguate data flow direction into or out of AOT cache files, regardless of mode.  Thus, `AOTCacheOutput` will always create an AOT cache.

Note also that in `AOTMode=create` only, the `-XX:AOTCache=newcache.aot` option specifies an _output_ AOT cache file, not an input.  In that mode, the output direction may be specified explicitly as well, using the new option `-XX:AOTCacheOutput=newcache.aot`.

If the `-XX:AOTConfiguration` option is present on the command line, that file name will be used, and the file will be retained after the Java launcher exits.  Otherwise, it will be deleted (if it ever existed) after exit.

Thus, the `AOTMode` and `AOTConfiguration` options are not needed for simple AOT cache creation.  At a minimum, with the given set of default behaviors, an `AOTCacheOutput` option suffices to trigger creation of an AOT cache from a training run.

In some advanced use cases, the AOT cache assembly process may need special assembly-specific command line options that differ from the training run.  This is handled directly in the old two-command workflow, by simply handing the assembly-specific command line options to the second explicit command (assembly) but not the first (training).  With the one-command workflow, assembly-specific options can be passed via the `JAVA_AOT_OPTIONS` environment variable.

There is currently no corresponding proposal for passing options only to the first sub-command (training run).  That is because most options passed to the training run can be modified by subsequent settings (in `JAVA_AOT_OPTIONS`) of the same option.

A combined training and assembly command applies all command line options first to the training run.  Then, the options are also passed to the AOT assembly phase, as if by `JAVA_TOOL_OPTIONS`.  After these options are processed, any options in the environment string `JAVA_AOT_OPTIONS` are also applied to the AOT assembly phase.

A script or launcher may launch many JVM instances.  If it is desired to create AOT caches for all of them, the option `-XX:AOTCacheOutput=cache%p.aot` can be added into the `JAVA_TOOL_OPTIONS` environment string.

The syntax of the `JAVA_TOOL_OPTIONS` (and thus `JAVA_AOT_OPTIONS`) environment variable is documented here:

<https://docs.oracle.com/en/java/javase/24/docs/specs/jvmti.html#tooloptions>