[GR-44733] Public flag for missing registration errors.

PullRequest: graal/17804

Author: vjovanov

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

@@ -523,8 +523,9 @@ public static void updateMaxJavaStackTraceDepth(EconomicMap<OptionKey<?>, Object
     @Option(help = "Trace VMOperation execution.")//
     public static final HostedOptionKey<Boolean> TraceVMOperations = new HostedOptionKey<>(false);
 
-    @APIOption(name = "trace-class-initialization")//
-    @Option(help = "Comma-separated list of fully-qualified class names that class initialization is traced for.")//
+    private static final String DEPRECATION_MESSAGE_TCI = "This option is not required anymore with the strict image heap enabled by default.";
+    @APIOption(name = "trace-class-initialization", deprecated = DEPRECATION_MESSAGE_TCI)//
+    @Option(help = "Comma-separated list of fully-qualified class names that class initialization is traced for.", deprecated = true, deprecationMessage = DEPRECATION_MESSAGE_TCI)//
     public static final HostedOptionKey<LocatableMultiOptionValue.Strings> TraceClassInitialization = new HostedOptionKey<>(LocatableMultiOptionValue.Strings.buildWithCommaDelimiter());
 
     @APIOption(name = "trace-object-instantiation")//
@@ -1100,7 +1101,7 @@ protected void onValueUpdate(EconomicMap<OptionKey<?>, Object> values, String ol
     public static final HostedOptionKey<Boolean> VerifyFrameAccess = new HostedOptionKey<>(false);
 
     @SuppressWarnings("unused")//
-    @APIOption(name = "configure-reflection-metadata")//
+    @APIOption(name = "configure-reflection-metadata", deprecated = "This option has no function anymore.")//
     @Option(help = "Enable runtime instantiation of reflection objects for non-invoked methods.", type = OptionType.Expert, deprecated = true)//
     public static final HostedOptionKey<Boolean> ConfigureReflectionMetadata = new HostedOptionKey<>(true);
 
@@ -1136,10 +1137,12 @@ 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 = "file:doc-files/MissingRegistrationHelp.txt")//
+    @APIOption(name = "exact-reachability-metadata", defaultValue = "")//
+    @Option(help = "file:doc-files/ExactReachabilityMetadataHelp.txt")//
     public static final HostedOptionKey<LocatableMultiOptionValue.Strings> ThrowMissingRegistrationErrors = new HostedOptionKey<>(LocatableMultiOptionValue.Strings.build());
 
-    @Option(help = "file:doc-files/MissingRegistrationPathsHelp.txt")//
+    @APIOption(name = "exact-reachability-metadata-path")//
+    @Option(help = "file:doc-files/ExactReachabilityMetadataPathHelp.txt")//
     public static final HostedOptionKey<LocatableMultiOptionValue.Strings> ThrowMissingRegistrationErrorsPaths = new HostedOptionKey<>(LocatableMultiOptionValue.Strings.build());
 
     public enum ReportingMode {

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/doc-files/ExactReachabilityMetadataHelp.txt

@@ -0,0 +1,25 @@
+Enables exact and user-friendly handling of reflection, resources, JNI, and serialization.
+When reachability metadata for an element is specified, the native executable will have expected and predictable behavior.
+When reachability metadata for an element is not specified, the binary will fail fast with a subtype of `java.lang.Error`
+ that explains exactly which element was missing. The errors can happen on reflection, resource, JNI, and serialization accesses.
+
+Note: '--exact-reachability-metadata' will become the default in future versions of Native Image. It is recommended to adopt the mode early
+ to avoid breakage during migration to newer GraalVM versions.
+
+If errors occur in third-party code, exact reachability metadata can be applied only to a single package with
+ '--exact-reachability-metadata=pkg'. To apply to whole jars, modules, and class-path entries please use
+ '--exact-reachability-metadata-path'. Using '--exact-reachability-metadata=<pkg>' with arguments is allowed in every scope:
+
+  1. On command line
+  2. Embedded in a 'native-image.properties' file of some zip/jar file on module-path
+  3. Embedded in a 'native-image.properties' file of some zip/jar file on class-path
+
+If used without arguments (only '--exact-reachability-metadata'), the errors will be thrown when calling the corresponding query from any
+ class in scope of the option. Using '--exact-reachability-metadata' without arguments is only allowed on command line or when
+ embedded in a 'native-image.properties' file of some zip/jar file on the module-path (but not on class-path).
+ In the module path case, the option will cause all classes of the module to trigger missing registration errors.
+ If used without arguments on command line all classes will trigger missing registration errors.
+
+If the option is embedded in 'native-image.properties' file in some zip/jar file all class-names
+and package-names passed to the option have to be found in the zip/jar files the option is embedded
+in. Using '--exact-reachability-metadata' with arguments on command line does not have that restriction.

substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/doc-files/ExactReachabilityMetadataPathHelp.txt

@@ -0,0 +1,10 @@
+Trigger exact handling of reflection, resources, JNI, and serialization from all types in the given class-path or module-path entries.
+
+This option requires arguments that are of the same type as the arguments passed via -p (--module-path) or -cp (--class-path):
+
+  --exact-reachability-metadata-path <class-search path of directories and jar files>
+
+The given entries are searched and all classes inside are registered as '--exact-reachability-metadata' classes.
+
+This option is only allowed to be used on command line. The option will be rejected if it is provided
+by 'Args' in a 'native-image.properties' file that is embedded in a jar file.