Update website

graalvm · Dec 6, 2024 · 31ef969 · 31ef969
1 parent 08e2975
commit 31ef969
Show file tree

Hide file tree

Showing 29 changed files with 96 additions and 74 deletions.
diff --git a/dev/getting-started/oci/cloud-shell/index.html b/dev/getting-started/oci/cloud-shell/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:25:09+00:00">
+        <meta name="dcterms.created" content="2024-12-06T09:02:15+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/dev/getting-started/oci/code-editor/index.html b/dev/getting-started/oci/code-editor/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:25:09+00:00">
+        <meta name="dcterms.created" content="2024-12-06T09:02:15+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/dev/getting-started/oci/compute-instance/index.html b/dev/getting-started/oci/compute-instance/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:25:09+00:00">
+        <meta name="dcterms.created" content="2024-12-06T09:02:15+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/dev/getting-started/oci/devops-build-pipeline/index.html b/dev/getting-started/oci/devops-build-pipeline/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:25:09+00:00">
+        <meta name="dcterms.created" content="2024-12-06T09:02:15+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/dev/getting-started/oci/index.html b/dev/getting-started/oci/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:25:09+00:00">
+        <meta name="dcterms.created" content="2024-12-06T09:02:15+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/dev/reference-manual/embed-languages/index.html b/dev/reference-manual/embed-languages/index.html
@@ -2350,13 +2350,17 @@ <h2 id="build-native-executables-from-polyglot-applications">
 <pre><code>mvn -Pnative package
 </code></pre>
 
-<p>To build a native executable from a polyglot application, for example, a Java-host application embedding Python, a <code>./resources</code> directory containing all the required files is created by default.
-By default, the language runtime will look for the resources directory relative to the native executable or library image that was built.
+<p>Building a native executable from a polyglot application, for example, a Java-host application embedding Python, automatically captures all the internal resources required by the included languages and tools.
+By default, the resources are included in the native executable itself.
+The inclusion of resources in the native executable can be disabled by <code>-H:-IncludeLanguageResources</code>.
+Another option is a separate <em>resources</em> directory containing all the required files.
+To switch to this option, use <code>-H:+CopyLanguageResources</code>. This is the default behavior when <code>-H:+IncludeLanguageResources</code> is not supported, i.e., with Graal Languages earlier than 24.2.x (see the <a href="https://www.graalvm.org/release-calendar/">versions roadmap</a>).
+When <code>-H:+CopyLanguageResources</code> is used, the language runtime will look for the resources directory relative to the native executable or the shared library.
 At run time, the lookup location may be customized using the <code>-Dpolyglot.engine.resourcePath=path/to/resources</code> option.
-To disable the resource creation, the <code>-H:-CopyLanguageResources</code> build-time option may be used.
-Note that some languages may not support running without a resources directory.</p>
+To disable the capturing of resources altogether, add both <code>-H:-IncludeLanguageResources</code> and <code>-H:-CopyLanguageResources</code> to build-time options.
+Note that some languages may not support running without their resources.</p>
 
-<p>With Polyglot version 23.1 the language home options like <code>-Dorg.graalvm.home</code> should no longer be used and were replaced with the resource directory option.
+<p>With Graal Languages version 23.1 and newer the language home options like <code>-Dorg.graalvm.home</code> should no longer be used and were replaced with the resource directory option.
 The language home options remain functional for compatibility reasons but may be removed in future releases.</p>
 
       <h3 id="configuring-native-host-reflection">

diff --git a/dev/reference-manual/native-image/native-code-interoperability/foreign-interface/index.html b/dev/reference-manual/native-image/native-code-interoperability/foreign-interface/index.html
@@ -620,7 +620,7 @@ <h3 id="looking-up-native-functions">
       </h3>
 
 <p>The FFM API provides the <code>SymbolLookup</code> interface to find functions in native libraries by name.
-<code>SymbolLookup.loaderLookup()</code> is currently the only supported kind of <code>SymbolLookup</code>.</p>
+Native image supports all available symbol lookup methods, i.e., <code>SymbolLookup.loaderLookup()</code>, <code>SymbolLookup.libraryLookup()</code>, and <code>Linker.defaultLookup()</code>.</p>
 
       <h3 id="registering-foreign-calls">
 
@@ -631,9 +631,13 @@ <h3 id="registering-foreign-calls">
       </h3>
 
 <p>In order to perform calls to native code at run time, supporting code must be generated at image build time.
-Therefore, the <code>native-image</code> tool must be provided with descriptors that characterize the functions to which downcalls may be performed at run time.</p>
+Therefore, the <code>native-image</code> tool must be provided with descriptors that characterize the functions with which downcalls or upcalls can be performed at runtime.</p>
 
-<p>These descriptors can be registered using a custom <code>Feature</code>, for example:</p>
+<p>For upcalls, it is recommended to register a specific static method as an upcall target by providing its declaring class and the method name.
+This allows <code>native-image</code> to create specialized upcall code that can be orders of magnitude faster than a upcall registered only by function descriptor.
+Whenever possible, this should be the preferred way to register upcalls.</p>
+
+<p>Descriptors and target methods can be registered using a custom <code>Feature</code>, for example:</p>
 <pre><code class="language-java">import static java.lang.foreign.ValueLayout.*;
 
 class ForeignRegistrationFeature implements Feature { 
@@ -645,6 +649,9 @@ <h3 id="registering-foreign-calls">
     RuntimeForeignAccess.registerForUpcall(FunctionDescriptor.of(JAVA_INT, JAVA_INT, JAVA_INT));
     RuntimeForeignAccess.registerForDowncall(FunctionDescriptor.of(ADDRESS, JAVA_INT, JAVA_INT), Linker.Option.firstVariadicArg(1));
     RuntimeForeignAccess.registerForDowncall(FunctionDescriptor.ofVoid(JAVA_INT), Linker.Option.captureCallState("errno"));
+
+    MethodHandle target = MethodHandles.lookup().findStatic(UserClass.class, "aStaticMethod", MethodType.of(int.class, int.class, int.class));
+    RuntimeForeignAccess.registerForUpcall(target, FunctionDescriptor.of(JAVA_INT, JAVA_INT, JAVA_INT));
   }
 }
 </code></pre>

diff --git a/jdk23/getting-started/oci/cloud-shell/index.html b/jdk23/getting-started/oci/cloud-shell/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:20:48+00:00">
+        <meta name="dcterms.created" content="2024-12-06T08:58:19+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/jdk23/getting-started/oci/code-editor/index.html b/jdk23/getting-started/oci/code-editor/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:20:48+00:00">
+        <meta name="dcterms.created" content="2024-12-06T08:58:19+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/jdk23/getting-started/oci/compute-instance/index.html b/jdk23/getting-started/oci/compute-instance/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:20:48+00:00">
+        <meta name="dcterms.created" content="2024-12-06T08:58:19+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/jdk23/getting-started/oci/devops-build-pipeline/index.html b/jdk23/getting-started/oci/devops-build-pipeline/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:20:48+00:00">
+        <meta name="dcterms.created" content="2024-12-06T08:58:19+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/jdk23/getting-started/oci/index.html b/jdk23/getting-started/oci/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:20:48+00:00">
+        <meta name="dcterms.created" content="2024-12-06T08:58:19+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/jdk24/getting-started/oci/cloud-shell/index.html b/jdk24/getting-started/oci/cloud-shell/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:24:23+00:00">
+        <meta name="dcterms.created" content="2024-12-06T09:01:31+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/jdk24/getting-started/oci/code-editor/index.html b/jdk24/getting-started/oci/code-editor/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:24:23+00:00">
+        <meta name="dcterms.created" content="2024-12-06T09:01:31+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/jdk24/getting-started/oci/compute-instance/index.html b/jdk24/getting-started/oci/compute-instance/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:24:23+00:00">
+        <meta name="dcterms.created" content="2024-12-06T09:01:31+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/jdk24/getting-started/oci/devops-build-pipeline/index.html b/jdk24/getting-started/oci/devops-build-pipeline/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:24:23+00:00">
+        <meta name="dcterms.created" content="2024-12-06T09:01:31+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/jdk24/getting-started/oci/index.html b/jdk24/getting-started/oci/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:24:23+00:00">
+        <meta name="dcterms.created" content="2024-12-06T09:01:31+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/jdk24/reference-manual/embed-languages/index.html b/jdk24/reference-manual/embed-languages/index.html
@@ -2363,13 +2363,17 @@ <h2 id="build-native-executables-from-polyglot-applications">
 <pre><code>mvn -Pnative package
 </code></pre>
 
-<p>To build a native executable from a polyglot application, for example, a Java-host application embedding Python, a <code>./resources</code> directory containing all the required files is created by default.
-By default, the language runtime will look for the resources directory relative to the native executable or library image that was built.
+<p>Building a native executable from a polyglot application, for example, a Java-host application embedding Python, automatically captures all the internal resources required by the included languages and tools.
+By default, the resources are included in the native executable itself.
+The inclusion of resources in the native executable can be disabled by <code>-H:-IncludeLanguageResources</code>.
+Another option is a separate <em>resources</em> directory containing all the required files.
+To switch to this option, use <code>-H:+CopyLanguageResources</code>. This is the default behavior when <code>-H:+IncludeLanguageResources</code> is not supported, i.e., with Graal Languages earlier than 24.2.x (see the <a href="https://www.graalvm.org/release-calendar/">versions roadmap</a>).
+When <code>-H:+CopyLanguageResources</code> is used, the language runtime will look for the resources directory relative to the native executable or the shared library.
 At run time, the lookup location may be customized using the <code>-Dpolyglot.engine.resourcePath=path/to/resources</code> option.
-To disable the resource creation, the <code>-H:-CopyLanguageResources</code> build-time option may be used.
-Note that some languages may not support running without a resources directory.</p>
+To disable the capturing of resources altogether, add both <code>-H:-IncludeLanguageResources</code> and <code>-H:-CopyLanguageResources</code> to build-time options.
+Note that some languages may not support running without their resources.</p>
 
-<p>With Polyglot version 23.1 the language home options like <code>-Dorg.graalvm.home</code> should no longer be used and were replaced with the resource directory option.
+<p>With Graal Languages version 23.1 and newer the language home options like <code>-Dorg.graalvm.home</code> should no longer be used and were replaced with the resource directory option.
 The language home options remain functional for compatibility reasons but may be removed in future releases.</p>
 
       <h3 id="configuring-native-host-reflection">

diff --git a/...4/reference-manual/native-image/native-code-interoperability/foreign-interface/index.html b/...4/reference-manual/native-image/native-code-interoperability/foreign-interface/index.html
@@ -633,7 +633,7 @@ <h3 id="looking-up-native-functions">
       </h3>
 
 <p>The FFM API provides the <code>SymbolLookup</code> interface to find functions in native libraries by name.
-<code>SymbolLookup.loaderLookup()</code> is currently the only supported kind of <code>SymbolLookup</code>.</p>
+Native image supports all available symbol lookup methods, i.e., <code>SymbolLookup.loaderLookup()</code>, <code>SymbolLookup.libraryLookup()</code>, and <code>Linker.defaultLookup()</code>.</p>
 
       <h3 id="registering-foreign-calls">
 
@@ -644,9 +644,13 @@ <h3 id="registering-foreign-calls">
       </h3>
 
 <p>In order to perform calls to native code at run time, supporting code must be generated at image build time.
-Therefore, the <code>native-image</code> tool must be provided with descriptors that characterize the functions to which downcalls may be performed at run time.</p>
+Therefore, the <code>native-image</code> tool must be provided with descriptors that characterize the functions with which downcalls or upcalls can be performed at runtime.</p>
 
-<p>These descriptors can be registered using a custom <code>Feature</code>, for example:</p>
+<p>For upcalls, it is recommended to register a specific static method as an upcall target by providing its declaring class and the method name.
+This allows <code>native-image</code> to create specialized upcall code that can be orders of magnitude faster than a upcall registered only by function descriptor.
+Whenever possible, this should be the preferred way to register upcalls.</p>
+
+<p>Descriptors and target methods can be registered using a custom <code>Feature</code>, for example:</p>
 <pre><code class="language-java">import static java.lang.foreign.ValueLayout.*;
 
 class ForeignRegistrationFeature implements Feature { 
@@ -658,6 +662,9 @@ <h3 id="registering-foreign-calls">
     RuntimeForeignAccess.registerForUpcall(FunctionDescriptor.of(JAVA_INT, JAVA_INT, JAVA_INT));
     RuntimeForeignAccess.registerForDowncall(FunctionDescriptor.of(ADDRESS, JAVA_INT, JAVA_INT), Linker.Option.firstVariadicArg(1));
     RuntimeForeignAccess.registerForDowncall(FunctionDescriptor.ofVoid(JAVA_INT), Linker.Option.captureCallState("errno"));
+
+    MethodHandle target = MethodHandles.lookup().findStatic(UserClass.class, "aStaticMethod", MethodType.of(int.class, int.class, int.class));
+    RuntimeForeignAccess.registerForUpcall(target, FunctionDescriptor.of(JAVA_INT, JAVA_INT, JAVA_INT));
   }
 }
 </code></pre>

diff --git a/latest/getting-started/oci/cloud-shell/index.html b/latest/getting-started/oci/cloud-shell/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:19:51+00:00">
+        <meta name="dcterms.created" content="2024-12-06T08:57:31+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/latest/getting-started/oci/code-editor/index.html b/latest/getting-started/oci/code-editor/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:19:51+00:00">
+        <meta name="dcterms.created" content="2024-12-06T08:57:31+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/latest/getting-started/oci/compute-instance/index.html b/latest/getting-started/oci/compute-instance/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:19:51+00:00">
+        <meta name="dcterms.created" content="2024-12-06T08:57:31+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/latest/getting-started/oci/devops-build-pipeline/index.html b/latest/getting-started/oci/devops-build-pipeline/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:19:51+00:00">
+        <meta name="dcterms.created" content="2024-12-06T08:57:31+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/latest/getting-started/oci/index.html b/latest/getting-started/oci/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:19:51+00:00">
+        <meta name="dcterms.created" content="2024-12-06T08:57:31+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/licensing-information/index.html b/licensing-information/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:19:51+00:00">
+        <meta name="dcterms.created" content="2024-12-06T08:57:31+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/reference-manual/graaljs/index.html b/reference-manual/graaljs/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:19:51+00:00">
+        <meta name="dcterms.created" content="2024-12-06T08:57:31+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/reference-manual/graalpy/index.html b/reference-manual/graalpy/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:19:51+00:00">
+        <meta name="dcterms.created" content="2024-12-06T08:57:31+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">

diff --git a/reference-manual/graalwasm/index.html b/reference-manual/graalwasm/index.html
@@ -20,7 +20,7 @@
 
 
 
-        <meta name="dcterms.created" content="2024-12-04T12:19:51+00:00">
+        <meta name="dcterms.created" content="2024-12-06T08:57:31+00:00">
         <meta name="dcterms.category" content="">
         <meta name="dcterms.identifier" content="">
         <meta name="dcterms.product" content="">