Flag that enables future behavoir for Native Image

Author: vjovanov

sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/impl/RuntimeClassInitializationSupport.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2018, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -67,4 +67,11 @@ default void rerunInitialization(Class<?> aClass, String reason) {
     }
 
     void initializeAtBuildTime(Class<?> aClass, String reason);
+
+    /**
+     * Returns if the <code>className</code> was marked for build-time initialization. The result
+     * applies both if a package prefix or a fully-qualified class name were configured as build
+     * time.
+     */
+    boolean isMarkedForBuildTimeInitialization(String className);
 }

substratevm/CHANGELOG.md

@@ -11,6 +11,7 @@ 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|jdk-at-run-time]` that allows for gentle migration to the future default behaviors of Native Image. The first enable behavior is `jdk-at-run-time` 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,12 @@
 import java.nio.file.Path;
 import java.nio.file.Paths;
 import java.util.List;
+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;
@@ -166,9 +168,7 @@ protected void onValueUpdate(EconomicMap<OptionKey<?>, Object> values, Boolean o
         @Override
         public String getValueOrDefault(UnmodifiableEconomicMap<OptionKey<?>, Object> values) {
             if (!values.containsKey(this)) {
-                return Platform.includedIn(Platform.ANDROID.class)
-                                ? "bionic"
-                                : System.getProperty("substratevm.HostLibC", "glibc");
+                return Platform.includedIn(Platform.ANDROID.class) ? "bionic" : System.getProperty("substratevm.HostLibC", "glibc");
             }
             return (String) values.get(this);
         }
@@ -884,9 +884,8 @@ protected void onValueUpdate(EconomicMap<OptionKey<?>, Object> values, String ol
                     isLLVMBackendMissing = ReflectionUtil.lookupClass(true, "com.oracle.svm.core.graal.llvm.LLVMFeature") == null;
                 }
                 if (isLLVMBackendMissing) {
-                    throw UserError.invalidOptionValue(CompilerBackend, newValue,
-                                    "The LLVM backend for GraalVM Native Image is missing and needs to be built from source. " +
-                                                    "For instructions, please see https://github.com/oracle/graal/blob/master/docs/reference-manual/native-image/LLVMBackend.md.");
+                    throw UserError.invalidOptionValue(CompilerBackend, newValue, "The LLVM backend for GraalVM Native Image is missing and needs to be built from source. " +
+                                    "For instructions, please see https://github.com/oracle/graal/blob/master/docs/reference-manual/native-image/LLVMBackend.md.");
                 }
 
                 /* See GR-14405, https://github.com/oracle/graal/issues/1056 */
@@ -1277,6 +1276,10 @@ public Boolean getValueOrDefault(UnmodifiableEconomicMap<OptionKey<?>, Object> v
                     deprecated = true, deprecationMessage = "This option was introduced to simplify migration to GraalVM 23.0 and will be removed in a future release")//
     public static final HostedOptionKey<Boolean> AllowDeprecatedBuilderClassesOnImageClasspath = new HostedOptionKey<>(false);
 
+    @Option(help = "Initialize JDK classes at build time the same way it was done before GraalVM 25.", type = OptionType.Debug, //
+                    deprecated = true, deprecationMessage = "This option was introduced to simplify migration to GraalVM 25 and will be removed in a future release")//
+    public static final HostedOptionKey<Boolean> InitializeJDKAtBuildTimeMigration = new HostedOptionKey<>(false);
+
     @APIOption(name = "exact-reachability-metadata", defaultValue = "")//
     @Option(help = "file:doc-files/ExactReachabilityMetadataHelp.txt")//
     public static final HostedOptionKey<AccumulatingLocatableMultiOptionValue.Strings> ThrowMissingRegistrationErrors = new HostedOptionKey<>(AccumulatingLocatableMultiOptionValue.Strings.build());
@@ -1381,4 +1384,63 @@ 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_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";
+
+    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_NONE_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(),
+                    SubstrateOptions::validateFutureDefaults) {
+        @Override
+        protected void onValueUpdate(EconomicMap<OptionKey<?>, Object> values, AccumulatingLocatableMultiOptionValue.Strings oldValue, AccumulatingLocatableMultiOptionValue.Strings newValue) {
+            super.onValueUpdate(values, oldValue, newValue);
+        }
+    };
+
+    private static EconomicSet<String> futureDefaults;
+
+    @Platforms(Platform.HOSTED_ONLY.class)
+    public static void validateFutureDefaults(HostedOptionKey<AccumulatingLocatableMultiOptionValue.Strings> optionKey) {
+        futureDefaults = EconomicSet.create(FUTURE_DEFAULTS_ALL_VALUES.size());
+        var valuesWithOrigin = optionKey.getValue().getValuesWithOrigins();
+        valuesWithOrigin.forEach(valueWithOrigin -> {
+            String value = valueWithOrigin.value();
+            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);
+        });
+    }
+
+    public boolean isJDKInitializedAtRunTime() {
+        return futureDefaults.contains(FUTURE_DEFAULTS_ALL_NAME) || futureDefaults.contains(FUTURE_DEFAULTS_RUN_TIME_INITIALIZE_JDK_NAME);
+    }
 }

substratevm/src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/classinitialization/ClassInitializationFeature.java

@@ -198,10 +198,12 @@ private void checkImageHeapInstance(DuringAnalysisAccess access, Object obj, Obj
             msg += """
                             If you are seeing this message after upgrading to a new GraalVM release, this means that some objects ended up in the image heap without their type being marked with --initialize-at-build-time.
                             To fix this, include %s in your configuration. If the classes do not originate from your code, it is advised to update all library or framework dependencies to the latest version before addressing this error.
+                            If the classes originate from the JDK you can try to use %s to temporarily disable this error until the proper configuration is introduced for the project.
                             """
                             .replaceAll("\n", System.lineSeparator())
                             .formatted(SubstrateOptionsParser.commandArgument(ClassInitializationOptions.ClassInitialization, proxyOrLambda ? proxyLambdaInterfaceCSV : typeName,
-                                            "initialize-at-build-time", true, false));
+                                            "initialize-at-build-time", true, false),
+                                            SubstrateOptionsParser.commandArgument(SubstrateOptions.InitializeJDKAtBuildTimeMigration, "+"));
 
             msg += System.lineSeparator() + "The following detailed trace displays from which field in the code the object was reached.";
             throw new UnsupportedFeatureException(msg);

substratevm/src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/classinitialization/ClassInitializationSupport.java

@@ -287,6 +287,11 @@ public void initializeAtBuildTime(String name, String reason) {
         }
     }
 
+    @Override
+    public boolean isMarkedForBuildTimeInitialization(String className) {
+        return InitKind.BUILD_TIME == classInitializationConfiguration.lookupKind(className).getLeft();
+    }
+
     static boolean isClassListedInStringOption(AccumulatingLocatableMultiOptionValue.Strings option, Class<?> clazz) {
         return option.values().contains(clazz.getName());
     }

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

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2025, 2025, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package com.oracle.svm.hosted.jdk;
+
+import static com.oracle.svm.core.SubstrateOptions.InitializeJDKAtBuildTimeMigration;
+
+import com.oracle.svm.core.feature.AutomaticallyRegisteredFeature;
+import com.oracle.svm.core.feature.InternalFeature;
+
+@AutomaticallyRegisteredFeature
+public class JDKInitializationMigrationFeature implements InternalFeature {
+
+    @Override
+    public void afterRegistration(AfterRegistrationAccess access) {
+        // Checkstyle: stop
+        if (InitializeJDKAtBuildTimeMigration.getValue()) {
+            /* Place all excluded entries from JDKInitializationFeature here. */
+        }
+        // Checkstyle: resume
+    }
+}