[GR-47943] Backport: Update getting started with Node.js and JavaScript using standalones.

PullRequest: js/2929

Author: olyagpl

README.md

@@ -14,40 +14,72 @@ The goals of GraalVM JavaScript are:
 
 
 ## Getting Started
-The preferred way to run GraalVM JavaScript is from a [GraalVM](https://www.graalvm.org/downloads/).
-Starting with GraalVM 22.2., GraalVM JavaScript is an installable component that needs to be installed with `gu install js` after downloading GraalVM.
-See the documentation on the [GraalVM website](https://www.graalvm.org/docs/getting-started/) for more information on how to install and use GraalVM JavaScript.
-
-Installing GraalVM JavaScript using the _GraalVM Updater_:
-
-```shell
-$JAVA_HOME/bin/gu install js
-$JAVA_HOME/bin/js --version
+The preferred way to run GraalVM JavaScript (a.k.a. GraalJS) is from a [GraalVM](https://www.graalvm.org/downloads/).
+As of GraalVM for JDK 21, (23.1), GraalVM JavaScript and Node.js runtimes are available as [standalone distributions](https://github.com/oracle/graaljs/releases) and [Maven artifacts](https://central.sonatype.com/artifact/org.graalvm.polyglot/js) (but no longer as GraalVM components).
+See the documentation on the [GraalVM website](https://www.graalvm.org/latest/reference-manual/js/) for more information on how to set up GraalVM JavaScript.
+
+### Standalone Distribution
+To install GraalVM JavaScript using the [standalone distribution], simply download and extract the desired archive from the [GitHub Releases](https://github.com/oracle/graaljs/releases) page.
+The standalone archives for the JavaScript and Node.js distributions are named `graaljs[-community][-jvm]-<version>-<os>-<arch>.tar.gz` and `graalnodejs[-community][-jvm]-<version>-<os>-<arch>.tar.gz`, respectively.
+Four different available configurations are available for each component and platform combination:
+
+| Runtime      | License | Archive Infix    |
+| -------------| ------- | ---------------- |
+| Native       | GFTC    | _none_           |
+| JVM          | GFTC    | `-jvm`           |
+| Native       | UPL     | `-community`     |
+| JVM          | UPL     | `-community-jvm` |
+
+After installation, the `js` or `node` executable in the `bin` subdirectory can be used to run JavaScript files or Node modules, respectively.
+If no file is provided on the command line, an interactive shell (REPL) will be spawned.
+
+### Maven Artifact
+All required artifacts for embedding GraalVM JavaScript can be found in the Maven dependency group [`org.graalvm.polyglot`](https://central.sonatype.com/namespace/org.graalvm.polyglot).
+
+Here is a minimal Maven dependency setup that you can copy into your `pom.xml`:
+```xml
+<dependency>
+	<groupId>org.graalvm.polyglot</groupId>
+	<artifactId>polyglot</artifactId>
+	<version>23.1.0</version>
+</dependency>
+<dependency>
+	<groupId>org.graalvm.polyglot</groupId>
+	<artifactId>js</artifactId>
+	<version>23.1.0</version>
+	<type>pom</type>
+</dependency>
+<!-- add additional languages and tools, if needed -->
 ```
 
-After installation, the `js` shell can be executed and used to run JavaScript code or execute JavaScript files.
-
-```
-$JAVA_HOME/bin/js
-> print("Hello JavaScript");
-Hello JavaScript
->
+See the [polyglot embedding demonstration](https://github.com/graalvm/polyglot-embedding-demo) on GitHub for a complete runnable example.
+
+Language and tool dependencies use the [GraalVM Free Terms and Conditions (GFTC)](https://www.oracle.com/downloads/licenses/graal-free-license.html) license by default.
+To use community-licensed versions instead, add the `-community` suffix to each language and tool dependency, e.g.:
+```xml
+<dependency>
+	<groupId>org.graalvm.polyglot</groupId>
+	<artifactId>js-community</artifactId>
+	<version>23.1.0</version>
+	<type>pom</type>
+</dependency>
 ```
+To access [polyglot isolate](https://www.graalvm.org/latest/reference-manual/embed-languages/#polyglot-isolates) artifacts (GFTC only), use the `-isolate` suffix instead (e.g. `js-isolate`).
 
 If you prefer running it on a stock JVM, please have a look at the documentation in [`RunOnJDK.md`](https://github.com/graalvm/graaljs/blob/master/docs/user/RunOnJDK.md).
 Note that in this mode many features and optimizations of GraalVM are not available.
 Due to those limitations, running on a stock JVM is not a supported feature - please use a GraalVM instead.
 
 ## Documentation
 
-Extensive documentation is available on [graalvm.org](https://www.graalvm.org/): how to [`Run JavaScript`](https://www.graalvm.org/docs/getting-started/#running-javascript) and the more extensive [`JavaScript & Node.js Reference Manual`](https://www.graalvm.org/reference-manual/js/).
-In addition there is documentation in the source code repository in the [`docs`](https://github.com/graalvm/graaljs/tree/master/docs) folder, for [`users`](https://github.com/graalvm/graaljs/tree/master/docs/user) and [`contributors`](https://github.com/graalvm/graaljs/tree/master/docs/contributor) of the engine.
+Extensive documentation is available on [graalvm.org](https://www.graalvm.org/): see [Getting Started](https://www.graalvm.org/docs/getting-started/) and the more extensive [JavaScript and Node.js Reference Manual](https://www.graalvm.org/reference-manual/js/).
+In addition, there is documentation in the source code repository in the [`docs`](https://github.com/graalvm/graaljs/tree/master/docs) directory, for [users](https://github.com/graalvm/graaljs/tree/master/docs/user) and [contributors](https://github.com/graalvm/graaljs/tree/master/docs/contributor).
 
 For contributors, a guide how to build GraalVM JavaScript from source code can be found in [`Building.md`](https://github.com/graalvm/graaljs/tree/master/docs/Building.md).
 
 ## Current Status
 
-GraalVM JavaScript is compatible with the [ECMAScript 2022 specification](https://262.ecma-international.org/13.0/).
+GraalVM JavaScript is compatible with the [ECMAScript 2023 specification](https://262.ecma-international.org/14.0/).
 New features, e.g. `ECMAScript proposals` scheduled to land in future editions, are added frequently and are accessible behind a flag.
 See the [CHANGELOG.md](https://github.com/graalvm/graaljs/tree/master/CHANGELOG.md) for the proposals already adopted.
 
@@ -56,22 +88,15 @@ In addition, some popular extensions of other engines are supported, see [`JavaS
 ### Node.js support
 
 GraalVM JavaScript can execute Node.js applications.
-It provides high compatibility with existing npm packages, with high likelyhood that your application will run out of the box.
+It provides high compatibility with existing npm packages, with high likelihood that your application will run out of the box.
 This includes npm packages with native implementations.
 Note that some npm modules will require to be re-compiled from source with GraalVM JavaScript if they ship with binaries that have been compiled for Node.js based on V8.
-
-Similar to JavaScript itself, Node.js is a separately installable component of GraalVM (since 21.1).
-It can be installed using the _GraalVM Updater_:
-
-```shell
-$JAVA_HOME/bin/gu install nodejs
-$JAVA_HOME/bin/node --version
-```
+Node.js is a separate [standalone distribution](#standalone-distribution).
 
 ### Compatibility on Operating Systems
 
 The core JavaScript engine is a Java application and is thus in principle compatible with every operating system that provides a compatible JVM, [see `RunOnJDK.md`](https://github.com/graalvm/graaljs/tree/master/docs/user/RunOnJDK.md).
-We test and support GraalVM JavaScript currently in full extent on Linux AMD64, Linux AArch64, MacOS, and Windows.
+We provide binary distributions and fully support GraalVM JavaScript on Linux (AMD64, AArch64), MacOS (AMD64, AArch64), and Windows (AMD64), currently.
 
 ## GraalVM JavaScript Reference Manual
 
@@ -81,11 +106,14 @@ A reference manual for GraalVM JavaScript is available on the [GraalVM website](
 
 See [graalvm.org/community](https://www.graalvm.org/community/) on how to stay connected with the development community.
 The channel _graaljs_ on [graalvm.slack.com](https://www.graalvm.org/slack-invitation) is a good way to get in touch with us.
+Please report JavaScript-specific issues on the [`oracle/graaljs`](https://github.com/oracle/graaljs/) GitHub repository.
 
-## Licence
+## License
 
-GraalVM JavaScript is available under the following license:
+GraalVM JavaScript source code and community distributions are available under the following license:
 
 * [The Universal Permissive License (UPL), Version 1.0](https://opensource.org/licenses/UPL)
 
+Non-community artifacts are provided under the following license:
 
+* [GraalVM Free Terms and Conditions (GFTC) including License for Early Adopter Versions](https://www.oracle.com/downloads/licenses/graal-free-license.html)

docs/Building.md

@@ -91,7 +91,7 @@ mx js [OPTION]... [FILE]...
 Assuming that you also built the GraalVM compiler (using the instructions in `graal/compiler/README.md`), here is how you can use it to run GraalVM JavaScript:
 ```bash
 cd graaljs/graal-js
-mx --dynamicimports /compiler --jdk jvmci js [OPTION]... [FILE]...
+mx --dynamicimports /compiler js [OPTION]... [FILE]...
 ```
 
 
@@ -130,7 +130,7 @@ mx node [OPTION]... [FILE]...
 Assuming that you also built the GraalVM Compiler (using the instructions in `graal/compiler/README.md`), here is how you can use it to run Node.js on GraalVM JavaScript:
 ```bash
 cd graaljs/graal-nodejs
-mx --dynamicimports /compiler --jdk jvmci node [OPTION]... [FILE]...
+mx --dynamicimports /compiler node [OPTION]... [FILE]...
 ```
 
 

docs/contributor/RegExpImplementation.md

@@ -11,7 +11,7 @@ Below are the most frequently asked questions and answers about JavaScript runni
 ## Compatibility
 
 ### Is GraalVM compatible with the JavaScript language?
-GraalVM is compatible with the ECMAScript 2022 specification and is further developed alongside the 2023 draft specification.
+GraalVM is compatible with the ECMAScript 2023 specification and is further developed alongside the 2024 draft specification.
 The compatibility of GraalVM's JavaScript runtime is verified by external sources, like the [Kangax ECMAScript compatibility table](https://kangax.github.io/compat-table/es6/).
 
 GraalVM JavaScript is tested against a set of test engines, like the official test suite of ECMAScript, [test262](https://github.com/tc39/test262), as well as tests published by V8 and Nashorn, Node.js unit tests, and GraalVM's own unit tests.
@@ -84,16 +84,17 @@ Additionally, you can upload your `package-lock.json` or `package.json` file int
 
 ### My application is slower on GraalVM JavaScript than on another engine
 Reason:
-* Ensure your benchmark considers warmup. During the first few iterations, GraalVM JavaScript will be slower than natively implemented engines, while on peak performance, this difference should level out.
-* GraalVM JavaScript is shipped in two different modes: `native` (default) and `JVM`. While the default of `native` offers fast startup, it might show slower peak performance once the application is warmed up. In the `JVM` mode, the application might need a few hundred milliseconds more to start, but typically shows better peak performance.
+* Ensure your benchmark considers warmup. During the first few iterations, GraalVM JavaScript may be slower than other engines, but after sufficient warmup, this difference should level out.
+* GraalVM JavaScript is shipped in two different standalones: Native (default) and JVM (with a `-jvm` infix). While the default _Native_ mode offers faster startup and lower latency, it might exhibit slower peak performance (lower throughput) once the application is warmed up. In the _JVM_ mode, the application might need hundreds of milliseconds more to start, but typically shows better peak performance.
 * Repeated execution of code via newly created `org.graalvm.polyglot.Context` is slow, despite the same code being executed every time.
 
 Solution:
 * Use proper warmup in your benchmark, and disregard the first few iterations where the application still warms up.
-* Use the `--jvm` option for slower startup, but higher peak performance.
+* When embedding GraalVM JavaScript in a Java application, ensure you're running on a GraalVM JDK for best performance.
+* Use `-jvm` standalones for slower startup, but higher peak performance.
 * Double-check you have no flags set that might lower your performance, e.g., `-ea`/`-esa`.
+* When running code via `org.graalvm.polyglot.Context`, make sure that one `org.graalvm.polyglot.Engine` object is shared and passed to each newly created `Context`. Use `org.graalvm.polyglot.Source` objects and cache them when possible. Then, GraalVM makes sure already compiled code can be shared across the Contexts, leading to improved performance. See [Reference Manual: Code Caching across multiple Contexts](https://www.graalvm.org/latest/reference-manual/embed-languages/#code-caching-across-multiple-contexts) for more details and an example.
 * Try to minify the problem to the root cause and [file an issue](https://github.com/graalvm/graaljs/issues) so the GraalVM team can have a look.
-* When running code via `org.graalvm.polyglot.Context`, make sure that one `org.graalvm.polyglot.Engine` object is shared and passed to each newly created `Context`. Use `org.graalvm.polyglot.Source` objects and cache them when possible. Then, GraalVM makes sure already compiled code can be shared across the Contexts, leading to improved performance. See [Reference Manual: Code Caching across multiple Contexts](https://www.graalvm.org/22.1/reference-manual/embed-languages/#code-caching-across-multiple-contexts) for more details and an example.
 
 ### How to achieve the best peak performance?
 Here are a few tips you can follow to analyse and improve peak performance:
@@ -106,7 +107,7 @@ Here are a few tips you can follow to analyse and improve peak performance:
 
 ### What is the difference between running GraalVM's JavaScript in Native Image compared to the JVM?
 In essence, the JavaScript engine of GraalVM is a plain Java application.
-Running it on any JVM (JDK 11 or higher) is possible, but, for a better result, it should be GraalVM or a compatible JVMCI-enabled JDK using the GraalVM compiler.
+Running it on any JVM (JDK 21 or later) is possible, but, for a better result, it should be GraalVM JDK, or a compatible Oracle JDK or OpenJDK using the Graal Compiler.
 This mode gives the JavaScript engine full access to Java at runtime, but also requires the JVM to first (just-in-time) compile the JavaScript engine when executed, just like any other Java application.
 
 Running in Native Image means that the JavaScript engine, including all its dependencies from, e.g., the JDK, is pre-compiled into a native executable.
@@ -252,15 +253,15 @@ HostAccess ha = HostAccess.newBuilder(HostAccess.EXPLICIT)
 
 ### Warning: Implementation does not support runtime compilation.
 
-If you get the following warning, you are not running on GraalVM or a JVMCI-enabled JVM using the GraalVM compiler:
+If you get the following warning, you are not running on GraalVM JDK, or a compatible Oracle JDK or OpenJDK using the Graal Compiler:
 ```
 [engine] WARNING: The polyglot context is using an implementation that does not support runtime compilation.
 The guest application code will therefore be executed in interpreted mode only.
 Execution only in interpreted mode will strongly impact the guest application performance.
 To disable this warning the '--engine.WarnInterpreterOnly=false' option or use the '-Dpolyglot.engine.WarnInterpreterOnly=false' system property.
 ```
 
-To resolve this, use [GraalVM](https://github.com/oracle/graal/blob/master/docs/getting-started/graalvm-community/get-started-graalvm-community.md) or see the [Run GraalVM JavaScript on a Stock JDK guide](RunOnJDK.md) for instructions how to set up the Graal compiler on a compatible JVMCI-enabled stock JDK.
+To resolve this, use [GraalVM](https://github.com/oracle/graal/blob/master/docs/getting-started/graalvm-community/get-started-graalvm-community.md) or see the [Run GraalVM JavaScript on a Stock JDK guide](RunOnJDK.md) for instructions how to set up the Graal compiler on a compatible Graal-enabled stock JDK.
 
 Nevertheless, if this is intentional, you can disable the warning and continue to run with degraded performance by setting the above mentioned option, either via the command line or using the `Context.Builder`, e.g.:
 ```java