[GR-19691] Update documentation for JVM Standalone instead of GraalVM…

… distribution

PullRequest: truffleruby/4008

CHANGELOG.md

@@ -1585,7 +1585,7 @@ Changes:
 
 * The supported version of LLVM for Oracle Linux has been updated from 3.8 to 4.0.
 * `mysql2` is now patched to avoid a bug in passing `NULL` to `rb_scan_args`, and now passes the majority of its test suite.
-* The post-install script now automatically detects if recompiling the OpenSSL C extension is needed. The post-install script should always be run in TravisCI as well, see `doc/user/standalone-distribution.md`.
+* The post-install script now automatically detects if recompiling the OpenSSL C extension is needed. The post-install script should always be run in TravisCI as well.
 * Detect when the system libssl is incompatible more accurately and add instructions on how to recompile the extension.
 
 # 1.0 RC 8, 19 October 2018

README.md

@@ -7,45 +7,45 @@ of the [Ruby programming language](https://www.ruby-lang.org/en/).
 
 TruffleRuby comes in two distributions:
 
-* Standalone: This only contains TruffleRuby in the [Native configuration](#truffleruby-runtime-configurations), making it a smaller download.
-* GraalVM: This includes support for other languages such as JavaScript, Python and R, and supports both the [Native and JVM configurations](#truffleruby-runtime-configurations).
-  We recommend that you use a [Ruby manager](doc/user/ruby-managers.md#configuring-ruby-managers-for-the-full-graalvm-distribution) to use TruffleRuby inside GraalVM.
+* Native Standalone: This only contains TruffleRuby in the [Native configuration](#truffleruby-runtime-configurations).
+* JVM Standalone: This only contains TruffleRuby in the [JVM configuration](#truffleruby-runtime-configurations).
+  This includes support for other languages such as Java, JavaScript, Python and WebAssembly.
 
 You can install either of those:
 
-* Via your [Ruby manager/installer](doc/user/ruby-managers.md) (RVM, rbenv, chruby, asdf, ruby-build, ruby-install).
+* Via your [Ruby manager/installer](doc/user/ruby-managers.md) (RVM, rbenv, chruby, asdf, ruby-build, ruby-install).  
   We recommend trying TruffleRuby dev builds which contain the latest fixes and improvements (replace `VERSION` by `dev`).
 
-Standalone:
+Native Standalone:
 ```bash
-RVM:    $ rvm install truffleruby
+RVM:    $ rvm install truffleruby # or truffleruby-head
 rbenv:  $ rbenv install truffleruby-VERSION
 asdf:   $ asdf install ruby truffleruby-VERSION
 chruby: $ ruby-install truffleruby
         $ ruby-build truffleruby-VERSION ~/.rubies/truffleruby-VERSION
 ```
-GraalVM:
+JVM Standalone:
 ```bash
 rbenv:  $ rbenv install truffleruby+graalvm-VERSION
 asdf:   $ asdf install ruby truffleruby+graalvm-VERSION
 chruby: $ ruby-install truffleruby-graalvm
         $ ruby-build truffleruby+graalvm-VERSION ~/.rubies/truffleruby+graalvm-VERSION
 ```
 
-* In CI with GitHub Actions, see [Testing TruffleRuby in CI](doc/user/standalone-distribution.md) for more details and other CIs.
+* In CI with GitHub Actions, see [Testing TruffleRuby in CI](doc/user/testing-truffleruby-in-ci.md) for more details and other CIs.
 
 ```yaml
 - uses: ruby/setup-ruby@v1
   with:
-    ruby-version: truffleruby # or truffleruby-head, or truffleruby+graalvm or truffleruby+graalvm-head
+    ruby-version: truffleruby # or truffleruby-head or truffleruby+graalvm or truffleruby+graalvm-head
 ```
 
 * Via Docker.
-  For Standalone see [official release images](https://github.com/graalvm/container/blob/master/truffleruby-community/README.md)
+  For Native Standalone see [official release images](https://github.com/graalvm/container/blob/master/truffleruby-community/README.md)
   and [nightly images](https://github.com/flavorjones/truffleruby/pkgs/container/truffleruby).
-  For GraalVM see [official release images](https://github.com/graalvm/container/blob/master/graalvm-community/README.md).
+  For JVM Standalone there are no Docker images yet, but you can easily [download it](doc/user/installing-truffleruby.md) and take inspiration from the [Native Standalone Dockerfiles](https://github.com/flavorjones/truffleruby/blob/master/tool/dockerfiles/stable.dockerfile).
 
-* Manually, by following the documentation: [Standalone](doc/user/standalone-distribution.md) and [GraalVM](doc/user/installing-graalvm.md).
+* Manually, by following the [documentation](doc/user/installing-truffleruby.md).
 
 You can use `gem` and `bundle` to install gems, as usual.
 
@@ -61,7 +61,7 @@ TruffleRuby aims to:
   * TruffleRuby does not have a global interpreter lock and runs Ruby code in parallel.
 * Support C extensions.
   * Many C extensions work out of the box, including database drivers.
-* Add fast and low-overhead interoperability with languages like Java, JavaScript, Python, and R.
+* Add fast and low-overhead interoperability with languages like Java, JavaScript, Python and WebAssembly.
   * Provided by GraalVM, see the [Polyglot documentation](doc/user/polyglot.md).
 * Provide new tooling, such as debuggers and monitoring, that works across languages.
   * Includes a profiler, debugger, VisualVM, and more. See the [Tools documentation](doc/user/tools.md).
@@ -129,8 +129,9 @@ If you find any performance issue, please see [this guide](doc/user/reporting-pe
 
 ## Releases
 
-TruffleRuby has the same version and is released at the same time as GraalVM.
-See the [release roadmap](https://www.graalvm.org/release-notes/version-roadmap/) for the release dates and information about how long releases are supported.
+TruffleRuby is released at the same time as GraalVM.
+TruffleRuby continues to use the release numbering based on the calendar year, for example, 21.x, and 22.x., same as GraalVM prior to 2023.
+See the [release roadmap](https://www.graalvm.org/release-notes/version-roadmap/) and [the upcoming releases list](https://github.com/oracle/truffleruby/milestones?state=open) for the release dates and information about how long releases are supported.
 GraalVM Community Edition releases are supported at most one year.
 [Longer support](https://docs.oracle.com/en/graalvm/enterprise/22/docs/release-calendar/) is available for Oracle GraalVM.
 

doc/contributor/native-image.md

@@ -24,9 +24,8 @@ https://youtu.be/FJY96_6Y3a4?t=10023
 More information can be found in Kevin Menard's
 [blog post](http://nirvdrum.com/2017/02/15/truffleruby-on-the-substrate-vm.html).
 
-The TruffleRuby that is distributed in the
-[GraalVM](../user/installing-graalvm.md) by default uses a version compiled
-using the Native Image Generator - this is to prioritise fast start-up and
+The TruffleRuby that is distributed in the TruffleRuby [Native Standalone](../../README.md#getting-started)
+by default uses a version compiled using [Native Image](https://www.graalvm.org/reference-manual/native-image/) - this is to prioritise fast start-up and
 warm-up time for shorter running commands and benchmarks.
 
 ```bash

doc/contributor/updating-ruby.md

@@ -43,8 +43,7 @@ rm -rf ~/tmp/ruby-$VERSION
 (required as `RUBY_BUILD_DIR` for `tool/import-mri-files.sh`),
 so one needs the extra `ruby-install` command when using `ruby-build`.
 
-See https://github.com/oracle/truffleruby/blob/master/doc/user/ruby-managers.md#ruby-install-and-chruby for details
-about `ruby-install`.
+See [these docs](../../doc/user/ruby-managers.md#ruby-install-and-chruby) for details about `ruby-install`.
 
 ## Create reference branches
 

doc/legal/legal.md

@@ -1,8 +1,7 @@
 # Legal Documentation
 
-This document applies to TruffleRuby as built and distributed as part of
-GraalVM or the standalone distribution, which are the only supported ways to
-use TruffleRuby.
+This document applies to TruffleRuby as built and distributed as the Native Standalone and JVM Standalone distributions,
+which are the only supported ways to use TruffleRuby.
 
 ## TruffleRuby
 

doc/user/benchmarking.md

@@ -14,7 +14,7 @@ We expect anyone publishing benchmark numbers about TruffleRuby to follow these
 
 ### Use Oracle GraalVM
 
-Use [Oracle GraalVM](installing-graalvm.md) (before 23.0: GraalVM EE), it is faster than GraalVM CE overall and represents what TruffleRuby is capable of.
+Use [Oracle GraalVM](installing-truffleruby.md#oracle-graalvm-and-graalvm-community-edition) (before 23.0: GraalVM Enterprise Edition), it is faster than GraalVM Community Edition overall and represents what TruffleRuby is capable of.
 
 Use `ruby --version` to ensure that you are running Oracle GraalVM.
 

doc/user/compatibility.md

@@ -29,7 +29,7 @@ TruffleRuby defines these constants for identification:
 - `RUBY_REVISION` is the full `git` commit hash used to build TruffleRuby (similar to MRI 2.7+).
 - `RUBY_RELEASE_DATE` is the `git` commit date.
 - `RUBY_PATCHLEVEL` is always zero.
-- `RUBY_ENGINE_VERSION` is the GraalVM version, or `0.0-` and the Git commit hash if your build is not part of a GraalVM release.
+- `RUBY_ENGINE_VERSION` is the TruffleRuby version, or `0.0-` and the Git commit hash if your build is not part of a TruffleRuby release.
 
 In the C API, the preprocessor macro `TRUFFLERUBY` is defined, which can be checked with `#ifdef TRUFFLERUBY`.
 

doc/user/deploying.md

@@ -12,26 +12,25 @@ This document details TruffleRuby's different *runtime* configurations.
 
 ## TruffleRuby Runtime Configurations
 
-There are two main configurations of TruffleRuby - *native* and *JVM*.
+There are two main configurations of TruffleRuby - *Native* and *JVM*.
 It is important to understand the different configurations of TruffleRuby, as each has different capabilities and performance characteristics.
 You should pick the execution mode that is appropriate for your application.
 
 ### Native Configuration
 
-When distributed as part of GraalVM, TruffleRuby by default runs in the *native* configuration.
+In the Native Standalone, TruffleRuby runs in the *native* configuration.
 In this configuration, TruffleRuby is ahead-of-time compiled to a standalone native executable.
 This means that you do not need a JVM installed on your system to use it.
 
-The advantages of the native configuration are that it [starts about as fast as MRI](https://eregon.me/blog/2019/04/24/how-truffleruby-startup-became-faster-than-mri.html), it may use less memory, and it becomes fast in less time than the *JVM*
-configuration.
+The advantages of the native configuration are that it [starts about as fast as MRI](https://eregon.me/blog/2019/04/24/how-truffleruby-startup-became-faster-than-mri.html), it may use less memory, and it becomes fast in less time than the *JVM* configuration.
 The disadvantages are that you can't use Java tools like VisualVM, it is less convenient for Java interoperability (see the details [here](compatibility.md#java-interoperability-with-the-native-configuration)), and *peak performance may be lower than on the JVM*.
 
 The native configuration is used by default, but you can also request it using `--native`.
 To use polyglot programming with the *native* configuration, you need to pass the `--polyglot` flag.
 
 ### JVM Configuration
 
-TruffleRuby can also be used in the *JVM* configuration, where it runs as a normal Java application on the JVM.
+TruffleRuby can also be used in the *JVM* configuration (by using the JVM Standalone or through embedding), where it runs as a normal Java application on the JVM.
 The advantages of the JVM configuration are that you can use Java interoperability easily, and *peak performance may be higher than the native configuration*.
 The disadvantages are that it takes much longer to start and to get fast, and may use more memory.
 You can select the JVM configuration by passing `--jvm`.

doc/user/faq.md

@@ -35,13 +35,12 @@ However this is complicated, so normally the Truffle framework uses the GraalVM
 
 GraalVM is the platform on which TruffleRuby runs. It is a system for high-performance polyglot programming.
 
-More concretely, GraalVM is a modified version of the OracleJDK that includes the Truffle framework, the GraalVM compiler, TruffleRuby, and other languages supported by GraalVM including JavaScript, Python, and R.
-
-See how to [install GraalVM and TruffleRuby](installing-graalvm.md).
+More concretely, GraalVM is a JDK (Java Development Kit) with extra components like the GraalVM compiler and GraalVM Native Image.
+The GraalVM compiler and GraalVM Native Image are then used by Truffle languages like TruffleRuby.
 
 ### How do I get TruffleRuby?
 
-There are three ways to get TruffleRuby. Please see [Getting Started](../../README.md#system-compatibility).
+There are multiple ways to install TruffleRuby, see [Getting Started](../../README.md#getting-started).
 
 ### Why is TruffleRuby slow on a standard JVM?
 
@@ -121,7 +120,7 @@ Benchmarks that we haven't looked at yet may require new code paths to be specia
 Currently we've added specialization for the code paths in the benchmarks and applications that we've been using.
 Adding them is generally not complicated and over time we will have specializations to cover a broad range of applications.
 
-Make sure that you are using [Oracle GraalVM, and have rebuilt the executable images](installing-graalvm.md) for the best performance.
+Make sure that you are using [Oracle GraalVM](installing-truffleruby.md#oracle-graalvm-and-graalvm-community-edition) for the best performance.
 
 ### How is this related to `invokedynamic`?
 

doc/user/installing-graalvm.md

@@ -6,59 +6,4 @@ permalink: /reference-manual/ruby/InstallingGraalVM/
 ---
 # Using TruffleRuby with GraalVM
 
-[GraalVM](http://graalvm.org/) is the platform on which TruffleRuby runs.
-
-Installing GraalVM enables you to run TruffleRuby both in the `--native` and `--jvm` [runtime configurations](../../README.md#truffleruby-runtime-configurations).
-
-## Dependencies
-
-[TruffleRuby's dependencies](../../README.md#dependencies) need to be installed for TruffleRuby to run correctly.
-
-## GraalVM Community Edition and Oracle GraalVM
-
-GraalVM is available in a Community Edition, which is open-source, and [Oracle GraalVM](https://www.oracle.com/graalvm/) which has better performance, footprint and scalability.
-See [the website](https://www.graalvm.org/downloads) for a comparison.
-
-## Installing the Base Image
-
-GraalVM starts with a base image which provides the platform for high-performance language runtimes.
-
-The Community Edition base image can be installed [from GitHub](https://www.graalvm.org/downloads), under an open source licence.
-
-Install the Oracle GraalVM base image from the [Oracle Downloads](https://www.oracle.com/downloads/graalvm-downloads.html) page by accepting the Oracle License Agreement.
-
-GraalVM Community Developer Builds are [also available](https://github.com/graalvm/graalvm-ce-dev-builds/releases).
-
-Whichever edition you choose, you will obtain a tarball which you can extract.
-There will be a `bin` directory (`Contents/Home/bin` on macOS) which you can add to your `$PATH` if you want to.
-
-### Installing with asdf
-
-Using [asdf](https://github.com/asdf-vm/asdf) and [asdf-java](https://github.com/halcyon/asdf-java) installation is as easy as
-`asdf install java graalvm-20.1.0+java11` (look up versions via `asdf list-all java | grep graalvm`).
-
-## Installing Ruby and Other Languages
-
-After installing GraalVM you then need to install the Ruby language into it.
-This is done using the `gu` command.
-The Ruby package is the same for both editions of GraalVM and comes from GitHub:
-```bash
-gu install ruby
-```
-
-This command will show a message regarding running a post-install script.
-This is necessary to make the Ruby `openssl` C extension work with your system libssl.
-Please run that script now.
-The path of the script will be:
-```bash
-languages/ruby/lib/truffle/post_install_hook.sh
-```
-
-You can also download the latest Ruby component (`ruby-installable-...`) manually from [GitHub](https://github.com/oracle/truffleruby/releases/latest) for GraalVM CE
-or from [Oracle Downloads](https://www.oracle.com/downloads/graalvm-downloads.html) for Oracle GraalVM.
-Then install it with `gu install --file path/to/ruby-installable-...`.
-
-## Using a Ruby Manager
-
-Inside GraalVM is a `jre/languages/ruby` or `languages/ruby` directory which has the usual structure of a Ruby implementation. It is recommended to add this directory to a Ruby manager.
-See [configuring Ruby managers](ruby-managers.md) for more information.
+This documentation has moved to [Installing TruffleRuby](installing-truffleruby.md).

doc/user/installing-libssl.md

@@ -10,7 +10,7 @@ TruffleRuby provides the `openssl` gem but not the native `libssl` system librar
 TruffleRuby supports libssl versions 1.0.2, 1.1.0 and 3.0.0.
 
 If you experience `openssl`-related errors, it might help to recompile the `openssl` gem by running `lib/truffle/post_install_hook.sh`.
-This is done automatically by Ruby managers, and mentioned in the post-install message when installing TruffleRuby via `gu install` in GraalVM.
+This is done automatically by Ruby managers.
 
 To compile TruffleRuby against a non-system `libssl`, set `OPENSSL_PREFIX` while installing TruffleRuby:
 ```bash

doc/user/installing-libyaml.md

@@ -9,7 +9,7 @@ permalink: /reference-manual/ruby/InstallingLibYAML/
 TruffleRuby requires to have `libyaml` installed, much like CRuby 3.2+ and Psych 5+.
 
 If you experience `psych`-related errors saying it cannot find `libyaml`, it might help to recompile the `psych` gem by running `lib/truffle/post_install_hook.sh`.
-This is done automatically by Ruby managers, and mentioned in the post-install message when installing TruffleRuby via `gu install` in GraalVM.
+This is done automatically by Ruby managers.
 
 ### Fedora-based: RHEL, Oracle Linux, etc