update documentation after Graal.js moved to an installable component

Author: wirthi

CHANGELOG.md

@@ -6,6 +6,7 @@ Changelog may include unreleased versions.
 See [version roadmap](https://www.graalvm.org/release-notes/version-roadmap/) for release dates.
 
 ## Version 22.2.0
+* GraalVM JavaScript is now an installable component of GraalVM. It can be installed with `gu install js`.
 * Removed experimental option `commonjs-global-properties`. The same functionality can be achieved in user code with a direct call to `require()` after context creation.
 
 ## Version 22.1.0

README.md

@@ -14,7 +14,18 @@ The goals of GraalVM JavaScript are:
 
 
 ## Getting Started
-See the documentation on the [GraalVM website](https://www.graalvm.org/docs/getting-started/) how to install and use GraalVM JavaScript.
+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
+$ $GRAALVM/bin/gu install js
+$ $GRAALVM/bin/js --version
+```
+
+After installation, the `js` shell can be executed and used to run JavaScript code or execute JavaScript files.
 
 ```
 $ $GRAALVM/bin/js
@@ -23,8 +34,9 @@ Hello JavaScript
 >
 ```
 
-The preferred way to run GraalVM JavaScript is from a [GraalVM](https://www.graalvm.org/downloads/).
 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
 
@@ -36,8 +48,9 @@ For contributors, a guide how to build GraalVM JavaScript from source code can b
 ## Current Status
 
 GraalVM JavaScript is compatible with the [ECMAScript 2021 specification](https://262.ecma-international.org/12.0/).
-Starting with GraalVM 22.0.0, ECMAScript 2022 - currently at the draft stage - is the default compatibility level.
+Starting with GraalVM 22.0.0, [ECMAScript 2022](https://262.ecma-international.org/13.0/) - currently at the draft stage - is the default compatibility level.
 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.
 
 In addition, some popular extensions of other engines are supported, see [`JavaScriptCompatibility.md`](https://github.com/graalvm/graaljs/tree/master/docs/user/JavaScriptCompatibility.md).
 
@@ -48,7 +61,8 @@ It provides high compatibility with existing npm packages, with high likelyhood
 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.
 
-Node.js support is not included in the main GraalVM distribution (since 21.1) but packaged as a separate component that can be installed using the _GraalVM Updater_:
+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
 $ $GRAALVM/bin/gu install nodejs
@@ -58,10 +72,7 @@ $ $GRAALVM/bin/node --version
 ### 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 and MacOS.
-For Windows, a preliminary preview version is available.
-
-Some features, including the Node.js support, are currently not supported on all platforms (e.g. Windows).
+We test and support GraalVM JavaScript currently in full extent on Linux AMD64, Linux AArch64, MacOS, and Windows.
 
 ## GraalVM JavaScript Reference Manual
 

docs/Building.md

@@ -7,9 +7,9 @@ The average user will prefer the pre-built binaries as part of [GraalVM](http://
 
 ### Prerequisites
 
-* Python 3 (required by `mx`), and Python 2.7 for building Node.js
+* Python 3.8+ (required by `mx`)
 * git (to download, update, and locate repositories)
-* Java JDK 8 or newer
+* Java JDK 11 or newer
 
 Building the Node.js support is optional, and requires additional tools, see futher below.
 
@@ -37,14 +37,9 @@ Building the Node.js support is optional, and requires additional tools, see fut
     For the further steps you need to be in either of those directories (we assume you cd'ed to the `graal-js` directory).
 
 4. setup your environment:
-    - if you build with JDK8:
+    - assuming you build with JDK11 or newer:
         ```bash
-        export JAVA_HOME=[path to JDK8]
-        ```
-    - if you build with JDK9+:
-        ```bash
-        export JAVA_HOME=[path to JDK9+]
-        export EXTRA_JAVA_HOMES=[path to JDK8]
+        export JAVA_HOME=[path to JDK11+]
         ```
 5. (optional) clone or update the dependent repositories:
     ```bash

docs/user/FAQ.md

@@ -20,22 +20,30 @@ For a reference of the JavaScript APIs that GraalVM supports, see [GRAAL.JS-API]
 
 ### Is GraalVM compatible with the original node implementation?
 Node.js based on GraalVM is largely compatible with the original Node.js (based on the V8 engine).
-This leads to a high number of npm-based modules being compatible with GraalVM. In fact, out of the 95k modules we test, more than 90% of them pass all tests.
+This leads to a high number of npm-based modules being compatible with GraalVM.
+In fact, out of the 100k npm modules we test, more than 94% of them pass all tests.
 Still, several sources of differences have to be considered:
 
 - **Setup:**
-GraalVM mostly mimicks the original setup of Node, including the `node` executable, `npm`, and similar. However, not all command-line options are supported (or behave exactly identically). You need to (re-)compile native modules against the v8.h file, etc.
+GraalVM mostly mimicks the original setup of Node, including the `node` executable, `npm`, and similar.
+However, not all command-line options are supported (or behave exactly identically).
+Modules might require that native modules are (re-)compiled against the v8.h file.
 
 Since GraalVM 21.1, Node.js and all related executables (e.g., `node`, `npm`, etc.) are not included by default in the GraalVM binary.
 Node.js support is now packaged in a separate component that can be installed with the _GraalVM Updater_ using `$GRAALVM/bin/gu install nodejs`.
 
 - **Internals:**
-GraalVM is implemented on top of a JVM, and thus has a different internal architecture than Node.js based on V8. This implies that some internal mechanisms behave differently and cannot exactly replicate V8 behaviour. This will hardly ever affect user code, but might affect modules implemented natively, depending on V8 internals.
+GraalVM is implemented on top of a JVM, and thus has a different internal architecture than Node.js based on V8.
+This implies that some internal mechanisms behave differently and cannot exactly replicate V8 behaviour.
+This will hardly ever affect user code, but might affect modules implemented natively, depending on V8 internals.
 
 - **Performance:**
-Due to GraalVM being implemented on top of a JVM, performance characteristics vary from the original native implementation. While GraalVM's peak performance can match V8 on many benchmarks, it will typically take longer to reach the peak (known as _warmup_). Be sure to give the GraalVM compiler some extra time when measuring (peak) performance.
+Due to GraalVM being implemented on top of a JVM, performance characteristics vary from the original native implementation.
+While GraalVM's peak performance can match V8 on many benchmarks, it will typically take longer to reach the peak (known as _warmup_).
+Be sure to give the GraalVM compiler some extra time when measuring (peak) performance.
 
-In addition, GraalVM uses the following approaches to check and retain compatibility with Node.js code:
+- **Compatiblity:**
+GraalVM uses the following approaches to check and retain compatibility with Node.js code:
 
 * node-compat-table: GraalVM is compared against other engines using the _node-compat-table_ module, highlighting incompatibilities that might break Node.js code.
 * automated mass-testing of modules using _mocha_: in order to test a large set of modules, GraalVM is tested against 95k modules that use the mocha test framework. Using mocha allows automating the process of executing the test and comprehending the test result.
@@ -96,10 +104,11 @@ 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 8 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 11 or higher) is possible, but, for a better result, it should be GraalVM or a compatible JVMCI-enabled JDK using the GraalVM 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. This will tremendously speed up the startup of any JavaScript application, as GraalVM can immediately start to compile JavaScript code, without itself requiring to be compiled first.
+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.
+This will tremendously speed up the startup of any JavaScript application, as GraalVM can immediately start to compile JavaScript code, without itself requiring to be compiled first.
 This mode, however, will only give GraalVM access to Java classes known at the time of image creation.
 Most significantly, this means that the JavaScript-to-Java interoperability features are not available in this mode, as they would require dynamic class loading and execution of arbitrary Java code at runtime.
 

docs/user/JavaInteroperability.md

@@ -14,12 +14,10 @@ See the [Embedding Reference](https://www.graalvm.org/reference-manual/embed-lan
 The [Polyglot Programming](https://www.graalvm.org/reference-manual/polyglot-programming/) guide can be of additional help in that area.
 Specific migration guides for [Rhino](RhinoMigrationGuide.md) and [Nashorn](NashornMigrationGuide.md) are also available.
 
-GraalVM ships with the `js` native launcher.
-The Node.js support is packaged separately and can be installed with GraalVM Updater:
-```shell
-$GRAALVM/bin/gu install nodejs
-```
-Then the `node` launcher becomes available.
+Both JavaScript and Node.js are separately installable components of GraalVM.
+See the [README](../../README.md) for details on how to use the _GraalVM Updater_ to install JavaScript and Node.js.
+After a successfull installation, the respective native launchers `js` and `node` from the `$GRAALVM/bin` directory can be used.
+
 Although other builds are possible, the following examples assume this setup is used.
 
 ## Enabling Java Interoperability

docs/user/NashornMigrationGuide.md

@@ -231,7 +231,9 @@ When the Java class has both a field and a method of the same name publicly avai
 ## Additional Aspects to Consider
 
 ### Features of GraalVM JavaScript
-GraalVM JavaScript supports features of the newest ECMAScript specification and some extensions to it. See [JavaScript Compatibility](JavaScriptCompatibility.md). Note that this example adds objects to the global scope that might interfere with existing source code unaware of those extensions.
+GraalVM JavaScript supports features of the newest ECMAScript specification and some extensions to it.
+See [JavaScript Compatibility](JavaScriptCompatibility.md).
+Note that this example adds objects to the global scope that might interfere with existing source code unaware of those extensions.
 
 ### Console Output
 GraalVM JavaScript provides a `print` builtin function compatible with Nashorn.