[GR-31495] Implement language and instrument specific source option support.

PullRequest: graal/19869

Author: chumer

sdk/CHANGELOG.md

@@ -9,6 +9,7 @@ This changelog summarizes major changes between GraalVM SDK versions. The main f
   * `PolyglotException#printStackTrace` now always starts with the string returned by `PolyglotException#toString()` like for regular Java Throwable objects.
 * GR-54673 Added the option `engine.MaximumCompilations` to protect against too many repeated compilations of the same call target. The default value is `100`.
 * GR-61448 Compilation id (`CompId`) was added to the `opt done` truffle compilation logs. This id matches the compilation id in the output of deoptimization, compilation and code cache logs on HotSpot and SubstrateVM.
+* GR-31495 Added the ability to specify language and instrument specific options using `Source.Builder.option(String, String)`. See the language and or tool specific documentation for available options. Available source options may also be reflected using `Instrument.getSourceOptions()` and `Language.getSourceOptions()`.
 
 ## Version 24.2.0
 * GR-54905 When using Truffle NFI with the Panama backend, native access must now be granted to the Truffle module instead of the NFI Panama module. Use the `--enable-native-access=org.graalvm.truffle` Java command line option to enable the native access for the NFI Panama backend.

sdk/src/org.graalvm.polyglot/snapshot.sigtest

@@ -352,6 +352,7 @@ meth public java.lang.String getName()
 meth public java.lang.String getVersion()
 meth public java.lang.String getWebsite()
 meth public org.graalvm.options.OptionDescriptors getOptions()
+meth public org.graalvm.options.OptionDescriptors getSourceOptions()
 supr java.lang.Object
 hfds dispatch,engine,receiver
 
@@ -367,6 +368,7 @@ meth public java.lang.String getVersion()
 meth public java.lang.String getWebsite()
 meth public java.util.Set<java.lang.String> getMimeTypes()
 meth public org.graalvm.options.OptionDescriptors getOptions()
+meth public org.graalvm.options.OptionDescriptors getSourceOptions()
 supr java.lang.Object
 hfds dispatch,engine,receiver
 
@@ -517,9 +519,11 @@ meth public org.graalvm.polyglot.Source$Builder interactive(boolean)
 meth public org.graalvm.polyglot.Source$Builder internal(boolean)
 meth public org.graalvm.polyglot.Source$Builder mimeType(java.lang.String)
 meth public org.graalvm.polyglot.Source$Builder name(java.lang.String)
+meth public org.graalvm.polyglot.Source$Builder option(java.lang.String,java.lang.String)
+meth public org.graalvm.polyglot.Source$Builder options(java.util.Map<java.lang.String,java.lang.String>)
 meth public org.graalvm.polyglot.Source$Builder uri(java.net.URI)
 supr java.lang.Object
-hfds cached,content,fileEncoding,interactive,internal,language,mimeType,name,origin,uri
+hfds cached,content,fileEncoding,interactive,internal,language,mimeType,name,options,origin,uri
 
 CLSS public final org.graalvm.polyglot.SourceSection
 meth public boolean equals(java.lang.Object)

sdk/src/org.graalvm.polyglot/src/org/graalvm/polyglot/Context.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2025, 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
@@ -406,7 +406,9 @@ public Engine getEngine() {
      * @throws IllegalStateException if the context is already closed and the current thread is not
      *             allowed to access it.
      * @throws IllegalArgumentException if the language of the given source is not installed or the
-     *             {@link Source#getMimeType() MIME type} is not supported with the language.
+     *             {@link Source#getMimeType() MIME type} is not supported with the language or the
+     *             validation of a {@link Source.Builder#option(String, String) source option}
+     *             failed.
      * @return the evaluation result. The returned instance is never <code>null</code>, but the
      *         result might represent a {@link Value#isNull() null} value.
      * @since 19.0
@@ -495,7 +497,10 @@ public Value eval(String languageId, CharSequence source) {
      *
      * @param source a source object to parse
      * @throws PolyglotException in case the guest language code parsing or validation failed.
-     * @throws IllegalArgumentException if the language does not exist or is not accessible.
+     * @throws IllegalArgumentException if the language of the given source is not installed or the
+     *             {@link Source#getMimeType() MIME type} is not supported with the language or the
+     *             validation of a {@link Source.Builder#option(String, String) source option}
+     *             failed.
      * @throws IllegalStateException if the context is already closed and the current thread is not
      *             allowed to access it, or if the given language is not installed.
      * @since 20.2

sdk/src/org.graalvm.polyglot/src/org/graalvm/polyglot/Engine.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2025, 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
@@ -2013,7 +2013,7 @@ public <S, T> Object newTargetTypeMapping(Class<S> sourceType, Class<T> targetTy
         @Override
         public Source buildSource(String language, Object origin, URI uri, String name, String mimeType, Object content, boolean interactive, boolean internal, boolean cached, Charset encoding,
                         URL url,
-                        String path)
+                        String path, Map<String, String> options)
                         throws IOException {
             throw noPolyglotImplementationFound();
         }

sdk/src/org.graalvm.polyglot/src/org/graalvm/polyglot/Instrument.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2025, 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
@@ -102,6 +102,17 @@ public OptionDescriptors getOptions() {
         return dispatch.getOptions(receiver);
     }
 
+    /**
+     * Returns the source options descriptors available for sources of this instrument.
+     *
+     * @see #getOptions()
+     * @see Source.Builder#option(String, String)
+     * @since 25.0
+     */
+    public OptionDescriptors getSourceOptions() {
+        return dispatch.getSourceOptions(receiver);
+    }
+
     /**
      * Gets the version of this instrument.
      *

sdk/src/org.graalvm.polyglot/src/org/graalvm/polyglot/Language.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2025, 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
@@ -134,6 +134,17 @@ public OptionDescriptors getOptions() {
         return dispatch.getOptions(receiver);
     }
 
+    /**
+     * Returns the source options descriptors available for sources of this language.
+     *
+     * @see #getOptions()
+     * @see Source.Builder#option(String, String)
+     * @since 25.0
+     */
+    public OptionDescriptors getSourceOptions() {
+        return dispatch.getSourceOptions(receiver);
+    }
+
     /**
      * Returns the default MIME type that is in use by a language. The default MIME type specifies
      * whether a source is loaded as character or binary based source by default. Returns

sdk/src/org.graalvm.polyglot/src/org/graalvm/polyglot/Source.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2025, 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
@@ -47,6 +47,8 @@
 import java.net.URI;
 import java.net.URL;
 import java.nio.charset.Charset;
+import java.util.HashMap;
+import java.util.Map;
 import java.util.Objects;
 
 import org.graalvm.polyglot.impl.AbstractPolyglotImpl;
@@ -533,7 +535,7 @@ public static Builder newBuilder(String language, CharSequence characters, Strin
      * <pre>
      *
      * </pre>
-     * 
+     *
      * @param language the language id, must not be <code>null</code>
      * @param bytes the byte sequence or string, must not be <code>null</code>
      * @param name the name of the source, if <code>null</code> then <code>"Unnamed"</code> will be
@@ -551,7 +553,7 @@ public static Builder newBuilder(String language, ByteSequence bytes, String nam
      * language, the {@link Builder#content(ByteSequence) contents} or the specified
      * {@link Builder#mimeType(String) MIME type}. A language may be detected from an existing file
      * using {@link #findLanguage(File)}.
-     * 
+     *
      * <pre>
      * File file = new File(dir, name);
      * assert name.endsWith(".java") : "Imagine proper file";
@@ -581,7 +583,7 @@ public static Builder newBuilder(String language, File file) {
      * using {@link #findLanguage(URL)}.
      * <p>
      * Example usage:
-     * 
+     *
      * <pre>
      * URL resource = relativeClass.getResource("sample.js");
      * Source source = Source.newBuilder("js", resource).build();
@@ -741,7 +743,7 @@ private static IllegalArgumentException invalidMimeType(String mimeType) {
      * Represents a builder to build {@link Source} objects.
      * <p>
      * To load a source from disk one can use:
-     * 
+     *
      * <pre>
      * File file = new File(dir, name);
      * assert name.endsWith(".java") : "Imagine proper file";
@@ -753,35 +755,35 @@ private static IllegalArgumentException invalidMimeType(String mimeType) {
      * assert file.getPath().equals(source.getPath());
      * assert file.toURI().equals(source.getURI());
      * </pre>
-     * 
+     *
      * To load source from a {@link URL} one can use:
-     * 
+     *
      * <pre>
      * URL resource = relativeClass.getResource("sample.js");
      * Source source = Source.newBuilder("js", resource).build();
      * assert resource.toExternalForm().equals(source.getPath());
      * assert "sample.js".equals(source.getName());
      * assert resource.toURI().equals(source.getURI());
      * </pre>
-     * 
+     *
      * To create a source representing characters:
-     * 
+     *
      * <pre>
      * Source source = Source.newBuilder("js", "function() {\n" + "  return 'Hi';\n" + "}\n", "hi.js").buildLiteral();
      * assert "hi.js".equals(source.getName());
      * </pre>
-     * 
+     *
      * or read a source from a {@link Reader}:
-     * 
+     *
      * <pre>
      * Reader stream = new InputStreamReader(
      *                 relativeClass.getResourceAsStream("sample.js"));
      * Source source = Source.newBuilder("js", stream, "sample.js").build();
      * assert "sample.js".equals(source.getName());
      * </pre>
-     * 
+     *
      * To create a source representing bytes:
-     * 
+     *
      * <pre>
      * byte[] bytes = new byte[]{ /* Binary &#42;/ };
      * Source source = Source.newBuilder("llvm",
@@ -806,6 +808,7 @@ public class Builder {
         private Object content;
         private String mimeType;
         private Charset fileEncoding;
+        private Map<String, String> options;
 
         Builder(String language, Object origin) {
             Objects.requireNonNull(language);
@@ -1016,6 +1019,52 @@ public Builder encoding(Charset encoding) {
             return this;
         }
 
+        /**
+         * Sets a source option key and value for the built source. Source options allow you to
+         * attach language- or instrument-specific configuration to a source. These options are
+         * parsed and validated only when {@link Context#eval(Source)} or
+         * {@link Context#parse(Source)} is invoked, rather than when the source is created.
+         * <p>
+         * If the source is validated, all source options will be validated. Therefore, each
+         * language or instrument associated with a source option must be installed.
+         * <p>
+         * Source options of any language or instrument can be supplied to all sources. Some source
+         * options may only have an effect when provided to sources of the language with the same
+         * id. The available source option keys can be found in the respective language or
+         * instrument documentation, or at runtime via {@link Language#getSourceOptions()} or
+         * {@link Instrument#getSourceOptions()}.
+         *
+         * @param key the option key (must not be null)
+         * @param value the option value (must not be null)
+         * @see Context#eval(Source)
+         * @see Context#parse(Source)
+         * @see Language#getSourceOptions()
+         * @see Instrument#getSourceOptions()
+         * @since 25.0
+         */
+        public Builder option(String key, String value) {
+            Objects.requireNonNull(key);
+            Objects.requireNonNull(value);
+            if (this.options == null) {
+                this.options = new HashMap<>();
+            }
+            this.options.put(key, value);
+            return this;
+        }
+
+        /**
+         * Shortcut for setting multiple {@link #option(String, String) options} using a map. All
+         * values of the provided map must be non-null.
+         *
+         * @since 25.0
+         */
+        public Builder options(@SuppressWarnings("hiding") Map<String, String> options) {
+            for (var entry : options.entrySet()) {
+                option(entry.getKey(), entry.getValue());
+            }
+            return this;
+        }
+
         /**
          * Uses configuration of this builder to create new {@link Source} object. The method throws
          * an {@link IOException} if an error loading the source occurred.
@@ -1024,7 +1073,7 @@ public Builder encoding(Charset encoding) {
          * @since 19.0
          */
         public Source build() throws IOException {
-            Source source = (Source) getImpl().buildSource(language, origin, uri, name, mimeType, content, interactive, internal, cached, fileEncoding, null, null);
+            Source source = (Source) getImpl().buildSource(language, origin, uri, name, mimeType, content, interactive, internal, cached, fileEncoding, null, null, options);
 
             // make sure origin is not consumed again if builder is used twice
             if (source.hasBytes()) {

sdk/src/org.graalvm.polyglot/src/org/graalvm/polyglot/impl/AbstractPolyglotImpl.java

@@ -559,9 +559,9 @@ public void resetPreInitializedEngine() {
     }
 
     public Object buildSource(String language, Object origin, URI uri, String name, String mimeType, Object content, boolean interactive, boolean internal, boolean cached, Charset encoding, URL url,
-                    String path)
+                    String path, Map<String, String> options)
                     throws IOException {
-        return getNext().buildSource(language, origin, uri, name, mimeType, content, interactive, internal, cached, encoding, url, path);
+        return getNext().buildSource(language, origin, uri, name, mimeType, content, interactive, internal, cached, encoding, url, path, options);
     }
 
     public String findLanguage(File file) throws IOException {
@@ -708,6 +708,8 @@ protected AbstractSourceDispatch(AbstractPolyglotImpl engineImpl) {
 
         public abstract String getLanguage(Object impl);
 
+        public abstract Map<String, String> getOptions(Object impl);
+
     }
 
     public abstract static class AbstractSourceSectionDispatch extends AbstractDispatchClass {
@@ -939,6 +941,8 @@ protected AbstractInstrumentDispatch(AbstractPolyglotImpl engineImpl) {
 
         public abstract OptionDescriptors getOptions(Object receiver);
 
+        public abstract OptionDescriptors getSourceOptions(Object receiver);
+
         public abstract String getVersion(Object receiver);
 
         public abstract <T> T lookup(Object receiver, Class<T> type);
@@ -971,6 +975,8 @@ protected AbstractLanguageDispatch(AbstractPolyglotImpl engineImpl) {
 
         public abstract OptionDescriptors getOptions(Object receiver);
 
+        public abstract OptionDescriptors getSourceOptions(Object receiver);
+
         public abstract Set<String> getMimeTypes(Object receiver);
 
         public abstract String getDefaultMimeType(Object receiver);

tools/src/com.oracle.truffle.tools.chromeinspector.test/src/com/oracle/truffle/tools/chromeinspector/test/SLInspectProfileTest.java

@@ -161,8 +161,11 @@ public void testDetailedCodeCoverage() throws Exception {
         tester.eval(source).get();
         tester.sendMessage("{\"id\":5,\"method\":\"Profiler.takePreciseCoverage\"}");
         assertEquals("{\"result\":{\"result\":[{\"scriptId\":\"1\",\"functions\":["
-                + "{\"ranges\":[{\"endOffset\":90,\"startOffset\":69,\"count\":1},{\"endOffset\":66,\"startOffset\":57,\"count\":1}],\"functionName\":\"main\",\"isBlockCoverage\":true},"
-                + "{\"ranges\":[{\"endOffset\":34,\"startOffset\":22,\"count\":2}],\"functionName\":\"add\",\"isBlockCoverage\":true}],"
+                + "{\"ranges\":[{\"endOffset\":34,\"startOffset\":22,\"count\":2}],\"functionName\":\"add\",\"isBlockCoverage\":true},"
+                + "{\"ranges\":["
+                + "{\"endOffset\":66,\"startOffset\":57,\"count\":1},"
+                + "{\"endOffset\":90,\"startOffset\":69,\"count\":1}],"
+                + "\"functionName\":\"main\",\"isBlockCoverage\":true}],"
                 + "\"url\":\"" + slTestURI + "\"}]},\"id\":5}", tester.getMessages(true).trim());
         tester.sendMessage("{\"id\":6,\"method\":\"Profiler.takePreciseCoverage\"}");
         assertEquals("{\"result\":{\"result\":[]},\"id\":6}", tester.getMessages(true).trim());

truffle/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 This changelog summarizes major changes between Truffle versions relevant to languages implementors building upon the Truffle framework. The main focus is on APIs exported by Truffle.
 
+## Version 25.0
+* GR-31495 Added ability to specify language and instrument specific options using `Source.Builder.option(String, String)`. Languages may describe available source options by implementing `TruffleLanguage.getSourceOptionDescriptors()` and `TruffleInstrument.getSourceOptionDescriptors()` respectively.
+ 
+
 ## Version 24.2.0
 * GR-60636 Truffle now stops compiling when the code cache fills up on HotSpot. A warning is printed when that happens.
 

truffle/src/com.oracle.truffle.api.debug/src/com/oracle/truffle/api/debug/Breakpoint.java

@@ -40,6 +40,7 @@
  */
 package com.oracle.truffle.api.debug;
 
+import java.io.IOException;
 import java.lang.ref.Reference;
 import java.lang.ref.WeakReference;
 import java.net.URI;
@@ -130,8 +131,8 @@
  * <p>
  * Example usage:
  *
- * {@snippet file="com/oracle/truffle/api/debug/Breakpoint.java"
- * region="BreakpointSnippets#example"}
+ * {@snippet file = "com/oracle/truffle/api/debug/Breakpoint.java" region =
+ * "BreakpointSnippets#example"}
  *
  * @since 0.9
  */
@@ -1671,7 +1672,12 @@ private void initializeConditional(MaterializedFrame frame) {
                 conditionSnippet = insert(snippet);
                 notifyInserted(snippet);
             } else {
-                CallTarget callTarget = Debugger.ACCESSOR.parse(conditionSource, instrumentedNode, new String[0]);
+                CallTarget callTarget;
+                try {
+                    callTarget = breakpoint.debugger.getEnv().parse(conditionSource);
+                } catch (IOException e) {
+                    throw new IllegalStateException("Error parsing condition.", e);
+                }
                 conditionCallNode = insert(Truffle.getRuntime().createDirectCallNode(callTarget));
             }
         }