[GR-63557] Inline multi-line help text for options.

PullRequest: graal/20413

Author: dougxc

compiler/src/jdk.graal.compiler.libgraal/src/jdk/graal/compiler/libgraal/LibGraalFeature.java

@@ -232,7 +232,7 @@ void afterAnalysis(AfterAnalysisAccess access) {
             Map<String, String> modules = libgraalLoader.getClassModuleMap();
             for (OptionKey<?> option : options) {
                 OptionDescriptor descriptor = option.getDescriptor();
-                if (descriptor != null) {
+                if (descriptor != null && descriptor.getContainer().optionsAreServiceLoadable()) {
                     GraalError.guarantee(access.isReachable(option.getClass()), "%s", option.getClass());
                     GraalError.guarantee(access.isReachable(descriptor.getClass()), "%s", descriptor.getClass());
 

compiler/src/jdk.graal.compiler.processor/src/jdk/graal/compiler/options/processor/OptionProcessor.java

@@ -24,10 +24,10 @@
  */
 package jdk.graal.compiler.options.processor;
 
-import java.io.BufferedReader;
 import java.io.IOException;
-import java.io.InputStreamReader;
+import java.io.InputStream;
 import java.io.PrintWriter;
+import java.nio.charset.StandardCharsets;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
@@ -185,72 +185,81 @@ private void processElement(Element element, OptionsDeclarer optionsDeclarer) {
             processingEnv.getMessager().printMessage(Kind.ERROR, "Option field cannot be declared in the unnamed package", element);
             return;
         }
-        List<String> helpValue = getAnnotationValueList(annotation, "help", String.class);
-        String help = "";
-        List<String> extraHelp = new ArrayList<>();
-
-        if (helpValue.size() == 1) {
-            help = helpValue.getFirst();
-            if (help.startsWith("file:")) {
-                String path = help.substring("file:".length());
-                Filer filer = processingEnv.getFiler();
+
+        String help = getAnnotationValue(annotation, "help", String.class);
+        List<String> helpLines;
+        if (help.startsWith("file:")) {
+            String path = help.substring("file:".length());
+            Filer filer = processingEnv.getFiler();
+            try {
+                FileObject file;
                 try {
-                    FileObject file;
-                    try {
-                        file = filer.getResource(StandardLocation.SOURCE_PATH, enclosingPackage.getQualifiedName(), path);
-                    } catch (IllegalArgumentException | IOException e) {
-                        // Handle the case when a compiler doesn't support the SOURCE_PATH location
-                        file = filer.getResource(StandardLocation.CLASS_OUTPUT, enclosingPackage.getQualifiedName(), path);
-                    }
-                    try (BufferedReader br = new BufferedReader(new InputStreamReader(file.openInputStream()))) {
-                        help = br.readLine();
-                        if (help == null) {
-                            help = "";
-                        }
-                        String line = br.readLine();
-                        while (line != null) {
-                            extraHelp.add(line);
-                            line = br.readLine();
-                        }
-                    }
-                } catch (IOException e) {
-                    String msg = String.format("Error reading %s containing the help text for option field: %s", path, e);
-                    processingEnv.getMessager().printMessage(Kind.ERROR, msg, element);
-                    return;
+                    file = filer.getResource(StandardLocation.SOURCE_PATH, enclosingPackage.getQualifiedName(), path);
+                } catch (IllegalArgumentException | IOException e) {
+                    // Handle the case when a compiler doesn't support the SOURCE_PATH location
+                    file = filer.getResource(StandardLocation.CLASS_OUTPUT, enclosingPackage.getQualifiedName(), path);
+                }
+                try (InputStream in = file.openInputStream()) {
+                    help = new String(in.readAllBytes(), StandardCharsets.UTF_8);
+                    helpLines = List.of(help.split(System.lineSeparator()));
                 }
+            } catch (IOException e) {
+                String msg = String.format("Error reading %s containing the help text for option field: %s", path, e);
+                processingEnv.getMessager().printMessage(Kind.ERROR, msg, element);
+                return;
             }
-        } else if (helpValue.size() > 1) {
-            help = helpValue.getFirst();
-            extraHelp = helpValue.subList(1, helpValue.size());
+        } else {
+            helpLines = List.of(help.split("\\n"));
         }
-        if (!help.isEmpty()) {
-            char firstChar = help.charAt(0);
+
+        String briefHelp = helpLines.getFirst();
+        List<String> extraHelp;
+        if (briefHelp.isEmpty()) {
+            if (helpLines.size() > 1) {
+                processingEnv.getMessager().printMessage(Kind.ERROR, "First line of multi-line help text cannot be empty", element);
+                return;
+            }
+            extraHelp = List.of();
+        } else {
+            if (helpLines.size() > 1) {
+                if (briefHelp.charAt(briefHelp.length() - 1) != '.' && !helpLines.get(1).isBlank()) {
+                    processingEnv.getMessager().printMessage(Kind.ERROR,
+                                    "First line of multi-line help text must end with a period or be followed by a blank line", element);
+                    return;
+                }
+            }
+            char firstChar = briefHelp.charAt(0);
             if (!Character.isUpperCase(firstChar)) {
                 processingEnv.getMessager().printMessage(Kind.ERROR, "Option help text must start with an upper case letter", element);
                 return;
             }
+            extraHelp = helpLines.subList(1, helpLines.size());
         }
 
         String stability = getAnnotationValue(annotation, "stability", VariableElement.class).getSimpleName().toString();
         if (stability.equals("STABLE")) {
-            if (help.isEmpty()) {
+            if (briefHelp.isEmpty()) {
                 processingEnv.getMessager().printMessage(Kind.ERROR, "A stable option must have non-empty help text", element);
                 return;
             }
         }
 
         String optionTypeName = getAnnotationValue(annotation, "type", VariableElement.class).getSimpleName().toString();
         if (!optionTypeName.equals("Debug")) {
-            if (help.isEmpty()) {
+            if (briefHelp.isEmpty()) {
                 processingEnv.getMessager().printMessage(Kind.ERROR, "Non debug options must always have a option help text " + optionName);
             }
         }
         boolean deprecated = getAnnotationValue(annotation, "deprecated", Boolean.class);
         String deprecationMessage = getAnnotationValue(annotation, "deprecationMessage", String.class);
-        OptionInfo info = new OptionInfo(optionName, optionTypeName, help, extraHelp, optionType, declaringClass, fieldName, stability, deprecated, deprecationMessage);
+        OptionInfo info = new OptionInfo(optionName, optionTypeName, briefHelp, extraHelp, optionType, declaringClass, fieldName, stability, deprecated, deprecationMessage);
         optionsDeclarer.options.add(info);
     }
 
+    private static String literal(String help) {
+        return "\"" + help.replace("\\", "\\\\").replace("\"", "\\\"") + "\"";
+    }
+
     static void createOptionsDescriptorsFile(ProcessingEnvironment processingEnv, OptionsDeclarer optionsDeclarer) {
         Element[] originatingElements = optionsDeclarer.originatingElements.toArray(new Element[0]);
         String optionsDescriptorsClassName = optionsDeclarer.getOptionDescriptorsClassName();
@@ -310,11 +319,11 @@ static void createOptionsDescriptorsFile(ProcessingEnvironment processingEnv, Op
                 out.printf("                /*name*/ \"%s\",\n", name);
                 out.printf("                /*optionType*/ %s.%s,\n", getSimpleName(OPTION_TYPE_CLASS_NAME), optionType);
                 out.printf("                /*optionValueType*/ %s.class,\n", type);
-                out.printf("                /*help*/ \"%s\",\n", help.replace("\\", "\\\\").replace("\"", "\\\""));
+                out.printf("                /*help*/ %s,\n", literal(help));
                 if (!extraHelp.isEmpty()) {
                     out.printf("                /*extraHelp*/ new String[] {\n");
                     for (String line : extraHelp) {
-                        out.printf("                         \"%s\",\n", line.replace("\\", "\\\\").replace("\"", "\\\""));
+                        out.printf("                         %s,\n", literal(line));
                     }
                     out.printf("                              },\n");
                 }

compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/core/GraalCompilerOptions.java

@@ -39,15 +39,30 @@ public class GraalCompilerOptions {
     // @formatter:off
     @Option(help = "Print an informational line to the console for each completed compilation.", type = OptionType.Debug, stability = OptionStability.STABLE)
     public static final OptionKey<Boolean> PrintCompilation = new OptionKey<>(false);
-    @Option(help = "Pattern for method(s) that will trigger an exception when compiled. " +
-                   "This option exists to test handling compilation crashes gracefully. " +
-                   "See the MethodFilter option for the pattern syntax. A ':Bailout' " +
-                   "suffix will raise a bailout exception and a ':PermanentBailout' " +
-                   "suffix will raise a permanent bailout exception.", type = OptionType.Debug)
+    @Option(help = """
+                   Pattern for method(s) that will trigger an exception when compiled.
+                   This option exists to test handling compilation crashes gracefully.
+                   See the MethodFilter option for the pattern syntax. A ':Bailout'
+                   suffix will raise a bailout exception and a ':PermanentBailout'
+                   suffix will raise a permanent bailout exception.""", type = OptionType.Debug)
     public static final OptionKey<String> CrashAt = new OptionKey<>(null);
     @Option(help = "Treats compilation bailouts as compilation failures.", type = OptionType.User, stability = OptionStability.STABLE)
     public static final OptionKey<Boolean> CompilationBailoutAsFailure = new OptionKey<>(false);
-    @Option(help = "file:doc-files/CompilationFailureActionHelp.txt", type = OptionType.User, stability = OptionStability.STABLE)
+    @Option(help = """
+                   Specifies the action to take when compilation fails.
+
+                   The accepted values are:
+                       Silent  - Prints nothing to the console.
+                        Print  - Prints the stack trace to the console.
+                     Diagnose* - Retries the compilation with extra diagnostics.
+                       ExitVM  - Same as Diagnose except that the VM process exits after retrying.
+
+                   * If the value is "Diagnose", compilation is retried with extra diagnostics enabled including dumping.
+                     Options specific to retry compilations can be modified using the DiagnoseOptions meta-option.
+                     For example, to enable full debug dumping and logging during all retry compilations, use "-Djdk.graal.DiagnoseOptions=Dump=:5 Log=:5".
+                     If the option value starts with a non-word character, that character is used as the separator between options instead of a space.
+                     For example: "-Djdk.graal.DiagnoseOptions=@Log=Inlining@LogFile=/path/with space".""",
+            type = OptionType.User, stability = OptionStability.STABLE)
     public static final EnumOptionKey<ExceptionAction> CompilationFailureAction = new EnumOptionKey<>(ExceptionAction.Silent);
     @Option(help = "Specifies the maximum number of compilation failures to handle with the action specified by " +
                    "CompilationFailureAction before changing to a less verbose action. " +

compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/core/common/GraalOptions.java

@@ -291,7 +291,15 @@ public final class GraalOptions {
     @Option(help = "Use a cache for snippet graphs.", type = OptionType.Debug)
     public static final OptionKey<Boolean> UseSnippetGraphCache = new OptionKey<>(true);
 
-    @Option(help = "file:doc-files/TraceInliningHelp.txt", type = OptionType.Debug, stability = OptionStability.STABLE)
+    @Option(help = """
+    Enable tracing of inlining decisions.
+    Output format:
+      compilation of 'Signature of the compilation root method':
+        at 'Signature of the root method' ['Bytecode index']: <'Phase'> 'Child method signature': 'Decision made about this callsite'
+          at 'Signature of the child method' ['Bytecode index']:
+             |--<'Phase 1'> 'Grandchild method signature': 'First decision made about this callsite'
+             \\--<'Phase 2'> 'Grandchild method signature': 'Second decision made about this callsite'
+          at 'Signature of the child method' ['Bytecode index']: <'Phase'> 'Another grandchild method signature': 'The only decision made about this callsite.'""", type = OptionType.Debug, stability = OptionStability.STABLE)
     public static final OptionKey<Boolean> TraceInlining = new OptionKey<>(false);
 
     @Option(help = "Enable inlining decision tracing in stubs and snippets.", type = OptionType.Debug)

compiler/src/jdk.graal.compiler/src/jdk/graal/compiler/core/common/SpectrePHTMitigations.java

@@ -64,7 +64,20 @@ protected void onValueUpdate(EconomicMap<OptionKey<?>, Object> values, Boolean o
             }
         };
 
-        @Option(help = "file:doc-files/MitigateSpeculativeExecutionAttacksHelp.txt", type = OptionType.Expert)
+        @Option(help = """
+                       Selects a strategy to mitigate speculative bounds check bypass (also known as Spectre-PHT or Spectre V1).
+                       The accepted values are:
+                                         None - No mitigations are used in JIT compiled code.
+                                   AllTargets - Speculative execution on all branch targets is
+                                                stopped using speculative execution barrier instructions.
+                                                This option is equivalent to setting SpeculativeExecutionBarriers to true.
+                                 GuardTargets - Branch targets relevant to Java memory safety are instrumented with barrier instructions.
+                                                This option has a lower performance impact than AllTargets.
+                         NonDeoptGuardTargets - Same as GuardTargets, except that branches which deoptimize are not protected because they cannot be
+                                                executed repeatedly and are thus less likely to be successfully exploited in an attack.
+
+
+                       Note that all modes except "None" also instrument branch target blocks containing UNSAFE memory accesses with barrier instructions.""", type = OptionType.Expert)
         public static final EnumOptionKey<SpectrePHTMitigations> SpectrePHTBarriers = new EnumOptionKey<>(None) {
             private boolean isSpeculativeExecutionBarriersEnabled(UnmodifiableEconomicMap<OptionKey<?>, Object> values) {
                 Object value = values.get(SpeculativeExecutionBarriers);