Ruby Rules® for Bazel

Table of Contents

• 1. Build Status & Activity
• 2. Rules Development Status
• 3. Table of Contents
• 4. Usage
  • 4.1. WORKSPACE File
    • 4.1.1. Load dependencies, select Ruby SDK and define one or more Bundles
  • 4.2. BUILD.bazel file(s)
    • 4.2.1. Define Ruby Executable, Library and an RSpec
    • 4.2.2. Package Ruby files as a Gem
  • 4.3. Tool Specific Setup
    • 4.3.1. ASDF
  • 4.4. Rule Dependency Diagram
• 5. Rules
  • 5.1. ruby_library
  • 5.2. ruby_binary
  • 5.3. ruby_test
  • 5.4. ruby_bundle
    • 5.4.1. Conventions
    • 5.4.2. WORKSPACE:
      • Vendor directory handling
    • 5.4.3. BUILD.bazel:
  • 5.5. ruby_rspec
  • 5.6. ruby_gem
• 6. Potential Future Features
• 7. Contributing
  • 7.1. Setup
    • 7.1.1. Using the Script
    • 7.1.2. OS-Specific Setup
  • 7.2. Verifying Your Environment
    • 7.2.1. Issues During Setup
  • 7.3. Developing Rules
  • 7.4. Running Tests
    • 7.4.1. Test Script
  • 7.5. Linter
  • 7.6. Regenerating README.pdf & Changelog
• 8. Copyright

This repo is primarily maintained by Konstantin Gredeskoul and Yuki "Yugui" Sonoda. We are both very busy and would really love more contributors to join the core team. If you are interested in developing Ruby Rules for Bazel, please submit a couple of PRs and then lets talk!

Tip	You can read or print this README in a proper PDF format by grabbing our README.pdf.

1. Build Status & Activity

CI Status	Activity & Documentation

2. Rules Development Status

Readiness	Types of Applications
	ruby apps, ruby gems, micro-services, ideally in a mono-repo
	medium-sized Ruby on Rails apps, ideally in a mono-repo
	complex Ruby on Rails monoliths, single-repo

Note	we have a short guide on Building your first Ruby Project on the Wiki. We encourage you to check it out.

3. Table of Contents

• Ruby Rules® for Bazel Build System

  • Build Status & Activity

  • Rules Development Status

  • Table of Contents

  • Usage

    • WORKSPACE File

    • BUILD.bazel file(s) * Tool Specific Setup * Rule Dependency Diagram

  • Rules

    • ruby_library

    • ruby_binary

    • ruby_test

    • ruby_bundle

    • ruby_rspec

    • ruby_gem

  • Potential Future Features

  • Contributing

    • Setup

    • Verifying Your Environment

    • Developing Rules

    • Running Tests

    • Linter

    • Regenerating README.pdf & Changelog

  • Copyright

4. Usage

4.1. WORKSPACE File

4.1.1. Load dependencies, select Ruby SDK and define one or more Bundles

workspace(name = "my_ruby_project")

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")

#———————————————————————————————————————————————————————————————————————
# To get the latest ruby rules, grab the 'master' branch.
#———————————————————————————————————————————————————————————————————————

git_repository(
    name = "rules_ruby",
    remote = "https://github.com/bazelruby/rules_ruby.git",
    branch = "master"
)

load("@rules_ruby//ruby:deps.bzl", "rules_ruby_dependencies")
rules_ruby_dependencies()

#———————————————————————————————————————————————————————————————————————
# Specify Ruby version — this will either build Ruby or use a local
# RBENV installation if the Ruby version matches.
#———————————————————————————————————————————————————————————————————————

load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
bazel_skylib_workspace()

load("@rules_ruby//ruby:deps.bzl", "register_toolchain")
register_toolchains("ruby-3.0")

#———————————————————————————————————————————————————————————————————————
# Now, load the ruby_bundle rule & install gems specified in the Gemfile
#———————————————————————————————————————————————————————————————————————

load("@ruby-3.0//:bundle.bzl", "ruby_bundle")

ruby_bundle(
    name = "bundle",
    # Specify additional paths to be loaded from the gems at runtime, if any.
    # Since spec.require_paths in Gem specifications are auto-included, directory paths
    # in spec.require_paths do not need to be listed in includes hash.
    includes = {
        "grpc": ["etc"],
    },
    excludes = {
        "mini_portile": ["test/**/*"],
    },
    gemfile = "//:Gemfile",
    gemfile_lock = "//:Gemfile.lock",
)

# You can specify more than one bundle in the WORKSPACE file
ruby_bundle(
    name = "bundle_app_shopping",
    gemfile = "//:apps/shopping/Gemfile",
    gemfile_lock = "//:apps/shopping/Gemfile.lock",
)

# You can also install from Gemfile using `gemspec`.
ruby_bundle(
    name = "bundle_gemspec",
    srcs = ["//:lib/my_gem/my_gem.gemspec"],
    gemfile = "//:lib/my_gem/Gemfile",
    gemfile_lock = "//:lib/my_gem/Gemfile.lock",
)

4.2. BUILD.bazel file(s)

Any of the project BUILD files can now reference any gems included in the Gemfile referenced by the ruby_bundle rule, and defined in the project’s WORKSPACE file.

4.2.1. Define Ruby Executable, Library and an RSpec

Add ruby_library, ruby_binary, ruby_rspec or ruby_test into your BUILD.bazel files.

#———————————————————————————————————————————————————————————————————————
# Define Ruby executable, test, spec and package a gem
#———————————————————————————————————————————————————————————————————————

load(
    "@rules_ruby//ruby:defs.bzl",
    "ruby_binary",
    "ruby_library",
    "ruby_test",
    "ruby_rspec",
)

ruby_library(
    name = "foo",
    srcs = glob(["lib/**/*.rb"]),
    includes = ["lib"],
    deps = [
      "@bundle//:activesupport",
      "@bundle//:awesome_print",
      "@bundle//:rubocop",
    ]
)

ruby_binary(
    name = "bar",
    srcs = ["bin/bar"],
    deps = [":foo"],
)

ruby_test(
    name = "foo-test",
    srcs = ["test/foo_test.rb"],
    deps = [":foo"],
)

ruby_rspec(
    name = "foo-spec",
    specs = glob(["spec/**/*.rb"]),
    rspec_args = { "--format": "progress" },
    deps = [":foo"]
}

4.2.2. Package Ruby files as a Gem

Use ruby_gem rule to package any number of ruby files or folders into a Ruby-Gem compatible ZIP archive.

load(
    "@rules_ruby//ruby:defs.bzl",
    "ruby_gem",
)

ruby_gem(
    name            = "awesome-sauce-gem", # name of the build target
    gem_name        = "awesome-sauce",     # name of the gem
    gem_version     = "0.1.0",
    gem_summary     = "Example gem to demonstrate Bazel Gem packaging",
    gem_description = "Example gem to demonstrate Bazel Gem packaging",
    gem_homepage    = "https://github.com/bazelruby/rules_ruby",
    gem_authors     = [
        "BazelRuby",
        "Konstantin Gredeskoul"
    ],
    gem_author_emails = [
        "bazelruby@googlegroups.com",
    ],
    gem_runtime_dependencies = {
        "colored2": "~> 3.1.2",
        "hashie": "",
    },
    gem_development_dependencies = {
        "rspec": "",
        "rspec-its": "",
        "rubocop": "",
    },
    srcs = [
        glob("{bin,exe,lib,spec}/**/*.rb")
    ],
    deps = [
        "//lib:example_gem",
    ],
)

4.3. Tool Specific Setup

4.3.1. ASDF

If you are using ASDF to manage your ruby installs, you can use them by adding .bazelrc:

build --test_env=ASDF_DIR --test_env=ASDF_DATA_DIR
build --action_env=ASDF_DIR --test_env=ASDF_DATA_DIR

You will have to be sure to export the ASDF_DATA_DIR in your profile since it’s not set by default. e.g. export ASDF_DATA_DIR="$HOME/.asdf"

4.4. Rule Dependency Diagram

Note	this diagram is somewhat outdated.

The following diagram attempts to capture the implementation behind ruby_library that depends on the result of bundle install, and a ruby_binary that depends on both:

5. Rules

5.1. ruby_library

ruby_library(
    name,
    deps,
    srcs,
    data,
    compatible_with,
    deprecation,
    distribs,
    features,
    licenses,
    restricted_to,
    tags,
    testonly,
    toolchains,
    visibility)

Attributes
name	Name, required A unique name for this rule.
srcs	List of Labels, optional List of .rb files. At least srcs or deps must be present
deps	List of labels, optional List of targets that are required by the srcs Ruby files. At least srcs or deps must be present
includes	List of strings, optional List of paths to be added to $LOAD_PATH at runtime. The paths must be relative to the the workspace which this rule belongs to.
rubyopt	List of strings, optional List of options to be passed to the Ruby interpreter at runtime. Note -I option should usually go to includes attribute.
And other common attributes.

5.2. ruby_binary

ruby_binary(
    name,
    deps,
    srcs,
    data,
    main,
    compatible_with,
    deprecation,
    distribs,
    features,
    licenses,
    restricted_to,
    tags,
    testonly,
    toolchains,
    visibility,
    args,
    output_licenses
)

Attributes
name	Name, required A unique name for this rule.
srcs	List of Labels, required List of .rb files.
deps	List of labels, optional List of targets that are required by the srcs Ruby files.
main	Label, optional The entrypoint file. It must be also in srcs. If not specified, $(NAME).rb where $(NAME) is the name of this rule.
includes	List of strings, optional List of paths to be added to $LOAD_PATH at runtime. The paths must be relative to the the workspace which this rule belongs to.
rubyopt	List of strings, optional List of options to be passed to the Ruby interpreter at runtime. Note -I option should usually go to includes attribute.
And other common attributes.

5.3. ruby_test

ruby_test(
    name,
    deps,
    srcs,
    data,
    main,
    compatible_with,
    deprecation,
    distribs,
    features,
    licenses,
    restricted_to,
    tags,
    testonly,
    toolchains,
    visibility,
    args,
    size,
    timeout,
    flaky,
    local,
    shard_count
)

Attributes
name	Name, required A unique name for this rule.
srcs	List of Labels, required List of .rb files.
deps	List of labels, optional List of targets that are required by the srcs Ruby files.
main	Label, optional The entrypoint file. It must be also in srcs. If not specified, $(NAME).rb where $(NAME) is the name of this rule.
includes	List of strings, optional List of paths to be added to $LOAD_PATH at runtime. The paths must be relative to the the workspace which this rule belongs to.
rubyopt	List of strings, optional List of options to be passed to the Ruby interpreter at runtime. Note -I option should usually go to includes attribute.
And other common attributes.

5.4. ruby_bundle

NOTE: This is a repository rule, and can only be used in a WORKSPACE file.

This rule installs gems defined in a Gemfile using Bundler, and exports individual gems from the bundle, as well as the entire bundle, available as a ruby_library that can be depended upon from other targets.

ruby_bundle(
    name,
    gemfile,
    gemfile_lock,
    bundler_version = "2.1.4",
    includes = {},
    excludes = {},
    srcs = [],
    vendor_cache = False,
    ruby_interpreter = "@rules_ruby//ruby/runtime:interpreter",
)

Attributes
name	Name, required A unique name for this rule.
gemfile	Label, required The Gemfile which Bundler runs with.
gemfile_lock	Label, optional The Gemfile.lock which Bundler runs with. Note This rule never updates the Gemfile.lock. It is your responsibility to generate/update Gemfile.lock
srcs	List of Labels, optional List of additional files required for Bundler to install gems. This could usually include *.gemspec files.
vendor_cache	Bool, optional Symlink the vendor directory into the Bazel build space, this allows Bundler to access vendored Gems
bundler_version	String, optional The Version of Bundler to use. Defaults to 2.1.4. Note This rule never updates the Gemfile.lock. It is your responsibility to generate/update Gemfile.lock
includes	Dictionary of key-value-pairs (key: string, value: list of strings), optional List of glob patterns per gem to be additionally loaded from the library. Keys are the names of the gems which require some file/directory paths not listed in the require_paths attribute of the gemspecs to be also added to $LOAD_PATH at runtime. Values are lists of blob path patterns, which are relative to the root directories of the gems.
excludes	Dictionary of key-value-pairs (key: string, value: list of strings), optional List of glob patterns per gem to be excluded from the library. Keys are the names of the gems. Values are lists of blob path patterns, which are relative to the root directories of the gems. The default value is ["/* .", "/* /"]
And other common attributes.

5.4.1. Conventions

ruby_bundle creates several targets that can be used downstream. In the examples below we assume that your ruby_bundle has a name app_bundle:

• @app_bundle//:bundler — references just the Bundler from the bundle.

• @app_bundle//:gems — references all gems in the bundle (i.e. "the entire bundle").

• @app_bundle//:gem-name — references just the specified gem in the bundle, eg. @app_bundle//:awesome_print.

• @app_bundle//:bin — references to all installed executables from this bundle, with individual executables accessible via eg. @app_bundle//:bin/rubocop

5.4.2. WORKSPACE:

load("@ruby-3.0//:bundle.bzl", "ruby_bundle")

ruby_bundle(
    name = "gems",
    bundler_version = '2.1.4',
    gemfile = "//:Gemfile",
    gemfile_lock = "//:Gemfile.lock",
)

Vendor directory handling

To use the vendor cache, you have to declare a managed_directory in your workspace. The name should match the name of the bundle.

load("@ruby-3.0//:bundle.bzl", "ruby_bundle")

workspace(
    name = "my_wksp",
    managed_directories = {"@bundle": ["vendor"]},
)

ruby_bundle(
    name = "bundle",
    bundler_version = "2.1.2",
    vendor_cache = True,
    gemfile = "//:Gemfile",
    gemfile_lock = "//:Gemfile.lock",
)

5.4.3. BUILD.bazel:

# Reference the entire bundle with :gems

ruby_library(
    name = "foo",
    srcs = ["foo.rb"],
    deps = ["@gems//:gems"],
)

# Or, reference specific gems from the bundle like so:

ruby_binary(
    name = "rubocop",
    srcs = [":foo", ".rubocop.yml"],
    args = ["-P", "-D", "-c" ".rubocop.yml"],
    main = "@gems//:bin/rubocop",
    deps = ["@gems//:rubocop"],
)

5.5. ruby_rspec

ruby_rspec(
    name,
    deps,
    srcs,
    data,
    main,
    rspec_args,
    bundle,
    compatible_with,
    deprecation,
    distribs,
    features,
    licenses,
    restricted_to,
    tags,
    testonly,
    toolchains,
    visibility,
    args,
    size,
    timeout,
    flaky,
    local,
    shard_count
)

Attributes
name	Name, required A unique name for this rule.
srcs	List of Labels, required List of .rb files.
deps	List of labels, optional List of targets that are required by the srcs Ruby files.
main	Label, optional The entrypoint file. It must be also in srcs. If not specified, $(NAME).rb where $(NAME) is the name of this rule.
rspec_args	List of strings, optional Command line arguments to the rspec binary, eg ["--progress", "-p2", "-b"] If not specified, the default arguments defined in constants.bzl are used: --format=documentation --force-color.
includes	List of strings, optional List of paths to be added to $LOAD_PATH at runtime. The paths must be relative to the the workspace which this rule belongs to.
rubyopt	List of strings, optional List of options to be passed to the Ruby interpreter at runtime. Note -I option should usually go to includes attribute.
And other common attributes.

5.6. ruby_gem

Used to generate a zipped gem containing its srcs, dependencies and a gemspec.

ruby_gem(
    name,
    gem_name,
    gem_version,
    gem_summary,
    gem_description,
    gem_homepage,
    gem_authors,
    gem_author_emails,
    gem_runtime_dependencies,
    gem_development_dependencies,
    require_paths = ["lib"],
    srcs = srcs,
    deps = deps,
    data = data
)

Attributes
name	Name, required A unique name for this build target.
gem_name	Name of the gem, required The name of the gem to be generated.
gem_version	String, optional The version of the gem. Is used to name the output file, which becomes name-version.zip, and also included in the Gemspec.
gem_summary	String, optional One line summary of the gem purpose.
gem_description	String, required Single-line, paragraph-sized description text for the gem.
gem_homepage	String, optional Homepage URL of the gem.
gem_authors	List of Strings, required List of human readable names of the gem authors. Required to generate a valid gemspec.
gem_author_emails	List of Strings, optional List of email addresses of the authors.
srcs	List of Labels, optional List of .rb files. At least srcs or deps must be present
deps	List of labels, optional List of targets that are required by the srcs Ruby files. At least srcs or deps must be present
require_paths	List of Strings, optional List of paths to be added to the Ruby LOAD_PATH when using this gem. Typically this value is just lib (which is also the default).
gem_runtime_dependencies	String Dictionary, optional This is a dictionary where keys are gem names, and values are either an empty string or a gem version specification. For instance, the pessimistic version specifier ~> 3.0 means that all versions up to 4.0 are accepted.
gem_development_dependencies	String Dictionary, optional Similar to the above, this specifies gems necessary for the development of the above gem, such as testing gems, linters, code coverage and more.
And other common attributes.

6. Potential Future Features

[check square] Using various versions of Ruby installed locally

[square] Building native extensions in gems with Bazel

[square] Releasing your gems with Bazel (Coinbase fork might have this feature, worth checking)

7. Contributing

We welcome contributions to RulesRuby. Please make yourself familiar with the code of conduct, which basically says — don’t be an a-hole.

You may notice that there is more than one Bazel WORKSPACE inside this repo. There is one in examples/simple_script for instance, because we use this example to validate and test the rules. So be mindful whether your current directory contains WORKSPACE file or not.

7.1. Setup

7.1.1. Using the Script

You will need Homebrew installed prior to running the script.

After that, cd into the top level folder and run the setup script in your Terminal:

❯ bin/setup

This runs a complete setup, shouldn’t take too long. You can explore various script options with the help command:

❯ bin/setup -h

USAGE
  # without any arguments runs a complete setup.
  bin/setup

  # alternatively, a sub-setup function name can be passed:
  bin/setup [ gems | git-hook | help | main | os-specific | rbenv | remove-git-hook ]

DESCRIPTION:
  Runs full setup without any arguments.

  Accepts one optional argument — one of the actions that typically run
  as part of setup, with one exception — remove-git-hook.
  This action removes the git commit hook installed by the setup.

EXAMPLES:
    bin/setup

  Or, to run only one of the sub-functions (actions), pass
  it as an argument:

    bin/setup help
    bin/setup remove-git-hook

7.1.2. OS-Specific Setup

Note that the setup contains os-specific section. This is because there are two extension scripts:

• bin/setup-linux

• bin/setup-darwin

Those will install Bazel and everything else you need on either platform. In fact, we use the linux version on CI.

7.2. Verifying Your Environment

We provided a handy script bin/show-env to display where your dependencies are coming from. Here is an example of running it on a Mac OS-X system:

❯ bin/show-env

7.2.1. Issues During Setup

Please report any errors to bin/setup as Issues on Github. You can assign them to @kigster. If I am not responding fast enough, and you are in a hurry, please email kigster AT gmail directly.

7.3. Developing Rules

Besides making yourself familiar with the existing code, and Bazel documentation on writing rules, you might want to follow this order:

1. Setup dev tools as described in the setup section.

2. hack, hack, hack…​

3. Make sure all tests pass — you can run a single command for that (but see more on it below.

bin/test-suite

OR, you can run individual Bazel test commands from the inside.

• bazel test //…​

• cd examples/simple_script && bazel test //…​

  1. Open a pull request in Github, and please be as verbose as possible in your description.

In general, it’s always a good idea to ask questions first — you can do so by creating an issue.

7.4. Running Tests

After running setup, and since this is a bazel repo you can use Bazel commands:

bazel build //...:all
bazel query //...:all
bazel test  //...:all

But to run tests inside each sub-WORKSPACE, you will need to repeat that in each sub-folder. Luckily, there is a better way.

7.4.1. Test Script

This script runs all tests (including sub-workspaces) when ran without arguments:

bin/test-suite

Run it with help command to see other options, and to see what parts you can run individually. At the moment they are:

# alternatively, a partial test name can be passed:
bin/test-suite [ all | bazel-info | buildifier | help | rspec | rubocop | simple-script |  workspace ]

On a MacBook Pro it takes about 3 minutes to run.

7.5. Linter

We are using RuboCop for ruby and Buildifier for Bazel. Both are represented by a single script bin/linter, which just like the scripts above runs ALL linters when ran without arguments, accepts help commnd, and can be run on a subset of linting strategies:

bin/linter

The following are the partial linting functions you can run:

# alternatively, a partial linter name can be passed:
bin/linter [ all | buildifier | help | rubocop ]

7.6. Regenerating README.pdf & Changelog

To regenerate, first you may need to grab an API token and export the GITHUB_TOKEN variable:

export GITHUB_TOKEN=....

Then use the make target:

make update

Or, manually:

gem install github_changelog_generator
github_changelog_generator -u bazelruby -p rules_ruby -t your-github-token

8. Copyright

© 2018-2021 BazelRuby Contributors.

Core Team:

• Yuki Yugui Sonoda

• Konstantin Gredeskoul

Core Team (Emeritus):

• Graham Jenson

Licensed under the Apache License, Version 2.0 (the "License").

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.