isabella232 / rules_ruby

Bazel Ruby Rules

• Usage
  • WORKSPACE File
  • BUILD.bazel files
• Rules
  • rb_library
  • rb_binary
  • rb_test
  • rb_bundle
  • rb_gem
• What's coming next
• Contributing
  • Setup
    • OSX Setup Script
      • Issues During Setup
  • Developing Rules
  • Running Tests
  • Linter
• Copyright

Build Status

Build	Status
CircleCI Master:

Rules Ruby

Ruby rules for Bazel.

** Current Status:** Work in progress.

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

Usage

WORKSPACE File

Add rules_ruby_dependencies and ruby_register_toolchains into your WORKSPACE file.

# To get the latest, grab the 'master' branch.

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

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

rules_ruby_dependencies()

ruby_register_toolchains()

Next, add any external Gem dependencies you may have via rb_bundle command. The name of the bundle becomes a reference to this particular Gemfile.lock.

Install external gems that can be later referenced as @<bundle-name>//:<gem-name>, and the executables from each gem can be accessed as @<bundle-name//:bin/<gem-binary-name> for instance, @bundle//:bin/rubocop.

You can install more than one bundle per WORKSPACE, but that's not recommended.

rb_bundle(
  name = "bundle",
  gemfile = ":Gemfile",
  gemfile_lock = ":Gemfile.lock",
  bundler_version = "2.1.2",
  full_index = True,
)

rb_bundle(
  name = "bundle_app_shopping",
  gemfile = "//apps/shopping:Gemfile",
  gemfile_lock = "//apps/shopping:Gemfile.lock",
  bundler_version = "2.1.2",
  full_index = True,
)

BUILD.bazel files

Add rb_library, rb_binary or rb_test into your BUILD.bazel files.

load(
    "@coinbase_rules_ruby//ruby:defs.bzl",
    "rb_binary",
    "rb_library",
    "rb_test",
    "rb_rspec",
)

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

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

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

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

Rules

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

rb_library

rb_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

rb_binary

rb_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

rb_test

rb_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

rb_bundle

Installs gems with Bundler, and make them available as a rb_library.

Example: WORKSPACE:

git_repository(
    name = "coinbase_rules_ruby",
    remote = "https://github.com/coinbase/rules_ruby.git",
    tag = "v0.1.0",
)

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

rules_ruby_dependencies()

ruby_register_toolchains()

load("@coinbase_rules_ruby//ruby:defs.bzl", "rb_bundle")

rb_bundle(
    name = "gems",
    gemfile = "//:Gemfile",
    gemfile_lock = "//:Gemfile.lock",
)

Example: lib/BUILD.bazel:

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

Or declare many gems in your Gemfile, and only use some of them in each ruby library:

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

rb_bundle(name, gemfile, gemfile_lock, bundler_version = "2.1.2")

Attributes
name	Name, required A unique name for this rule.
gemfile	Label, required The Gemfile which Bundler runs with.
gemfile_lock	Label, required The Gemfile.lock which Bundler runs with. NOTE: This rule never updates the Gemfile.lock. It is your responsibility to generate/update Gemfile.lock
bundler_version	String, optional The Version of Bundler to use. Defaults to 2.1.2. NOTE: This rule never updates the Gemfile.lock. It is your responsibility to generate/update Gemfile.lock
full_index	Bool, optional Set to True to add the --full-index option to the bundle install. Can improve performance.

rb_gem

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

rb_gem(name, gem_name, version, srcs, authors, deps, data, includes)

Attributes
name	Name, required A unique name for this rule.
gem_name	Name of the gem, required The name of the gem to be generated.
version	Label, required The version of the gem. Is used to name the output file, which becomes name-version.zip, and also included in the Gemspec.
authors	List of Strings, required List of human readable names of the gem authors. Required to generate a valid gemspec.
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

What's coming next

1. Building native extensions in gems with Bazel
2. Using a specified version of Ruby.
3. Releasing your gems with Bazel

Contributing

We welcome contributions to RulesRuby.

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.

Setup

OSX Setup 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-darwin

Issues During Setup

Please report any errors as Issues on Github.

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 individual Bazel test commands from the inside.

• bazel test //...
• cd examples/simple_script && bazel test //...

4. 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.

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.

Linter

We are using RuboCop for ruby and Buildifier for Bazel. Both can be run using bazel:

bazel run //:buildifier

Copyright

© 2018-2019 Yuki Yugui Sonoda & BazelRuby Authors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

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.