diff --git a/CHANGELOG.md b/CHANGELOG.md index f2f07a080908..c0f4e0a4449b 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index d937b981e69b..40e8ab1ad926 100644 --- a/README.md +++ b/README.md @@ -7,24 +7,24 @@ 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 @@ -32,20 +32,20 @@ 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. diff --git a/doc/contributor/native-image.md b/doc/contributor/native-image.md index b7504490a6be..8f3ac3b4d89b 100644 --- a/doc/contributor/native-image.md +++ b/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 diff --git a/doc/contributor/updating-ruby.md b/doc/contributor/updating-ruby.md index 6026449080b2..84d7b90ac635 100644 --- a/doc/contributor/updating-ruby.md +++ b/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 diff --git a/doc/legal/legal.md b/doc/legal/legal.md index 4b58c91e154d..a5a11c020fae 100644 --- a/doc/legal/legal.md +++ b/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 diff --git a/doc/user/benchmarking.md b/doc/user/benchmarking.md index 3163a2e0980d..13173474c862 100644 --- a/doc/user/benchmarking.md +++ b/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. diff --git a/doc/user/compatibility.md b/doc/user/compatibility.md index a766b79c8c56..c2949935b46c 100644 --- a/doc/user/compatibility.md +++ b/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`. diff --git a/doc/user/deploying.md b/doc/user/deploying.md index cff63014eb43..b8313ca3c658 100644 --- a/doc/user/deploying.md +++ b/doc/user/deploying.md @@ -12,18 +12,17 @@ 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`. @@ -31,7 +30,7 @@ To use polyglot programming with the *native* configuration, you need to pass th ### 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`. diff --git a/doc/user/faq.md b/doc/user/faq.md index 18870091a23e..fa7565f9d9e7 100644 --- a/doc/user/faq.md +++ b/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`? diff --git a/doc/user/installing-graalvm.md b/doc/user/installing-graalvm.md index 9fbfdff23fdc..ed5dbb859dad 100644 --- a/doc/user/installing-graalvm.md +++ b/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). diff --git a/doc/user/installing-libssl.md b/doc/user/installing-libssl.md index 295b01fb4610..8d558c53b26f 100644 --- a/doc/user/installing-libssl.md +++ b/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 diff --git a/doc/user/installing-libyaml.md b/doc/user/installing-libyaml.md index 7dbf21c5c944..c3cf9f957bd6 100644 --- a/doc/user/installing-libyaml.md +++ b/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 diff --git a/doc/user/installing-truffleruby.md b/doc/user/installing-truffleruby.md new file mode 100644 index 000000000000..9dccb0c63322 --- /dev/null +++ b/doc/user/installing-truffleruby.md @@ -0,0 +1,75 @@ +--- +layout: docs-experimental +toc_group: ruby +link_title: Installing TruffleRuby +permalink: /reference-manual/ruby/InstallingTruffleRuby/ +--- +# Installing TruffleRuby + +The recommended way to install TruffleRuby is via your Ruby manager/installer, see [Getting Started](../../README.md#getting-started). + +You can also install TruffleRuby by manually downloading the binary tarball, extracting it, running the post-install script and adding TruffleRuby to `$PATH`. +This page documents the URLs and the extra steps necessary after downloading the tarball. + +## Dependencies + +[TruffleRuby's dependencies](../../README.md#dependencies) need to be installed for TruffleRuby to run correctly. + +## Oracle GraalVM and GraalVM Community Edition + +There are 2 variants of TruffleRuby and GraalVM: +* Oracle GraalVM, which provides the best TruffleRuby experience: it is significantly faster and more memory-efficient. +* GraalVM Community Edition, which is fully open-source. + +Oracle GraalVM is the GraalVM distribution from Oracle available under the [GraalVM Free Terms and Conditions](https://medium.com/graalvm/161527df3d76). + +## Download Links + +### Native Standalone + +Releases of the Native Standalone are [available on GitHub](https://github.com/oracle/truffleruby/releases/latest). +The Native Standalones are the files: +``` +# Oracle GraalVM Native Standalone +truffleruby-VERSION-PLATFORM.tar.gz +# GraalVM Community Edition Native Standalone +truffleruby-community-VERSION-PLATFORM.tar.gz +``` + +Development builds are [also available](https://github.com/ruby/truffleruby-dev-builder/releases/latest). +More platforms for dev builds are [available here](https://github.com/graalvm/graalvm-ce-dev-builds/releases/latest) but those builds tend to be slightly older. +The Native Standalones are the files `truffleruby-community-dev-PLATFORM.tar.gz`. + +### JVM Standalone + +Releases of the Native Standalone are [available on GitHub](https://github.com/oracle/truffleruby/releases/latest). +The JVM Standalones are the files: +``` +# Oracle GraalVM JVM Standalone +truffleruby-jvm-VERSION-PLATFORM.tar.gz +# GraalVM Community Edition JVM Standalone +truffleruby-community-jvm-VERSION-PLATFORM.tar.gz +``` + +Development builds are [also available](https://github.com/graalvm/graalvm-ce-dev-builds/releases/latest). +The JVM Standalones are the files `truffleruby-community-jvm-dev-PLATFORM.tar.gz`. + +## After Downloading + +Once you have downloaded a tarball, extract it. +We will refer to the directory you extracted it as `$EXTRACTED_DIRECTORY`. +This directory should contain `bin/truffleruby`, `lib/truffle`, etc. + +Then you need to run the post-install script. +This is necessary to make the Ruby `openssl` C extension work with your system libssl. +The path of the script will be: +```bash +$EXTRACTED_DIRECTORY/lib/truffle/post_install_hook.sh +``` + +You can then add `$EXTRACTED_DIRECTORY/bin` to `PATH` and use `ruby`/`gem`/`bundle`/etc. + +## RubyGems Configuration + +Note that you also need to ensure `GEM_HOME` and `GEM_PATH` are not set, so TruffleRuby uses the correct `GEM_HOME` and `GEM_PATH`. +See [Using TruffleRuby without a Ruby manager](ruby-managers.md#using-truffleruby-without-a-ruby-manager) for details. diff --git a/doc/user/jruby-migration.md b/doc/user/jruby-migration.md index 3711d782e709..35ab78771a52 100644 --- a/doc/user/jruby-migration.md +++ b/doc/user/jruby-migration.md @@ -10,24 +10,21 @@ When trying TruffleRuby on your gems and applications, you are encouraged to [ge ## Deployment -If you are migrating from JRuby, probably the easiest way to use TruffleRuby is via [GraalVM](installing-graalvm.md), which gives you a JVM, JavaScript, Ruby, and other languages in one package. +If you are migrating from JRuby, probably the easiest way to use TruffleRuby is to install the [TruffleRuby JVM Standalone](../../README.md#getting-started). -If you do not need the Java interoperability capabilities of TruffleRuby, then you could also install via your [Ruby manager/installer](ruby-managers.md) as with any other implementation of Ruby. - -You can also use the [standalone distribution](standalone-distribution.md) as a simple tarball. -The standalone distribution does not allow for Java interoperability. +If you do not need the Java interoperability capabilities of TruffleRuby, then you can install the [TruffleRuby Native Standalone](../../README.md#getting-started). ## Using Ruby from Java JRuby supports many different ways to embed Ruby in Java, including JSR 223 (also know as `javax.script`), the Bean Scripting Framework (BSF), JRuby Embed (also known as Red Bridge), and the JRuby direct embedding API. -The best way to embed TruffleRuby is to use the Polyglot API, which is part of GraalVM. +The best way to embed TruffleRuby is to use the Polyglot API. The API is different because it is designed to support many languages, not just Ruby. TruffleRuby also supports JSR 223, compatible with JRuby, to make it easier to run legacy JRuby code. See [this documentation](https://github.com/oracle/graal/blob/master/docs/reference-manual/embedding/embed-languages.md#compatibility-with-jsr-223-scriptengine) for how to use it. -You will need to use GraalVM to use both of these APIs. +You will need to use the JVM standalone or depend on the `org.graalvm.polyglot:polyglot` Maven package to use the Polyglot API. See the [polyglot](polyglot.md) documentation for more information about how to use Ruby from other languages including Java; this document only shows the comparison to JRuby. @@ -362,7 +359,7 @@ Constants are read by reading properties of the class rather than using Ruby not ### Require Java Do not `require 'java'` in TruffleRuby. However, you do need to run in `--jvm` mode. -This is only available in GraalVM - not in the standalone distribution installed by Ruby version managers and installers. +This is not available in the Native Standalone. ### Referring to Classes @@ -493,4 +490,4 @@ TruffleRuby does not support this at the moment. VisualVM works for TruffleRuby as for JRuby. -Additionally, the VisualVM included in GraalVM understands Ruby objects, rather than Java objects, when you use the heap dump tool. +Additionally, VisualVM understands Ruby objects, rather than Java objects, when you use the heap dump tool. diff --git a/doc/user/optcarrot.md b/doc/user/optcarrot.md index 651e4d6022b3..7e79f1608d35 100644 --- a/doc/user/optcarrot.md +++ b/doc/user/optcarrot.md @@ -8,12 +8,7 @@ permalink: /reference-manual/ruby/Optcarrot/ ## Running the Demo -Start by [installing GraalVM](installing-graalvm.md). - -Then add GraalVM/bin in `PATH` (or use a Ruby manager): -```bash -export PATH="/path/to/graalvm/bin:$PATH" -``` +Start by [installing the TruffleRuby JVM Standalone](../../README.md#getting-started). You also need to install SDL2: * `brew install sdl2` on macOS @@ -38,7 +33,7 @@ On macOS, you need an extra flag, `--vm.XstartOnFirstThread`, for the GUI to app ruby --jvm --vm.XstartOnFirstThread bin/optcarrot --print-fps --sdl2 --audio=none examples/Lan_Master.nes ``` -Note: `--audio=none` is used since the audio it not nice at non-60FPS speeds. +Note: `--audio=none` is used since the audio is not nice at non-60FPS speeds. To play, use keys `1`...`7` (not on numpad) to scale the screen, `X` for OK/turn right, `S` for turn left, arrows to move around, and `Q` to quit. diff --git a/doc/user/reporting-performance-problems.md b/doc/user/reporting-performance-problems.md index fd6aac209024..3757353be0a8 100644 --- a/doc/user/reporting-performance-problems.md +++ b/doc/user/reporting-performance-problems.md @@ -25,7 +25,7 @@ All of these issues make it hard to benchmark TruffleRuby. This is not a problem ## Using Oracle GraalVM -To experiment with how fast TruffleRuby can be, use [Oracle GraalVM](installing-graalvm.md). +To experiment with how fast TruffleRuby can be, use [Oracle GraalVM](installing-truffleruby.md#oracle-graalvm-and-graalvm-community-edition). ## Using the JVM Configuration diff --git a/doc/user/ruby-managers.md b/doc/user/ruby-managers.md index 8d8d820c2e39..fe6399805cb4 100644 --- a/doc/user/ruby-managers.md +++ b/doc/user/ruby-managers.md @@ -6,15 +6,9 @@ permalink: /reference-manual/ruby/RubyManagers/ --- # Ruby Managers and Installers -If you have [installed GraalVM](installing-graalvm.md), it is recommended to add TruffleRuby to a Ruby manager. -See -[Configuring Ruby managers for the full GraalVM distribution](#configuring-ruby-managers-for-the-full-graalvm-distribution) below. - -## Installing TruffleRuby with `rvm`, `ruby-build`, `asdf` or `ruby-install` - TruffleRuby is supported by the 3 major Ruby installers. -### `rvm` +## `rvm` Upgrade `rvm` to let `rvm` know about the latest TruffleRuby release: @@ -22,19 +16,19 @@ Upgrade `rvm` to let `rvm` know about the latest TruffleRuby release: rvm get head ``` -Install the latest TruffleRuby standalone release with: +Install the latest TruffleRuby Native Standalone release with: ```bash rvm install truffleruby ``` -You can also install the latest nightly standalone build of TruffleRuby with: +You can also install the latest Native Standalone dev build of TruffleRuby with: ```bash rvm install truffleruby-head ``` -### `ruby-build` and `rbenv` +## `ruby-build` and `rbenv` We assume you already have [`ruby-build`](https://github.com/rbenv/ruby-build) installed as a plugin for [`rbenv`](https://github.com/rbenv/rbenv). @@ -53,41 +47,41 @@ Check the latest available version of TruffleRuby with: rbenv install --list ``` -Then install the latest TruffleRuby standalone release with: +Then install the latest TruffleRuby Native Standalone release with: ```bash rbenv install truffleruby-[LATEST_VERSION] ``` -You can also install the latest nightly standalone build of TruffleRuby with: +You can also install the latest Native Standalone dev build of TruffleRuby with: ```bash rbenv install truffleruby-dev ``` -You can also install TruffleRuby+GraalVM with: +You can also install the TruffleRuby JVM Standalone with: ```bash rbenv install truffleruby+graalvm-[LATEST_VERSION] OR truffleruby+graalvm-dev ``` -### `asdf` (with `asdf-ruby` plugin) +## `asdf` (with `asdf-ruby` plugin) See https://github.com/asdf-vm/asdf-ruby for installing and updating `asdf-ruby`. -You can install a TruffleRuby standalone release or nightly build with: +You can install a TruffleRuby Native Standalone release or dev build with: ```bash asdf install ruby truffleruby-VERSION OR truffleruby-dev ``` -You can install TruffleRuby+GraalVM with: +You can also install the TruffleRuby JVM Standalone with: ```bash asdf install ruby truffleruby+graalvm-VERSION OR truffleruby+graalvm-dev ``` -### `ruby-install` and `chruby` +## `ruby-install` and `chruby` See https://github.com/postmodern/ruby-install#install for installing and updating `ruby-install`. @@ -102,21 +96,21 @@ And compare to the [latest tag](https://github.com/postmodern/ruby-install/tags) If it is older, you should update to the latest `ruby-install` (e.g. 0.8.4 is necessary for aarch64 support). Follow the [installation instructions](https://github.com/postmodern/ruby-install#install), since the steps for upgrading `ruby-install` are the same as the steps for installing it. -Then install the latest TruffleRuby standalone release with: +Then install the latest TruffleRuby Native Standalone release with: ```bash ruby-install --update ruby-install truffleruby ``` -You can also install TruffleRuby+GraalVM with: +You can also install the TruffleRuby JVM Standalone with: ```bash ruby-install truffleruby-graalvm ``` -`ruby-install` does not support installing nightly builds. -Please use `ruby-build` (which also works with `chruby`) if you want to install nightly builds: +`ruby-install` does not support installing dev builds. +Please use `ruby-build` (which also works with `chruby`) if you want to install dev builds: ```bash ruby-build truffleruby-dev ~/.rubies/truffleruby-dev @@ -126,67 +120,6 @@ ruby-build truffleruby+graalvm-dev ~/.rubies/truffleruby+graalvm-dev There are also instructions on the [chruby wiki](https://github.com/postmodern/chruby/wiki/TruffleRuby) if you prefer to install TruffleRuby manually. -## Configuring Ruby Managers for the Full GraalVM Distribution - -When [installing GraalVM and Ruby](installing-graalvm.md), it is recommended to add TruffleRuby to a Ruby manager for ease of use. - -Make sure you ran the post-install script *before* adding GraalVM to Ruby managers. - -Then follow these steps to integrate GraalVM with your Ruby manager. - -The first step is to find the TruffleRuby home. -On macOS, run: -```bash -ruby_home=$(path/to/graalvm/Contents/Home/bin/ruby -e 'print RbConfig::CONFIG["prefix"]') -``` - -On Linux and other platforms, run: -```bash -ruby_home=$(path/to/graalvm/bin/ruby -e 'print RbConfig::CONFIG["prefix"]') -``` - -### `rbenv` - -To add TruffleRuby to `rbenv`, create a symbolic link in the `versions` directory of `rbenv`: - -```bash -ln -s "$ruby_home" "$RBENV_ROOT/versions/truffleruby" -rbenv shell truffleruby -ruby --version -``` - -### `chruby` - -To add TruffleRuby to `chruby`, create a symbolic link to the `$HOME/.rubies` directory: - -```bash -ln -s "$ruby_home" "$HOME/.rubies/truffleruby" -chruby truffleruby -ruby --version -``` - -### `rvm` - -`rvm` has a command for adding a precompiled Ruby to the list of available rubies: - -```bash -rvm mount "$ruby_home" -n truffleruby -rvm use ext-truffleruby -ruby --version -``` - -### `asdf` (with `asdf-ruby` plugin) - -To add TruffleRuby to `asdf`, create a symbolic link in the `.installs/ruby` directory. -You also need to reshim: - -```bash -ln -s "$ruby_home" "$HOME/.asdf/installs/ruby/truffleruby" -asdf reshim ruby truffleruby -asdf local ruby truffleruby -ruby --version -``` - ## Using TruffleRuby without a Ruby Manager If you are using a Ruby manager like `rvm`, `rbenv`, or `chruby` and wish not to add TruffleRuby to one of them, make sure that the manager does not set environment variables `GEM_HOME` and `GEM_PATH`. diff --git a/doc/user/standalone-distribution.md b/doc/user/standalone-distribution.md index d023b7dd8c08..6f84e661e7b6 100644 --- a/doc/user/standalone-distribution.md +++ b/doc/user/standalone-distribution.md @@ -6,92 +6,4 @@ permalink: /reference-manual/ruby/StandaloneDistribution/ --- # Standalone Distribution -For details regarding the three ways to install TruffleRuby, see [Getting Started](../../README.md#getting-started). -The recommended way is to install [GraalVM](installing-graalvm.md) as it provides the most flexibility. -However, you can also use what we call the standalone distribution of TruffleRuby, either via your Ruby manager/installer, or as a simple binary tarball. - -Releases of the standalone distribution are [available on GitHub](https://github.com/oracle/truffleruby/releases/latest). -Nightly builds are [also available](https://github.com/ruby/truffleruby-dev-builder/releases/latest). - -The standalone distributions are the files: -```bash -truffleruby-VERSION-linux-amd64.tar.gz -truffleruby-VERSION-macos-amd64.tar.gz -``` - -## Testing TruffleRuby in TravisCI - -TruffleRuby is now integrated in TravisCI. -Just add `truffleruby` in the build matrix, such as: - -```yaml -language: ruby -rvm: - - 2.6.1 - - truffleruby - - truffleruby-head -``` - -See [the TravisCI documentation](https://docs.travis-ci.com/user/languages/ruby#truffleruby) for details. -Please [report](https://github.com/oracle/truffleruby/issues) any issue you might find. - -## Testing TruffleRuby in GitHub Actions - -In GitHub Actions, you can easily setup TruffleRuby with [ruby/setup-ruby](https://github.com/ruby/setup-ruby): - -```yaml -name: My workflow -on: [push] -jobs: - test: - strategy: - fail-fast: false - matrix: - ruby: [ 2.6, truffleruby, truffleruby-head ] - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - uses: ruby/setup-ruby@v1 - with: - ruby-version: ${{ matrix.ruby }} - - run: ruby -v -``` - -See the [README](https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby) of that action for more documentation. - -## Testing TruffleRuby in CI - -If you use another continuous integration system, simply follow these instructions to run TruffleRuby in CI: download and extract the archive, add it to `PATH`, and run the post-install script. - -## Latest Release - -Set `TRUFFLERUBY_VERSION` to the latest TruffleRuby version from [GitHub releases](https://github.com/oracle/truffleruby/releases/latest). - -```bash -export TRUFFLERUBY_VERSION= -curl -L https://github.com/oracle/truffleruby/releases/download/vm-$TRUFFLERUBY_VERSION/truffleruby-$TRUFFLERUBY_VERSION-linux-amd64.tar.gz | tar xz -export PATH="$PWD/truffleruby-$TRUFFLERUBY_VERSION-linux-amd64/bin:$PATH" -$PWD/truffleruby-$TRUFFLERUBY_VERSION-linux-amd64/lib/truffle/post_install_hook.sh -ruby -v -``` - -## Latest Nightly Build - -Here are the instructions for manually installing the latest nightly build: - -```bash -curl -L https://github.com/ruby/truffleruby-dev-builder/releases/latest/download/truffleruby-head-ubuntu-18.04.tar.gz | tar xz -export PATH="$PWD/truffleruby-head/bin:$PATH" -$PWD/truffleruby-head/lib/truffle/post_install_hook.sh -ruby -v -``` - -## RubyGems Configuration - -Note that you also need to ensure `GEM_HOME` and `GEM_PATH` are not set, so TruffleRuby uses the correct `GEM_HOME` and `GEM_PATH`. -See [Using TruffleRuby without a Ruby manager](ruby-managers.md#using-truffleruby-without-a-ruby-manager) -for details. - -## Dependencies - -[TruffleRuby's dependencies](../../README.md#dependencies) need to be installed for TruffleRuby to run correctly. +This documentation has moved to [Installing TruffleRuby](installing-truffleruby.md). diff --git a/doc/user/testing-truffleruby-in-ci.md b/doc/user/testing-truffleruby-in-ci.md new file mode 100644 index 000000000000..91b9ab7c4317 --- /dev/null +++ b/doc/user/testing-truffleruby-in-ci.md @@ -0,0 +1,80 @@ +--- +layout: docs-experimental +toc_group: ruby +link_title: Testing TruffleRuby in CI +permalink: /reference-manual/ruby/TestingTruffleRubyInCI/ +--- +# Testing TruffleRuby in CI + +## Testing TruffleRuby in GitHub Actions + +In GitHub Actions, you can easily setup TruffleRuby with [ruby/setup-ruby](https://github.com/ruby/setup-ruby): + +```yaml +name: My workflow +on: [push] +jobs: + test: + strategy: + fail-fast: false + matrix: + ruby: [ 2.6, truffleruby, truffleruby-head ] + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + - run: ruby -v +``` + +See the [README](https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby) of that action for more documentation. + +## Testing TruffleRuby in TravisCI + +TruffleRuby is now integrated in TravisCI. +Just add `truffleruby` in the build matrix, such as: + +```yaml +language: ruby +rvm: + - 2.6.1 + - truffleruby + - truffleruby-head +``` + +See [the TravisCI documentation](https://docs.travis-ci.com/user/languages/ruby#truffleruby) for details. +Please [report](https://github.com/oracle/truffleruby/issues) any issue you might find. + +## Testing TruffleRuby in CI + +If you use another continuous integration system, simply follow these instructions to run TruffleRuby in CI: +download and extract the archive, add it to `PATH`, and run the post-install script. + +## Latest Release + +Set `TRUFFLERUBY_VERSION` to the latest TruffleRuby version from [GitHub releases](https://github.com/oracle/truffleruby/releases/latest). + +```bash +export TRUFFLERUBY_VERSION= +curl -L https://github.com/oracle/truffleruby/releases/download/graal-$TRUFFLERUBY_VERSION/truffleruby-$TRUFFLERUBY_VERSION-linux-amd64.tar.gz | tar xz +export PATH="$PWD/truffleruby-$TRUFFLERUBY_VERSION-linux-amd64/bin:$PATH" +$PWD/truffleruby-$TRUFFLERUBY_VERSION-linux-amd64/lib/truffle/post_install_hook.sh +ruby -v +``` + +## Latest Dev Build + +Here are the instructions for manually installing the latest dev build: + +```bash +curl -L https://github.com/ruby/truffleruby-dev-builder/releases/latest/download/truffleruby-head-ubuntu-18.04.tar.gz | tar xz +export PATH="$PWD/truffleruby-head/bin:$PATH" +$PWD/truffleruby-head/lib/truffle/post_install_hook.sh +ruby -v +``` + +## RubyGems Configuration + +Note that you also need to ensure `GEM_HOME` and `GEM_PATH` are not set, so TruffleRuby uses the correct `GEM_HOME` and `GEM_PATH`. +See [Using TruffleRuby without a Ruby manager](ruby-managers.md#using-truffleruby-without-a-ruby-manager) for details. diff --git a/doc/user/tools.md b/doc/user/tools.md index db49d1d6f9b4..d8a0b7f4c5fa 100644 --- a/doc/user/tools.md +++ b/doc/user/tools.md @@ -21,7 +21,7 @@ c.save('c.png') ## VisualVM -You need to use the `--jvm` runtime configuration and [install GraalVM](installing-graalvm.md) to use VisualVM. +Install VisualVM from [its website](https://visualvm.github.io/). VisualVM is a GUI with many tools: diff --git a/doc/user/truffleruby-additions.md b/doc/user/truffleruby-additions.md index 13767d6094c8..42b53418e2e6 100644 --- a/doc/user/truffleruby-additions.md +++ b/doc/user/truffleruby-additions.md @@ -22,9 +22,7 @@ In C code `TRUFFLERUBY` is defined. It is also possible to use feature-detection instead of looking at `RUBY_ENGINE`. -TruffleRuby is an integral part of GraalVM, so the version number of TruffleRuby is always the same as the version of GraalVM that contains it. -If you are using TruffleRuby outside of GraalVM, such as a standard JVM, the version will be `'0.0'`. -You can find the version number of GraalVM and TruffleRuby using the standard `RUBY_ENGINE_VERSION` constant. +You can find the version number of TruffleRuby using the standard `RUBY_ENGINE_VERSION` constant. ## TruffleRuby Methods and Classes @@ -40,7 +38,7 @@ TruffleRuby provides these non-standard methods and classes that provide additio * `TruffleRuby.full_memory_barrier` ensures lack of reordering of loads or stores before the barrier with loads or stores after the barrier. -* `TruffleRuby.graalvm_home` returns the GraalVM home or `nil` if running outside of GraalVM (e.g., TruffleRuby standalone). +* `TruffleRuby.graalvm_home` returns the GraalVM home or `nil` if running outside of GraalVM (e.g., Native standalone). * `TruffleRuby.synchronized(object) { }` will run the block while holding an implicit lock per object instance.