[GR-47647] Explicit Experimental Option Handling

[fniephaus]

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:

1. 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.

2. 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.

3. 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.