[GR-50267] Deprecate options that we plan to remove in a future GraalVM release.

PullRequest: graal/16166

Author: Christian Wimmer

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

@@ -400,7 +400,8 @@ public static void updateMaxJavaStackTraceDepth(EconomicMap<OptionKey<?>, Object
     @Option(help = "Verify naming conventions during image construction.")//
     public static final HostedOptionKey<Boolean> VerifyNamingConventions = new HostedOptionKey<>(false);
 
-    @Option(help = "Enable support for threads and and thread-local variables (disable for single-threaded implementation)")//
+    @Option(help = "Enable support for threads and and thread-local variables (disable for single-threaded implementation)", //
+                    deprecated = true, deprecationMessage = "This special mode to build images that cannot start any additional threads has no benefits anymore and will be removed in a future release")//
     public static final HostedOptionKey<Boolean> MultiThreaded = new HostedOptionKey<>(true);
 
     @Option(help = "Use only a writable native image heap (requires ld.gold linker)")//
@@ -409,7 +410,7 @@ public static void updateMaxJavaStackTraceDepth(EconomicMap<OptionKey<?>, Object
     @Option(help = "Force no direct relocations to be present in the text section of the generated image", type = OptionType.Debug) //
     public static final HostedOptionKey<Boolean> NoDirectRelocationsInText = new HostedOptionKey<>(true);
 
-    @Option(help = "Support multiple isolates.") //
+    @Option(help = "Support multiple isolates.", deprecated = true, deprecationMessage = "This option disables a major feature of GraalVM Native Image and will be removed in a future release") //
     public static final HostedOptionKey<Boolean> SpawnIsolates = new HostedOptionKey<>(true);
 
     @Option(help = "At CEntryPoints check that the passed IsolateThread is valid.") //
@@ -968,7 +969,7 @@ protected void onValueUpdate(EconomicMap<OptionKey<?>, Object> values, String ol
     @Option(help = "Verify type states computed by the static analysis at run time. This is useful when diagnosing problems in the static analysis, but reduces peak performance significantly.", type = OptionType.Debug)//
     public static final HostedOptionKey<Boolean> VerifyTypes = new HostedOptionKey<>(false);
 
-    @Option(help = "Run reachability handlers concurrently during analysis.", type = Expert)//
+    @Option(help = "Run reachability handlers concurrently during analysis.", type = Expert, deprecated = true, deprecationMessage = "This option was introduced to simplify migration to GraalVM 22.2 and will be removed in a future release")//
     public static final HostedOptionKey<Boolean> RunReachabilityHandlersConcurrently = new HostedOptionKey<>(true);
 
     @Option(help = "Force many trampolines to be needed for inter-method calls. Normally trampolines are only used when a method destination is outside the range of a pc-relative branch instruction.", type = OptionType.Debug)//
@@ -990,7 +991,8 @@ public Boolean getValueOrDefault(UnmodifiableEconomicMap<OptionKey<?>, Object> v
         }
     };
 
-    @Option(help = "Instead of abort, only warn if image builder classes are found on the image class-path.", type = OptionType.Debug)//
+    @Option(help = "Instead of abort, only warn if image builder classes are found on the image class-path.", type = OptionType.Debug, //
+                    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 = "file:doc-files/MissingRegistrationHelp.txt")//
@@ -1023,7 +1025,7 @@ public enum ReportingMode {
     @Option(help = "Enable and disable normal processing of flags relating to experimental options.", type = OptionType.Expert, stability = OptionStability.EXPERIMENTAL) //
     public static final HostedOptionKey<Boolean> UnlockExperimentalVMOptions = new HostedOptionKey<>(false);
 
-    @Option(help = "Force using legacy method handle intrinsics.", type = Expert) //
+    @Option(help = "Force using legacy method handle intrinsics.", type = Expert, deprecated = true, deprecationMessage = "This option was introduced to simplify migration to GraalVM 23.1 and will be removed in a future release") //
     public static final HostedOptionKey<Boolean> UseOldMethodHandleIntrinsics = new HostedOptionKey<>(false);
 
     @Option(help = "Include all classes, methods, and fields from given modules", type = OptionType.Debug) //

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

@@ -37,8 +37,6 @@
 import java.util.function.Function;
 import java.util.stream.Collectors;
 
-import jdk.graal.compiler.debug.DebugContext;
-import jdk.graal.compiler.options.Option;
 import org.graalvm.nativeimage.ImageSingletons;
 import org.graalvm.nativeimage.hosted.Feature;
 
@@ -62,6 +60,9 @@
 import com.oracle.svm.util.ReflectionUtil;
 import com.oracle.svm.util.ReflectionUtil.ReflectionUtilError;
 
+import jdk.graal.compiler.debug.DebugContext;
+import jdk.graal.compiler.options.Option;
+
 /**
  * Handles the registration and iterations of {@link Feature features}.
  */
@@ -77,7 +78,8 @@ private static List<String> userEnabledFeatures() {
             return Options.Features.getValue().values();
         }
 
-        @Option(help = "Allow using deprecated @AutomaticFeature annotation. If set to false, an error is shown instead of a warning.")//
+        @Option(help = "Allow using deprecated @AutomaticFeature annotation. If set to false, an error is shown instead of a warning.", //
+                        deprecated = true, deprecationMessage = "This option was introduced to simplify migration to GraalVM 22.3 and will be removed in a future release")//
         public static final HostedOptionKey<Boolean> AllowDeprecatedAutomaticFeature = new HostedOptionKey<>(true);
     }
 

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

@@ -745,7 +745,8 @@ public InlineBeforeAnalysisGraphDecoder createInlineBeforeAnalysisGraphDecoder(B
     }
 
     public static class Options {
-        @Option(help = "Enable the behavior of old GraalVM versions. When enabled, interfaces not available for the current platform are filtered.")//
+        @Option(help = "Enable the behavior of old GraalVM versions. When enabled, interfaces not available for the current platform are filtered.", //
+                        deprecated = true, deprecationMessage = "This option was introduced to simplify migration to GraalVM 21.2 and will be removed in a future release")//
         public static final HostedOptionKey<Boolean> PlatformInterfaceCompatibilityMode = new HostedOptionKey<>(false);
     }
 

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

@@ -31,14 +31,14 @@
 
 import java.util.function.Function;
 
-import jdk.graal.compiler.options.Option;
-import jdk.graal.compiler.options.OptionType;
-
 import com.oracle.svm.core.option.APIOption;
 import com.oracle.svm.core.option.HostedOptionKey;
 import com.oracle.svm.core.option.LocatableMultiOptionValue;
 import com.oracle.svm.util.LogUtils;
 
+import jdk.graal.compiler.options.Option;
+import jdk.graal.compiler.options.OptionType;
+
 public final class ClassInitializationOptions {
 
     private static class InitializationValueTransformer implements Function<Object, Object> {
@@ -92,7 +92,8 @@ private static class InitializationValueEager extends InitializationValueTransfo
     @Option(help = "A comma-separated list of classes appended with their initialization strategy (':build_time', ':rerun', or ':run_time')", type = OptionType.User)//
     public static final HostedOptionKey<LocatableMultiOptionValue.Strings> ClassInitialization = new HostedOptionKey<>(LocatableMultiOptionValue.Strings.build());
 
-    @Option(help = "Instead of abort, only warn if --initialize-at-build-time= is used.", type = OptionType.Debug)//
+    @Option(help = "Instead of abort, only warn if --initialize-at-build-time= is used.", type = OptionType.Debug, //
+                    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> AllowDeprecatedInitializeAllClassesAtBuildTime = new HostedOptionKey<>(false);
 
     @Option(help = "Prints class initialization info for all classes detected by analysis.", type = OptionType.Debug)//
@@ -103,7 +104,7 @@ private static class InitializationValueEager extends InitializationValueTransfo
 
     @APIOption(name = "strict-image-heap", deprecated = "'--strict-image-heap' is now the default. You can remove the option.") //
     @Option(help = "Enable the strict image heap mode that allows all classes to be used at build-time but also requires types of all objects in the heap to be explicitly marked for build-time initialization.", //
-                    type = OptionType.User, deprecated = true, deprecationMessage = "The strict image heap mode is now the default. You can remove the option.") //
+                    type = OptionType.User, deprecated = true, deprecationMessage = "This option was introduced to simplify migration to GraalVM 24.0 and will be removed in a future release") //
     public static final HostedOptionKey<Boolean> StrictImageHeap = new HostedOptionKey<>(true, k -> {
         if (k.hasBeenSet() && Boolean.FALSE.equals(k.getValue())) {
             LogUtils.warning("The non-strict image heap mode should be avoided as it is deprecated and marked for removal.");