Usage
- WORKSPACE File
- BUILD.bazel files
Rules
- rb_library
- rb_binary
- rb_test
- rb_bundle
- rb_gem
What's coming next
Contributing
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

Building native extensions in gems with Bazel
Using a specified version of Ruby.
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:

Setup dev tools as described in the setup section.
hack, hack, hack...
Make sure all tests pass — you can run individual Bazel test commands from the inside.

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

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

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.

p0deje/coinbase_rules_ruby