[GR-33644] [GR-33641] Support newlines in Truffle's OptionProcessor.

PullRequest: graal/9736

Author: fniephaus

compiler/src/org.graalvm.compiler.truffle.options/src/org/graalvm/compiler/truffle/options/PolyglotCompilerOptions.java

@@ -178,7 +178,7 @@ public ExceptionAction apply(String s) {
             try {
                 return ExceptionAction.valueOf(s);
             } catch (IllegalArgumentException e) {
-                throw new IllegalArgumentException(ExceptionAction.HELP);
+                throw new IllegalArgumentException(String.format(ExceptionAction.HELP));
             }
         }
     });
@@ -365,10 +365,10 @@ private String indent(int nameLength) {
     private static final String EXPANSION_VALUES = "Accepted values are:%n" +
                     "    true - Collect data for the default tier 'truffleTier'.%n" +
                     "    false - No data will be collected.%n" +
-                    "Or one or multiple tiers separated by comma (e.g. truffleTier,lowTier) :%n" +
+                    "Or one or multiple tiers separated by comma (e.g. truffleTier,lowTier):%n" +
                     "    peTier - After partial evaluation without additional phases applied.%n" +
                     "    truffleTier - After partial evaluation with additional phases applied.%n" +
-                    "    lowTier - After low tier phases were applied.%n";
+                    "    lowTier - After low tier phases were applied.";
 
     @Option(help = "Print a tree of all expanded Java methods with statistics after each compilation. " + EXPANSION_VALUES, category = OptionCategory.INTERNAL)
     public static final OptionKey<Set<CompilationTier>> TraceMethodExpansion = new OptionKey<>(Collections.emptySet(), COMPILATION_TIERS_TYPE);
@@ -498,7 +498,7 @@ private String indent(int nameLength) {
             "On runtimes which doesn't support it the option has no effect.",
             category = OptionCategory.EXPERT)
     public static final OptionKey<Integer> EncodedGraphCachePurgeDelay = new OptionKey<>(10_000);
-    
+
     @Option(help = "Forces the frame clearing mechanism to be executed, even if Frame.clear() is not used.",
             category = OptionCategory.EXPERT)
     public static final OptionKey<Boolean> ForceFrameLivenessAnalysis = new OptionKey<>(false);

docs/getting-started/graalvm-community/get-started-graalvm-community.md

@@ -14,7 +14,7 @@ GraalVM's polyglot capabilities make it possible to mix multiple programming lan
 Here you will find information about installing GraalVM Community Edition, running basic applications with it, and adding support for accompanying features.
 Further, you will learn about the polyglot capabilities of GraalVM and see how to build platform-specific native executables of JVM-based applications.
 
-If you are new to GraaVM, we recommend starting with [Introduction to GraalVM](/docs/introduction/), where you will find information about GraalVM's architecture, distributions available, supported platforms, core and additional features, and much more.
+If you are new to GraalVM, we recommend starting with [Introduction to GraalVM](/docs/introduction/), where you will find information about GraalVM's architecture, distributions available, supported platforms, core and additional features, and much more.
 
 If you have GraalVM already installed and have experience using it, you can skip this getting started guide and proceed to the in-depth [Reference Manuals](/reference-manual/).
 

sdk/mx.sdk/mx_sdk_vm_impl.py

@@ -2149,8 +2149,9 @@ def _gen_gu_manifest(components, formatter, bundled=False):
     dependencies = sorted(dependencies)
     if dependencies:
         manifest["Require-Bundle"] = ','.join(("org.graalvm." + d for d in dependencies))
-    if isinstance(main_component, mx_sdk.GraalVmLanguage):
-        _wd_base = join('jre', 'languages') if _src_jdk_version < 9 else 'languages'
+    if isinstance(main_component, (mx_sdk.GraalVmLanguage, mx_sdk.GraalVmTool)):
+        _component_type_base = 'languages' if isinstance(main_component, mx_sdk.GraalVmLanguage) else 'tools'
+        _wd_base = join('jre', _component_type_base) if _src_jdk_version < 9 else _component_type_base
         manifest["x-GraalVM-Working-Directories"] = join(_wd_base, main_component.dir_name)
 
     post_install_msg = None

sdk/src/org.graalvm.launcher/src/org/graalvm/launcher/Launcher.java

@@ -973,9 +973,12 @@ private static String wrap(String s) {
 
     private void printOption(String option, String description, int indentStart, int optionWidth) {
         String indent = spaces(indentStart);
-        String desc = wrap(description != null ? description : "");
+        String desc = description != null ? description : "";
         String nl = System.lineSeparator();
         String[] descLines = desc.split(nl);
+        for (int i = 0; i < descLines.length; i++) {
+            descLines[i] = wrap(descLines[i]);
+        }
         if (option.length() >= optionWidth && description != null) {
             out.println(indent + option + nl + indent + spaces(optionWidth) + descLines[0]);
         } else {

sdk/src/org.graalvm.options/src/org/graalvm/options/OptionDescriptor.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2021, 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
@@ -96,7 +96,7 @@ public boolean isDeprecated() {
     }
 
     /**
-     * Returns the deprecation reason and the recommended fix.
+     * Returns the deprecation reason and the recommended fix. For newlines, use <code>%n</code>.
      *
      * @since 20.1.0
      */
@@ -133,7 +133,8 @@ public OptionStability getStability() {
     }
 
     /**
-     * Returns a human-readable description on how to use the option.
+     * Returns a human-readable description on how to use the option. For newlines, use
+     * <code>%n</code>.
      *
      * @since 19.0
      */

substratevm/src/com.oracle.svm.hosted/src/com/oracle/svm/hosted/substitute/AnnotationSubstitutionProcessor.java

@@ -819,11 +819,13 @@ private static boolean isIncluded(TargetElement targetElementAnnotation, Class<?
 
     private static <T> void register(Map<T, T> substitutions, T annotated, T original, T target) {
         if (annotated != null) {
-            guarantee(!substitutions.containsKey(annotated) || substitutions.get(annotated) == original || substitutions.get(annotated) == target, "Already registered: %s", annotated);
+            guarantee(!substitutions.containsKey(annotated) || substitutions.get(annotated) == original || substitutions.get(annotated) == target,
+                            "Substition: %s conflicts with previously registered: %s", annotated, substitutions.get(annotated));
             substitutions.put(annotated, target);
         }
         if (original != null) {
-            guarantee(!substitutions.containsKey(original) || substitutions.get(original) == original || substitutions.get(original) == target, "Already registered: %s", original);
+            guarantee(!substitutions.containsKey(original) || substitutions.get(original) == original || substitutions.get(original) == target,
+                            "Substition: %s conflicts with previously registered: %s", original, substitutions.get(original));
             substitutions.put(original, target);
         }
     }

truffle/src/com.oracle.truffle.api.instrumentation/src/com/oracle/truffle/api/instrumentation/TruffleInstrument.java

@@ -232,7 +232,7 @@ protected OptionDescriptors getOptionDescriptors() {
      * }
      *
      * @Registration(...)
-     * class MyInstrument extends TruffleInstruement {
+     * class MyInstrument extends TruffleInstrument {
      *
      *   static final OptionDescriptors CONTEXT_OPTIONS = new MyContextOptionDescriptors();
      *

truffle/src/com.oracle.truffle.api.interop/src/com/oracle/truffle/api/interop/InteropLibrary.java

@@ -105,9 +105,9 @@
  * The interop protocol only allows <i>interop values</i> to be used as receivers, return values or
  * parameters of messages. Allowed Java types of interop values are:
  * <ul>
- * <li>{@link TruffleObject}: Any subclass of {@link TruffleObject} is interpreted depending on the
- * interop messages it {@link ExportLibrary exports}. Truffle objects are expected but not required
- * to export interop library messages.
+ * <li>{@link TruffleObject}: Any object that implements the {@link TruffleObject} interface is
+ * interpreted according to the interop messages it {@link ExportLibrary exports}. Truffle objects
+ * are expected but not required to export interop library messages.
  * <li>{@link String} and {@link Character} are interpreted as {@link #isString(Object) string}
  * value.
  * <li>{@link Boolean} is interpreted as {@link #isBoolean(Object) boolean} value.

truffle/src/com.oracle.truffle.api.library/src/com/oracle/truffle/api/library/ExportLibrary.java

@@ -295,7 +295,7 @@
      *
      * <pre>
      * &#64;ExportLibrary(value = ArrayLibrary.class, delegateTo = "delegate")
-     * &#64;ExportLibrary(ReflectionLibrary.class, delegateTo = "delegate")
+     * &#64;ExportLibrary(value = ReflectionLibrary.class, delegateTo = "delegate")
      * final class ArrayFullWrapper {
      *
      *     final Object delegate;

truffle/src/com.oracle.truffle.api.test/src/com/oracle/truffle/api/test/option/OptionProcessorTest.java

@@ -86,6 +86,7 @@ public void testTestLang() {
         descriptor1 = descriptor = descriptors.get("optiontestlang1.StringOption1");
         assertNotNull(descriptor);
         assertTrue(descriptor.isDeprecated());
+        assertEquals(String.format("Deprecation message%nwith newline"), descriptor.getDeprecationMessage());
         assertFalse(descriptor.isOptionMap());
         assertSame(OptionCategory.USER, descriptor.getCategory());
         assertSame(OptionStability.EXPERIMENTAL, descriptor.getStability());
@@ -94,7 +95,7 @@ public void testTestLang() {
 
         descriptor2 = descriptor = descriptors.get("optiontestlang1.StringOption2");
         assertNotNull(descriptor);
-        assertEquals("StringOption2 help", descriptor.getHelp());
+        assertEquals(String.format("StringOption2 help%nwith newline"), descriptor.getHelp());
         assertFalse(descriptor.isDeprecated());
         assertFalse(descriptor.isOptionMap());
         assertSame(OptionCategory.EXPERT, descriptor.getCategory());
@@ -166,14 +167,15 @@ public void testOptionsInstrument() {
         descriptor1 = descriptor = descriptors.get("optiontestinstr1.StringOption1");
         assertNotNull(descriptor);
         assertTrue(descriptor.isDeprecated());
+        assertEquals(String.format("Deprecation message%nwith newline"), descriptor.getDeprecationMessage());
         assertFalse(descriptor.isOptionMap());
         assertSame(OptionCategory.USER, descriptor.getCategory());
         assertEquals("StringOption1 help", descriptor.getHelp());
         assertSame(OptionTestInstrument1.StringOption1, descriptor.getKey());
 
         descriptor2 = descriptor = descriptors.get("optiontestinstr1.StringOption2");
         assertNotNull(descriptor);
-        assertEquals("StringOption2 help", descriptor.getHelp());
+        assertEquals(String.format("StringOption2 help%nwith newline"), descriptor.getHelp());
         assertFalse(descriptor.isDeprecated());
         assertFalse(descriptor.isOptionMap());
         assertSame(OptionCategory.EXPERT, descriptor.getCategory());
@@ -357,10 +359,10 @@ public enum EnumValue {
     @Registration(id = "optiontestlang1", version = "1.0", name = "optiontestlang1")
     public static class OptionTestLang1 extends TruffleLanguage<Env> {
 
-        @Option(help = "StringOption1 help", deprecated = true, category = OptionCategory.USER) //
+        @Option(help = "StringOption1 help", deprecated = true, deprecationMessage = "Deprecation message%nwith newline", category = OptionCategory.USER) //
         static final OptionKey<String> StringOption1 = new OptionKey<>("defaultValue");
 
-        @Option(help = "StringOption2 help", deprecated = false, category = OptionCategory.EXPERT, stability = OptionStability.EXPERIMENTAL) //
+        @Option(help = "StringOption2 help%nwith newline", deprecated = false, category = OptionCategory.EXPERT, stability = OptionStability.EXPERIMENTAL) //
         public static final OptionKey<String> StringOption2 = new OptionKey<>("defaultValue");
 
         // The variable name differs from the option name on purpose, to test they can be different
@@ -397,10 +399,10 @@ public static Env getCurrentContext() {
     @TruffleInstrument.Registration(id = "optiontestinstr1", services = OptionValues.class)
     public static class OptionTestInstrument1 extends TruffleInstrument {
 
-        @Option(help = "StringOption1 help", deprecated = true, category = OptionCategory.USER, stability = OptionStability.STABLE) //
+        @Option(help = "StringOption1 help", deprecated = true, deprecationMessage = "Deprecation message%nwith newline", category = OptionCategory.USER, stability = OptionStability.STABLE) //
         public static final OptionKey<String> StringOption1 = new OptionKey<>("defaultValue");
 
-        @Option(help = "StringOption2 help", deprecated = false, category = OptionCategory.EXPERT) //
+        @Option(help = "StringOption2 help%nwith newline", deprecated = false, category = OptionCategory.EXPERT) //
         public static final OptionKey<String> StringOption2 = new OptionKey<>("defaultValue");
 
         @Option(help = "Instrument user-defined thresholds", deprecated = false, category = OptionCategory.EXPERT) //