- GraalVM for JDK 22 (Latest)
- GraalVM for JDK 23 (Early Access)
- GraalVM for JDK 21
- GraalVM for JDK 17
- Archives
- Dev Build
- Java on Truffle
- JavaScript and Node.js Reference
- LLVM Languages Reference
- Python Reference
- Ruby Reference
- Compatibility
- Debugging Ruby
- Runtime Configurations
- Using Ruby with GraalVM
- Installing `libssl`
- Installing LibYAML
- Installing Make and GCC
- Installing `zlib`
- Migration from JRuby to Ruby
- TruffleRuby Options and Command Line
- Polyglot Programming
- Ruby Managers and Installers
- Standalone Distribution
- Development Tools for Ruby
- Ruby Additional Functionality
- Setting up a UTF-8 Locale
- Reporting Performance Problems
- Security
- Optcarrot Example
- FAQ
- GraalVM R Runtime
- GraalWasm
TruffleRuby
TruffleRuby is the GraalVM high-performance implementation of the Ruby programming language.
Getting Started #
TruffleRuby comes in two distributions:
- Native Standalone: This only contains TruffleRuby in the Native configuration.
- JVM Standalone: This only contains TruffleRuby in the JVM configuration. This includes support for other languages such as Java, JavaScript, Python and WebAssembly.
You can install either of those:
- Via your Ruby manager/installer (RVM, rbenv, chruby, asdf, ruby-build, ruby-install).
We recommend trying TruffleRuby dev builds which contain the latest fixes and improvements (replaceVERSION
bydev
).
Native Standalone:
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
JVM Standalone:
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 for more details and other CIs.
- uses: ruby/setup-ruby@v1
with:
ruby-version: truffleruby # or truffleruby-head or truffleruby+graalvm or truffleruby+graalvm-head
-
Via Docker. For Native Standalone see official release images and nightly images. For JVM Standalone there are no Docker images yet, but you can easily download it and take inspiration from the Native Standalone Dockerfiles.
-
Manually, by following the documentation.
You can use gem
and bundle
to install gems, as usual.
Please report any issues you might find on GitHub.
Aim #
TruffleRuby aims to:
- Run idiomatic Ruby code faster.
- TruffleRuby is the fastest Ruby implementation for many CPU-intensive benchmarks.
- Run Ruby code in parallel.
- 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 WebAssembly.
- Provided by GraalVM, see the Polyglot documentation.
- Provide new tooling, such as debuggers and monitoring, that works across languages.
- Includes a profiler, debugger, VisualVM, and more. See the Tools documentation.
- Provide all of the above while maintaining very high compatibility with the standard implementation of Ruby.
TruffleRuby Runtime Configurations #
There are two main runtime configurations of TruffleRuby, Native and JVM, which have different trade-offs.
Configuration: | Native (--native , default) |
JVM (--jvm ) |
---|---|---|
Time to start TruffleRuby | about as fast as MRI startup | slower |
Time to reach peak performance | faster | slower |
Peak performance (also considering GC) | good | best |
Java host interoperability | needs reflection configuration | just works |
To find out which runtime configuration is being used, run ruby --version
on the command line,
or check the value of RUBY_DESCRIPTION
or TruffleRuby.native?
in Ruby code.
Runtime configurations are further detailed in Deploying TruffleRuby.
System Compatibility #
TruffleRuby is actively tested on the following systems:
- Oracle Linux 7, 8, 9
- Ubuntu 18.04, 20.04, 22.04 (all LTS)
- Fedora 37, 38
- Debian 10, 11, 12
- macOS 11 (Big Sur)
Architectures:
- AMD64 (aka
x86_64
): Supported - AArch64 (aka
arm64
): Supported on Linux (from 21.2) and on macOS (from 22.2)
You may find that TruffleRuby will not work if you severely restrict the
environment, for example, by unmounting system filesystems such as /dev/shm
.
Dependencies #
- make, gcc and g++ for building C and C++ extensions
- libssl for the
openssl
C extension - libyaml for the
psych
C extension - zlib for the
zlib
C extension
Without these dependencies, many libraries including RubyGems will not work. TruffleRuby will try to print a nice error message if a dependency is missing, but this can only be done on a best effort basis.
You also need to set up a UTF-8 locale if not already done.
See the contributor workflow document if you wish to build TruffleRuby from source.
Current Status #
We recommend that people trying TruffleRuby on their gems and applications get in touch with us for any help they might need.
TruffleRuby runs Rails and is compatible with many gems, including C extensions. TruffleRuby is not 100% compatible with MRI 3.2 yet. Please report any compatibility issues you might find. TruffleRuby passes around 97% of ruby/spec, more than any other alternative Ruby implementation.
Regarding performance, TruffleRuby is by far
the fastest Ruby implementation on the yjit-bench benchmark suite which includes railsbench
, etc.
To achieve this performance TruffleRuby needs a fair amount of warmup, as other advanced JIT compilers do.
If you find any performance issue, please see this guide.
Releases #
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 and the upcoming releases list for the release dates and information about how long releases are supported. GraalVM Community Edition releases are supported at most one year. Longer support is available for Oracle GraalVM.
Migration from MRI #
TruffleRuby should in most cases work as a drop-in replacement for MRI, but you should read about our compatibility.
Migration from JRuby #
For many use cases TruffleRuby should work as a drop-in replacement for JRuby. However, our approach to integration with Java is different to JRuby so you should read our migration guide.
Contact #
The best way to get in touch with us is to join the #truffleruby
channel on
GraalVM Slack.
You can also Tweet to @TruffleRuby, or email
benoit.daloze@oracle.com.
Please report security vulnerabilities via the process outlined in the reporting vulnerabilities guide, rather than by something public such as a GitHub issue or a Gitter conversation.
Mailing List #
Announcements about GraalVM, including TruffleRuby, are made on the graal-dev mailing list.
Authors #
The main authors of TruffleRuby ordered by first contribution are: Chris Seaton, Benoit Daloze, Kevin Menard, Petr Chalupa, Brandon Fish, Duncan MacGregor, Christian Wirth, Rafael França, Alan Wu, Nicolas Laurent, Carol Chen, Nikolay Sverchkov, Lillian Zhang, Tom Stuart, and Maple Ong.
Security #
See SECURITY for how to report security vulnerabilities to Oracle. For known vulnerabilities in Ruby, please refer to the known-cves file.
Licence #
TruffleRuby is copyright (c) 2013-2024 Oracle and/or its affiliates, and is made available to you under the terms of any one of the following three licenses:
- Eclipse Public License version 2.0, or
- GNU General Public License version 2, or
- GNU Lesser General Public License version 2.1.
For further licensing information, see LICENCE, 3rd_party_licenses, and doc/legal/legal.
Attribution #
TruffleRuby includes infrastructure code from JRuby (e.g. parser, JCodings, Joni), core library code from the Rubinius project, as well as code from the standard implementation of Ruby, MRI.