You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Similar to HotSpot's -XX:+UnlockExperimentalVMOptions, we plan to introduce an -H:±UnlockExperimentalVMOptions option to explicitly unlock access to experimental options in Native Image.
Goals
Native Image provides numerous non-API build options (for public API options, see native-image --help). To make users more aware of the fact that their Native Image builds rely on experimental options, to prevent misuse, and to help us identify options that users rely on in the first place, we plan to introduce an -H:±UnlockExperimentalVMOptions option that must be used to explicitly unlock access to experimental build options. If access is not explicitly requested, an attempt to use any experimental option will fail the build with an actionable error message. Using -H:±UnlockExperimentalVMOptions without actually using any experimental option will print a warning.
To allow this option to be used in a composable way, we intend to enforce the following rules:
Experimental options can only be used in an appropriate scope that starts with -H:+UnlockExperimentalVMOptions and ends with -H:-UnlockExperimentalVMOptions.
Example 1: native-image -H:+UnlockExperimentalVMOptions -H:SomeExperimentalOption -H:-UnlockExperimentalVMOptions -cp ./ HelloWorld.
While not encouraged, -H:-UnlockExperimentalVMOptions can be left out for convenience. The scope will be closed at the end of the argument list that is currently being processed.
Example 2: native-image -H:+UnlockExperimentalVMOptions -H:SomeExperimentalOption -cp ./ HelloWorld. This works just like Example 1 except that it also allows other dependencies on the classpath to use experimental options.
Libraries and frameworks can use -H:±UnlockExperimentalVMOptions within the Args property of their native-image.properties files.
Example 3: Args = -H:+UnlockExperimentalVMOptions -cp lib-dependency-using-experimental-options.jar. This unlocks experimental options for the additional dependency that is added to the classpath. Note that it does not unlock experimental options for arguments provided by other native-image.properties files. Due to Rule 2, it is equivalent to using Args = -H:+UnlockExperimentalVMOptions -cp lib-dependency-using-experimental-options.jar -H:-UnlockExperimentalVMOptions.
To help users understand who or which library or framework requested these options, active experimental options will be listed as part of the build output alongside their origin.
For the initial classification of options, we propose the following:
All API options are non-experimental.
For non-API options, we use org.graalvm.compiler.options.Option#stability to determine if we consider the option stable. I.e. if an option has @Option(stability = OptionStability.STABLE), we consider it non-experimental even though it is not an API option.
For certain widely used non-API options, we need to adjust the Option#stability field to classify them as non-experimental. (e.g. com.oracle.svm.hosted.image.CCLinkerInvocation.Options#NativeLinkerOption).
Non-Goals
Significantly extend the Native Image API with more options.
Deprecate or remove any experimental options.
The text was updated successfully, but these errors were encountered:
`-H:ReflectionConfigurationResources`
- Reported in `netty`: netty/netty#13595.
- Fixed in `netty`: netty/netty#13596.
- See also similar issue in
Karm/mandrel-integration-tests#190 and its
workaround in
Karm/mandrel-integration-tests#203.
`-H:Log=registerResource, -H:Log=registerResource:`
- Added explicitly by `APP_FULL_MICROPROFILE` config.
- Typical use case documented in Quarkus Native Reference Guide,
the documentation was added in
quarkusio/quarkus#36494.
- Allow-listed, instead of using `-H:+UnlockExperimentalVMOptions` /
`-H:-UnlockExperimentalVMOptions`, to avoid errors with GraalVM /
Mandrel based on Java < 21, which do not recognize this option
(see oracle/graal#7105).
TL;DR
Similar to HotSpot's
-XX:+UnlockExperimentalVMOptions
, we plan to introduce an-H:±UnlockExperimentalVMOptions
option to explicitly unlock access to experimental options in Native Image.Goals
Native Image provides numerous non-API build options (for public API options, see
native-image --help
). To make users more aware of the fact that their Native Image builds rely on experimental options, to prevent misuse, and to help us identify options that users rely on in the first place, we plan to introduce an-H:±UnlockExperimentalVMOptions
option that must be used to explicitly unlock access to experimental build options. If access is not explicitly requested, an attempt to use any experimental option will fail the build with an actionable error message. Using-H:±UnlockExperimentalVMOptions
without actually using any experimental option will print a warning.To allow this option to be used in a composable way, we intend to enforce the following rules:
Experimental options can only be used in an appropriate scope that starts with
-H:+UnlockExperimentalVMOptions
and ends with-H:-UnlockExperimentalVMOptions
.While not encouraged,
-H:-UnlockExperimentalVMOptions
can be left out for convenience. The scope will be closed at the end of the argument list that is currently being processed.Libraries and frameworks can use
-H:±UnlockExperimentalVMOptions
within theArgs
property of theirnative-image.properties
files.To help users understand who or which library or framework requested these options, active experimental options will be listed as part of the build output alongside their origin.
For the initial classification of options, we propose the following:
org.graalvm.compiler.options.Option#stability
to determine if we consider the option stable. I.e. if an option has@Option(stability = OptionStability.STABLE)
, we consider it non-experimental even though it is not an API option.Option#stability
field to classify them as non-experimental. (e.g.com.oracle.svm.hosted.image.CCLinkerInvocation.Options#NativeLinkerOption
).Non-Goals
The text was updated successfully, but these errors were encountered: