Flag for future default behavior of Native Image

Author: vjovanov

docs/reference-manual/native-image/BuildOutput.md

@@ -282,6 +282,12 @@ This feature is currently only available for code compiled by Graal for Linux AM
 
 The build output may contain one or more of the following recommendations that help you get the best out of Native Image.
 
+#### <a name="recommendation-futr"></a>`FUTR`: Use the Correct Semantics and Prepare for the Future Releases
+
+Use `--future-defaults=all` to ensure that the executable aligns more closely with JVM semantics and to prepare for future GraalVM releases where this will become the default.
+This flag is unlikely to affect your program's behavior but guarantees that it adheres to the correct execution semantics.
+Additionally, it ensures that future GraalVM updates will not introduce unexpected changes to your program's behavior.
+
 #### <a name="recommendation-awt"></a>`AWT`: Missing Reachability Metadata for Abstract Window Toolkit
 
 The Native Image analysis has included classes from the [`java.awt` package](https://docs.oracle.com/en/java/javase/22/docs/api/java.desktop/java/awt/package-summary.html) but could not find any reachability metadata for it.

substratevm/CHANGELOG.md

@@ -11,6 +11,8 @@ This changelog summarizes major changes to GraalVM Native Image.
 * (GR-61492) The experimental JDWP option is now present in standard GraalVM builds.
 * (GR-55222) Enabled lazy deoptimization of runtime-compiled code, which reduces memory used for deoptimization. Can be turned off with `-H:-LazyDeoptimization`.
 * (GR-54953) Add the experimental option `-H:Preserve` that makes the program work correctly without providing reachability metadata. Correctness is achieved by preserving all classes, resources, and reflection metadata in the image. Usage: `-H:Preserve=[all|none|module=<module>|package=<package>|package=<package-wildcard>|path=<cp-entry>][,...]`.
+* (GR-49525) Introduced `--future-defaults=[all|<options>|none]` that allows for gentle migration to the future default behaviors of Native Image. The enabled behaviors are:
+    1. `run-time-initialized-jdk` that moves away from build-time initialization of the JDK.
 
 ## GraalVM for JDK 24 (Internal Version 24.2.0)
 * (GR-59717) Added `DuringSetupAccess.registerObjectReachabilityHandler` to allow registering a callback that is executed when an object of a specified type is marked as reachable during heap scanning.

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/SubstrateOptions.java

@@ -36,10 +36,13 @@
 import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.util.List;
+import java.util.Objects;
+import java.util.Set;
 import java.util.UUID;
 import java.util.function.Predicate;
 
 import org.graalvm.collections.EconomicMap;
+import org.graalvm.collections.EconomicSet;
 import org.graalvm.collections.UnmodifiableEconomicMap;
 import org.graalvm.nativeimage.ImageInfo;
 import org.graalvm.nativeimage.ImageSingletons;
@@ -1381,4 +1384,79 @@ public static class TruffleStableOptions {
 
     @Option(help = "file:doc-files/LibGraalClassLoader.txt")//
     public static final HostedOptionKey<String> LibGraalClassLoader = new HostedOptionKey<>("");
+
+    private static final String FUTURE_DEFAULTS_OPTION = "future-defaults";
+
+    private static final String FUTURE_DEFAULTS_DEFAULT_NAME = "<default-value>";
+    private static final String FUTURE_DEFAULTS_ALL_NAME = "all";
+    private static final String FUTURE_DEFAULTS_NONE_NAME = "none";
+    private static final String FUTURE_DEFAULTS_RUN_TIME_INITIALIZE_JDK_NAME = "run-time-initialized-jdk";
+
+    /**
+     * Note: what makes it into the future-defaults must not be an experimental feature that can be
+     * rolled back. The changes must be aligning native image with the Java spec and must be
+     * thoroughly reviewed.
+     */
+    private static final Set<String> FUTURE_DEFAULTS_ALL_VALUES = Set.of(FUTURE_DEFAULTS_RUN_TIME_INITIALIZE_JDK_NAME, FUTURE_DEFAULTS_ALL_NAME, FUTURE_DEFAULTS_NONE_NAME);
+    private static final String FUTURE_DEFAULTS_ALLOWED_VALUES_TEXT = "'" + FUTURE_DEFAULTS_ALL_NAME + "'" +
+                    ", '" + FUTURE_DEFAULTS_RUN_TIME_INITIALIZE_JDK_NAME + "'" +
+                    ", or '" + FUTURE_DEFAULTS_NONE_NAME + "'";
+
+    static {
+        assert FUTURE_DEFAULTS_ALL_VALUES.stream().allMatch(FUTURE_DEFAULTS_ALLOWED_VALUES_TEXT::contains) : "A value is missing in the user-facing help text";
+    }
+
+    @APIOption(name = FUTURE_DEFAULTS_OPTION, defaultValue = FUTURE_DEFAULTS_DEFAULT_NAME) //
+    @Option(help = "Enable the future default behaviors for Native Image. Comma-separated list can contain " + FUTURE_DEFAULTS_ALLOWED_VALUES_TEXT + ". " +
+                    "For example: '--" + FUTURE_DEFAULTS_OPTION + "=" + FUTURE_DEFAULTS_ALL_NAME + "'.", type = OptionType.User) //
+    public static final HostedOptionKey<AccumulatingLocatableMultiOptionValue.Strings> FutureDefaults = new HostedOptionKey<>(
+                    AccumulatingLocatableMultiOptionValue.Strings.buildWithCommaDelimiter());
+
+    private static EconomicSet<String> futureDefaults;
+
+    @Platforms(Platform.HOSTED_ONLY.class)
+    public static void processFutureDefaults() {
+        futureDefaults = EconomicSet.create(FUTURE_DEFAULTS_ALL_VALUES.size());
+        var valuesWithOrigin = FutureDefaults.getValue().getValuesWithOrigins();
+        valuesWithOrigin.forEach(valueWithOrigin -> {
+            String value = valueWithOrigin.value();
+            if (FUTURE_DEFAULTS_DEFAULT_NAME.equals(value)) {
+                throw UserError.abort("The '%s' from %s is forbidden. It can only contain: %s.",
+                                SubstrateOptionsParser.commandArgument(FutureDefaults, FUTURE_DEFAULTS_DEFAULT_NAME),
+                                valueWithOrigin.origin(),
+                                FUTURE_DEFAULTS_ALLOWED_VALUES_TEXT);
+            }
+
+            if (!FUTURE_DEFAULTS_ALL_VALUES.contains(value)) {
+                throw UserError.abort("The '%s' option from %s contains invalid value '%s'. It can only contain: %s.",
+                                SubstrateOptionsParser.commandArgument(FutureDefaults, value),
+                                valueWithOrigin.origin(),
+                                value,
+                                FUTURE_DEFAULTS_ALLOWED_VALUES_TEXT);
+            }
+
+            if (value.equals(FUTURE_DEFAULTS_NONE_NAME)) {
+                if (!valueWithOrigin.origin().commandLineLike()) {
+                    throw UserError.abort("The '%s' option can only be used from the command line. Detected usage from %s.",
+                                    SubstrateOptionsParser.commandArgument(FutureDefaults, FUTURE_DEFAULTS_NONE_NAME),
+                                    valueWithOrigin.origin());
+                }
+                futureDefaults.clear();
+            }
+
+            futureDefaults.add(value);
+        });
+    }
+
+    private static EconomicSet<String> getFutureDefaults() {
+        return Objects.requireNonNull(futureDefaults, "must be initialized before usage");
+    }
+
+    public static boolean allFutureDefaults() {
+        return getFutureDefaults().contains(FUTURE_DEFAULTS_ALL_NAME);
+    }
+
+    public static boolean isJDKInitializedAtRunTime() {
+        return allFutureDefaults() || getFutureDefaults().contains(FUTURE_DEFAULTS_RUN_TIME_INITIALIZE_JDK_NAME);
+    }
 }

substratevm/src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/NativeImageGenerator.java

@@ -919,7 +919,7 @@ protected void setupNativeImage(String imageName, OptionValues options, Map<Meth
 
                 ImageSingletons.add(SubstrateOptions.ReportingSupport.class, new SubstrateOptions.ReportingSupport(
                                 DiagnosticsMode.getValue() ? DiagnosticsDir.getValue().lastValue().get() : Path.of("reports")));
-
+                SubstrateOptions.processFutureDefaults();
                 if (javaMainSupport != null) {
                     ImageSingletons.add(JavaMainSupport.class, javaMainSupport);
                 }

substratevm/src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/ProgressReporterFeature.java

@@ -106,12 +106,17 @@ public void createAdditionalArtifactsOnSuccess(@SuppressWarnings("unused") Build
 
     protected List<UserRecommendation> getRecommendations() {
         return List.of(// in order of appearance:
+                        new UserRecommendation("FUTR", "Use --future-defaults=all to prepare for future releases.", ProgressReporterFeature::recommendFutureDefaults),
                         new UserRecommendation("AWT", "Use the tracing agent to collect metadata for AWT.", ProgressReporterFeature::recommendTraceAgentForAWT),
                         new UserRecommendation("HOME", "To avoid errors, provide java.home to the app with '-Djava.home=<path>'.", AnalyzeJavaHomeAccessFeature.instance()::getJavaHomeUsed),
                         new UserRecommendation("HEAP", "Set max heap for improved and more predictable memory usage.", () -> SubstrateGCOptions.MaxHeapSize.getValue() == 0),
                         new UserRecommendation("CPU", "Enable more CPU features with '-march=native' for improved performance.", ProgressReporterFeature::recommendMArchNative));
     }
 
+    private static boolean recommendFutureDefaults() {
+        return !SubstrateOptions.allFutureDefaults();
+    }
+
     private static boolean recommendMArchNative() {
         if (NativeImageOptions.MicroArchitecture.getValue() != null) {
             return false; // explicitly set by user

substratevm/src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/jdk/JDKInitializationFeature.java

@@ -31,6 +31,7 @@
 import org.graalvm.nativeimage.impl.RuntimeClassInitializationSupport;
 
 import com.oracle.svm.core.ParsingReason;
+import com.oracle.svm.core.SubstrateOptions;
 import com.oracle.svm.core.TypeResult;
 import com.oracle.svm.core.feature.AutomaticallyRegisteredFeature;
 import com.oracle.svm.core.feature.InternalFeature;
@@ -143,9 +144,16 @@ public void afterRegistration(AfterRegistrationAccess access) {
         rci.initializeAtBuildTime("java.awt.font.JavaAWTFontAccessImpl", "Required for sun.text.bidi.BidiBase.NumericShapings");
 
         /* XML-related */
-        rci.initializeAtBuildTime("com.sun.xml", JDK_CLASS_REASON);
-        rci.initializeAtBuildTime("com.sun.org.apache", JDK_CLASS_REASON);
-        rci.initializeAtBuildTime("com.sun.org.slf4j.internal", JDK_CLASS_REASON);
+        if (SubstrateOptions.isJDKInitializedAtRunTime()) {
+            // GR-50683 should remove this part
+            rci.initializeAtBuildTime("com.sun.xml", JDK_CLASS_REASON);
+            rci.initializeAtBuildTime("com.sun.org.apache", JDK_CLASS_REASON);
+            rci.initializeAtBuildTime("com.sun.org.slf4j.internal", JDK_CLASS_REASON);
+        } else {
+            rci.initializeAtBuildTime("com.sun.xml", JDK_CLASS_REASON);
+            rci.initializeAtBuildTime("com.sun.org.apache", JDK_CLASS_REASON);
+            rci.initializeAtBuildTime("com.sun.org.slf4j.internal", JDK_CLASS_REASON);
+        }
 
         /* Security services */
         rci.initializeAtBuildTime("com.sun.crypto.provider", JDK_CLASS_REASON);