From c767446e76cc15a6c745e2d17b8a6b71329a421f Mon Sep 17 00:00:00 2001 From: Vojin Jovanovic Date: Sat, 25 May 2024 23:19:35 +0200 Subject: [PATCH] Add the exact-reachability-metadata flag Deprecate old flags on the way --- .../com/oracle/svm/core/SubstrateOptions.java | 13 ++++++---- .../ExactReachabilityMetadataHelp.txt | 25 +++++++++++++++++++ .../ExactReachabilityMetadataPathHelp.txt | 10 ++++++++ .../doc-files/MissingRegistrationHelp.txt | 19 -------------- .../MissingRegistrationPathsHelp.txt | 11 -------- 5 files changed, 43 insertions(+), 35 deletions(-) create mode 100644 substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/doc-files/ExactReachabilityMetadataHelp.txt create mode 100644 substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/doc-files/ExactReachabilityMetadataPathHelp.txt delete mode 100644 substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/doc-files/MissingRegistrationHelp.txt delete mode 100644 substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/doc-files/MissingRegistrationPathsHelp.txt diff --git a/substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/SubstrateOptions.java b/substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/SubstrateOptions.java index 51e733c962dd6..d3d352be470a3 100644 --- a/substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/SubstrateOptions.java +++ b/substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/SubstrateOptions.java @@ -523,8 +523,9 @@ public static void updateMaxJavaStackTraceDepth(EconomicMap, Object @Option(help = "Trace VMOperation execution.")// public static final HostedOptionKey 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 TraceClassInitialization = new HostedOptionKey<>(LocatableMultiOptionValue.Strings.buildWithCommaDelimiter()); @APIOption(name = "trace-object-instantiation")// @@ -1097,7 +1098,7 @@ protected void onValueUpdate(EconomicMap, Object> values, String ol public static final HostedOptionKey VerifyFrameAnchors = 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 ConfigureReflectionMetadata = new HostedOptionKey<>(true); @@ -1133,10 +1134,12 @@ public Boolean getValueOrDefault(UnmodifiableEconomicMap, 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 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 ThrowMissingRegistrationErrors = new HostedOptionKey<>(LocatableMultiOptionValue.Strings.build()); - @Option(help = "file:doc-files/MissingRegistrationPathsHelp.txt")// + @APIOption(name = "exact-reachability-metadata-paths")// + @Option(help = "file:doc-files/ExactReachabilityMetadataPathHelp.txt")// public static final HostedOptionKey ThrowMissingRegistrationErrorsPaths = new HostedOptionKey<>(LocatableMultiOptionValue.Strings.build()); public enum ReportingMode { diff --git a/substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/doc-files/ExactReachabilityMetadataHelp.txt b/substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/doc-files/ExactReachabilityMetadataHelp.txt new file mode 100644 index 0000000000000..a39481d568274 --- /dev/null +++ b/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=' 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. diff --git a/substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/doc-files/ExactReachabilityMetadataPathHelp.txt b/substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/doc-files/ExactReachabilityMetadataPathHelp.txt new file mode 100644 index 0000000000000..94c9a19db9be2 --- /dev/null +++ b/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 + +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. diff --git a/substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/doc-files/MissingRegistrationHelp.txt b/substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/doc-files/MissingRegistrationHelp.txt deleted file mode 100644 index baad25ac45e25..0000000000000 --- a/substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/doc-files/MissingRegistrationHelp.txt +++ /dev/null @@ -1,19 +0,0 @@ -Throw Native Image-specific errors when trying to access an element that has not been registered. -This can happen on reflection and serialization queries, and resource access. -If used without args, the errors will be thrown when calling the corresponding query from any class in scope of the option. - -Using -H:ThrowMissingRegistrationErrors 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. - -Using -H:ThrowMissingRegistrationErrors 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 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 -H:ThrowMissingRegistrationErrors with arguments on command line does not have that restriction. diff --git a/substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/doc-files/MissingRegistrationPathsHelp.txt b/substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/doc-files/MissingRegistrationPathsHelp.txt deleted file mode 100644 index 9d7022b9f8859..0000000000000 --- a/substratevm/src/com.oracle.svm.core/src/com/oracle/svm/core/doc-files/MissingRegistrationPathsHelp.txt +++ /dev/null @@ -1,11 +0,0 @@ -Trigger missing registration errors from all types in the given class 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): - - -H:ThrowMissingRegistrationErrorsPaths - -The given entries are searched and all classes inside are registered as -H:ThrowMissingRegistrationErrorsPaths classes. - -This option is only allowed to be used on command line. I.e. the option will be rejected if it is provided -by Args of a native-image.properties file embedded in a zip/jar file.