This repository hosts Ruby language ruleset for Bazel.

The ruleset is known to work with:

• Bazel 7 using WORKSPACE and Bzlmod (tested on CI);
• Bazel 6 using WORKSPACE and Bzlmod (not tested on CI);
• Bazel 5 using WORKSPACE (no longer tested on CI).

1. Install the ruleset following WORKSPACE instructions on the latest release.
2. Download and install Ruby:

# WORKSPACE
load("@rules_ruby//ruby:deps.bzl", "rb_register_toolchains")

rb_register_toolchains(
    version = "3.0.6",
    # alternatively, load version from .ruby-version file
    # version_file = "//:.ruby-version",
)

3. (Optional) Download and install Bundler dependencies:

# WORKSPACE
load("@rules_ruby//ruby:deps.bzl", "rb_bundle_fetch")

rb_bundle_fetch(
    name = "bundle",
    gemfile = "//:Gemfile",
    gemfile_lock = "//:Gemfile.lock",
)

4. Start defining your library, binary and test targets in BUILD files.

1. Install ruleset following Bzlmod instructions on the latest release.
2. Download and install Ruby:

# MODULE.bazel
ruby = use_extension("@rules_ruby//ruby:extensions.bzl", "ruby")
ruby.toolchain(
    name = "ruby",
    version = "3.0.6",
    # alternatively, load version from .ruby-version file
    # version_file = "//:.ruby-version",
)
use_repo(ruby, "ruby")

3. (Optional) Download and install Bundler dependencies:

# MODULE.bazel
ruby.bundle_fetch(
    name = "bundle",
    gemfile = "//:Gemfile",
    gemfile_lock = "//:Gemfile.lock",
)
use_repo(ruby, "bundle", "ruby_toolchains")

4. Register Ruby toolchains:

# MODULE.bazel
register_toolchains("@ruby_toolchains//:all")

4. Start defining your library, binary and test targets in BUILD files.

• See repository rules for the documentation of WORKSPACE rules.
• See rules for the documentation of BUILD rules.

See examples directory for a comprehensive set of examples how to use the ruleset.

The following toolchains are known to work and tested on CI.

The following toolchains were previously known to work but no longer tested on CI.

On Linux and macOS, ruby-build is used to install MRI from sources. Keep in mind, that it takes some time for compilation to complete.

On Windows, RubyInstaller is used to install MRI.

On all operating systems, JRuby is downloaded manually. It uses Bazel runtime Java toolchain as JDK. JRuby is currently the only toolchain that supports Remote Build Execution.

On Linux and macOS, ruby-build is used to install TruffleRuby. Windows is not supported.

On Linux and macOS, you can potentially use any Ruby distribution that is supported by ruby-build. However, some are known not to work or work only partially (e.g. mRuby has no bundler support).

• JRuby/TruffleRuby might need HOME variable exposed. See examples/gem/.bazelrc to learn how to do that. This is to be fixed in jruby/jruby#5661 and oracle/truffleruby#2784.
• JRuby might fail with Errno::EACCES: Permission denied - NUL error on Windows. You need to configure JDK to allow proper access. This is described in jruby/jruby#7182.
• RuboCop < 1.55 crashes with LoadError on Windows. This is fixed in rubocop/rubocop#12062.
• REPL doesn't work when used with bazel test. To work it around, use a debugger with remote client support such as ruby/debug . See examples/gem/.bazelrc to learn how to do that.