From ca08301cf26b5bd2cf047cf59572ca901c5f78ba Mon Sep 17 00:00:00 2001
From: Stefan Bodewig <bodewig@apache.org>
Date: Mon, 10 Aug 2020 18:12:53 +0200
Subject: [PATCH] add some documentation about GraalVM JavaScript

---
 manual/Tasks/script.html | 16 +++++++++++++++-
 manual/install.html      | 17 ++++++++++++++++-
 2 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/manual/Tasks/script.html b/manual/Tasks/script.html
index 7cb6a477c..e029cd9db 100644
--- a/manual/Tasks/script.html
+++ b/manual/Tasks/script.html
@@ -274,11 +274,25 @@ with <code>importClass</code>/<code>importPackage</code>. For other packages you
 full classified name with <strong>Packages</strong>. For example
 Ant's <code class="code">FileUtils</code> class can be imported
 with <code class="code">importClass(<strong>Packages</strong>.org.apache.tools.ant.util.FileUtils)</code></p>
-<p>In Java 8+, you may use the built-in Nashorn JavaScript engine rather than Rhino (which is
+<p>In Java 8 up until Java 14, you may use the built-in Nashorn JavaScript engine rather than Rhino (which is
 available in Java 7 runtime). Then, use <code>Java.type</code> as import statement for any Java
 class
 or <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/prog_guide/javascript.html#A1147207">the
 compatibility script</a>: <code>load("nashorn:mozilla_compat.js");</code>.</p>
+
+<p>Starting with Java 15 Nashorn has been removed again and you need
+  to provide an external JavaScript engine. Your best option probably
+  is <a href="https://github.com/graalvm/graaljs">GraalVM
+  JavaScript</a> which requires you to add a lot of extra jars. For
+  GraalVM JavaScript 20.1 you'll
+  need <code>org.graalvm.js:js</code>, <code>org.graalvm.js:js-engine</code>
+  which in turn
+  require <code>org.graalvm.regex:regex</code>, <code>org.graalvm.truffle:truffle-api</code>, <code>org.graalvm.sdk:graal-sdk</code>,
+  and <code>com.ibm.icu:icu4j</code>. GraalVM JavaScript is not a
+  drop-in replacement for Nashorn, see
+  Graal's <a href="https://github.com/graalvm/graaljs/blob/master/docs/user/NashornMigrationGuide.md">Nashorn
+  Migration Guide</a> for more details.</p>
+
 <p>The <code>&lt;script&gt;</code> task populates the Project instance under the
 name <code class="code">project</code>, so we can use that reference. Another way is to use its
 given name or getting its reference from the task itself. The Project provides methods for accessing
diff --git a/manual/install.html b/manual/install.html
index 4938e632b..3984bee36 100644
--- a/manual/install.html
+++ b/manual/install.html
@@ -828,11 +828,26 @@ these tasks available. Please refer to the <a href="#optionalTasks">Installing A
            target="_top">https://www.ibm.com/software/awdtools/netrexx/library.html</a></td>
   </tr>
   <tr>
-    <td>rhino.jar<br/>(included in Java 7 runtime, replaced by Nashorn in Java&nbsp;8 and later)</td>
+    <td>rhino.jar<br/>(included in Java 7 runtime, replaced by Nashorn
+      in Java&nbsp;8 and later, dropped with Java 15)</td>
     <td>JavaScript with <a href="Tasks/script.html">script</a> task<br/><strong>Note</strong>: Apache BSF 2.4.0 works
       only with Rhino 1.5R4 and later versions.</td>
     <td><a href="https://www.mozilla.org/rhino/" target="_top">https://www.mozilla.org/rhino/</a></td>
   </tr>
+  <tr>
+    <td>graalvm js.jar and js-scriptengine.jar<br/></td>
+    <td>JavaScript with <a href="Tasks/script.html">script</a> task for Java 15 and later<br/>
+    </td>
+    <td>Java 15 has dropped Nashorn
+      and <a href="https://github.com/graalvm/graaljs">GraalVM JavaScript</a>
+      is meant to replace it - outside of the Java class
+      library.<br/>
+      <strong>Note</strong> GraalVM JavaScript is not a drop-in
+      replacement for Nashorn, see the script task documentation for
+      details. Also GraakVM JavaScript requires a couple of more
+      dependencies, in particular GraalVM regex, truffle, the GraalVM
+      SDK and ICU.</td>
+  </tr>
   <tr>
     <td>jython.jar</td>
     <td>Python with <a href="Tasks/script.html">script</a> task</td>