Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.aspect.build/llms.txt

Use this file to discover all available pages before exploring further.

Documentation for @rules_ruby@v0.23.1 — View source
Public API for rules

​
Rule: rb_binary

Runs a Ruby binary. Suppose you have the following Ruby gem, where rb_library() is used in BUILD files to define the packages for the gem. 
|-- BUILD
|-- Gemfile
|-- WORKSPACE
|-- gem.gemspec
`-- lib
    |-- BUILD
    |-- gem
    |   |-- BUILD
    |   |-- add.rb
    |   |-- subtract.rb
    |   `-- version.rb
    `-- gem.rb
One of the files can be run as a Ruby script: lib/gem/version.rb: 
module GEM
  VERSION = '0.1.0'
end

puts "Version is: #{GEM::VERSION}" if __FILE__ == $PROGRAM_NAME
You can run this script by defining a target: lib/gem/BUILD: 
load("@rules_ruby//ruby:defs.bzl", "rb_binary", "rb_library")

rb_library(
    name = "version",
    srcs = ["version.rb"],
)

rb_binary(
    name = "print-version",
    args = ["lib/gem/version.rb"],
    deps = [":version"],
)

$ bazel run lib/gem:print-version
...
Version is: 0.1.0
You can also run general purpose Ruby scripts that rely on a Ruby interpreter in PATH: lib/gem/add.rb: 
#!/usr/bin/env ruby

a, b = *ARGV
puts Integer(a) + Integer(b)
lib/gem/BUILD: 
load("@rules_ruby//ruby:defs.bzl", "rb_binary", "rb_library")

rb_library(
    name = "add",
    srcs = ["add.rb"],
)

rb_binary(
    name = "add-numbers",
    main = "add.rb",
    deps = [":add"],
)

$ bazel run lib/gem:add-numbers 1 2
...
3
You can also run a Ruby binary script available in Gemfile dependencies, by passing bin argument with a path to a Bundler binary stub: BUILD: 
load("@rules_ruby//ruby:defs.bzl", "rb_binary")

package(default_visibility = ["//:__subpackages__"])

rb_binary(
    name = "rake",
    main = "@bundle//bin:rake",
    deps = [
        "//lib:gem",
        "@bundle",
    ],
)

$ bazel run :rake -- --version
...
rake, version 13.1.0
Kind: Executable rule

​
Attributes

​
name
name
required
A unique name for this target.
​
main
label
default:"None"
Ruby script to run. It may also be a binary stub generated by Bundler. If omitted, it defaults to the Ruby interpreter.Use a built-in args attribute to pass extra arguments to the script.
​
env
dictionary: String → String
default:"{}"
Environment variables to use during execution.Supports $(location) expansion for targets from srcs, data and deps.
​
env_inherit
list of strings
default:"[]"
List of environment variable names to be inherited by the test runner.
​
ruby
label
default:"None"
Override Ruby toolchain to use when running the script.
​
coverage_filters
list of strings
default:"[]"
Additional coverage filters to add to SimpleCov. Only applied during ‘bazel coverage’.
​
srcs
list of labels
default:"[]"
List of Ruby source files used to build the library.
​
data
list of labels
default:"[]"
List of runtime dependencies needed by a program that depends on this library.
​
deps
list of labels
default:"[]"
List of other Ruby libraries the target depends on.

​
Rule: rb_bundle_install

Installs Bundler dependencies from cached gems. You normally don’t need to call this rule directly as it’s an internal one used by rb_bundle_fetch().

​
Attributes

​
name
name
required
A unique name for this target.
​
gemfile
label
required
Gemfile to install dependencies from.
​
gemfile_lock
label
required
Gemfile.lock to install dependencies from.
​
gems
list of labels
required
List of gems in vendor/cache that are used to install dependencies from.
​
jars
list of labels
default:"[]"
JAR dependencies for JRuby gems.
​
jars_path
string
default:"\"\""
Path to the directory containing JAR dependencies (set as JARS_HOME).
​
srcs
list of labels
default:"[]"
List of Ruby source files used to build the library.
​
env
dictionary: String → String
default:"{}"
Environment variables to use during installation.
​
ruby
label
default:"None"
Override Ruby toolchain to use when installing the gem.

​
Rule: rb_gem

Exposes a Ruby gem file. You normally don’t need to call this rule directly as it’s an internal one used by rb_bundle_fetch().

​
Attributes

​
name
name
required
A unique name for this target.
​
gem
label
required
Gem file.

​
Rule: rb_gem_build

Builds a Ruby gem. Suppose you have the following Ruby gem, where rb_library() is used in BUILD files to define the packages for the gem. 
|-- BUILD
|-- Gemfile
|-- WORKSPACE
|-- gem.gemspec
`-- lib
    |-- BUILD
    |-- gem
    |   |-- BUILD
    |   |-- add.rb
    |   |-- subtract.rb
    |   `-- version.rb
    `-- gem.rb
And a RubyGem specification is: gem.gemspec: 
root = File.expand_path(__dir__)
$LOAD_PATH.push(File.expand_path('lib', root))
require 'gem/version'

Gem::Specification.new do |s|
  s.name = 'example'
  s.version = GEM::VERSION

  s.authors = ['Foo Bar']
  s.email = ['foobar@gmail.com']
  s.homepage = 'http://rubygems.org'
  s.license = 'MIT'

  s.summary = 'Example'
  s.description = 'Example gem'
  s.files = ['Gemfile'] + Dir['lib/**/*']

  s.require_paths = ['lib']
  s.add_dependency 'rake', '~> 10'
  s.add_development_dependency 'rspec', '~> 3.0'
  s.add_development_dependency 'rubocop', '~> 1.10'
end
You can now package everything into a .gem file by defining a target: BUILD: 
load("@rules_ruby//ruby:defs.bzl", "rb_gem_build")

package(default_visibility = ["//:__subpackages__"])

rb_gem_build(
    name = "gem-build",
    gemspec = "gem.gemspec",
    deps = [
        "//lib:gem",
        "@bundle",
    ],
)

$ bazel build :gem-build
...
  Successfully built RubyGem
  Name: example
  Version: 0.1.0
  File: example-0.1.0.gem
...

​
Attributes

​
name
name
required
A unique name for this target.
​
srcs
list of labels
default:"[]"
List of Ruby source files used to build the library.
​
deps
list of labels
default:"[]"
List of other Ruby libraries the target depends on.
​
data
list of labels
default:"[]"
List of runtime dependencies needed by a program that depends on this library.
​
bundle_env
dictionary: String → String
default:"{}"
List of bundle environment variables to set when building the library.
​
ruby
label
default:"None"
Override Ruby toolchain to use when running the script.
​
gemspec
label
required
Gemspec file to use for gem building.

​
Rule: rb_gem_install

Installs a built Ruby gem. Suppose you have the following Ruby gem, where rb_library() is used in BUILD files to define the packages for the gem and rb_gem_build() is used to build a Ruby gem package from the sources. 
|-- BUILD
|-- Gemfile
|-- WORKSPACE
|-- gem.gemspec
`-- lib
    |-- BUILD
    |-- gem
    |   |-- BUILD
    |   |-- add.rb
    |   |-- subtract.rb
    |   `-- version.rb
    `-- gem.rb
You can now install the built .gem file by defining a target: BUILD: 
load("@rules_ruby//ruby:defs.bzl", "rb_gem_build", "rb_gem_install")

package(default_visibility = ["//:__subpackages__"])

rb_gem_build(
    name = "gem-build",
    gemspec = "gem.gemspec",
    deps = ["//lib:gem"],
)

rb_gem_install(
    name = "gem-install",
    gem = ":gem-build",
)

$ bazel build :gem-install
...
Successfully installed example-0.1.0
1 gem installed
...

​
Attributes

​
name
name
required
A unique name for this target.
​
gem
label
required
Gem file to install.
​
ruby
label
default:"None"
Override Ruby toolchain to use when installing the gem.

​
Rule: rb_gem_push

Pushes a built Ruby gem. Suppose you have the following Ruby gem, where rb_library() is used in BUILD files to define the packages for the gem and rb_gem_build() is used to build a Ruby gem package from the sources. 
|-- BUILD
|-- Gemfile
|-- WORKSPACE
|-- gem.gemspec
`-- lib
    |-- BUILD
    |-- gem
    |   |-- BUILD
    |   |-- add.rb
    |   |-- subtract.rb
    |   `-- version.rb
    `-- gem.rb
You can now release the built .gem file to RubyGems by defining a target: BUILD: 
load("@rules_ruby//ruby:defs.bzl", "rb_gem_build", "rb_gem_push")

package(default_visibility = ["//:__subpackages__"])

rb_gem_build(
    name = "gem-build",
    gemspec = "gem.gemspec",
    deps = ["//lib:gem"],
)

rb_gem_push(
    name = "gem-release",
    gem = ":gem-build",
)

$ bazel run :gem-release
...
Pushing gem to https://rubygems.org...
Successfully registered gem: example (0.1.0)
Kind: Executable rule

​
Attributes

​
name
name
required
A unique name for this target.
​
srcs
list of labels
default:"[]"
List of Ruby source files used to build the library.
​
deps
list of labels
default:"[]"
List of other Ruby libraries the target depends on.
​
data
list of labels
default:"[]"
List of runtime dependencies needed by a program that depends on this library.
​
bundle_env
dictionary: String → String
default:"{}"
List of bundle environment variables to set when building the library.
​
gem
label
required
Gem file to push to RubyGems. You would usually use an output of rb_gem_build() target here.
​
env
dictionary: String → String
default:"{}"
Environment variables to use during execution.Supports $(location) expansion for targets from srcs, data and deps.
​
env_inherit
list of strings
default:"[]"
List of environment variable names to be inherited by the test runner.
​
ruby
label
default:"None"
Override Ruby toolchain to use when running the script.

​
Rule: rb_library

Defines a Ruby library. Suppose you have the following Ruby gem: 
|-- BUILD
|-- Gemfile
|-- WORKSPACE
|-- gem.gemspec
`-- lib
    |-- BUILD
    |-- gem
    |   |-- BUILD
    |   |-- add.rb
    |   |-- subtract.rb
    |   `-- version.rb
    `-- gem.rb
You can define packages for the gem source files: BUILD: 
load("@rules_ruby//ruby:defs.bzl", "rb_library")

package(default_visibility = ["//:__subpackages__"])

rb_library(
    name = "gem",
    deps = ["//lib:gem"],
)
lib/BUILD: 
load("@rules_ruby//ruby:defs.bzl", "rb_library")

package(default_visibility = ["//:__subpackages__"])

rb_library(
    name = "gem",
    srcs = ["gem.rb"],
    deps = [
        "//lib/gem:add",
        "//lib/gem:subtract",
        "//lib/gem:version",
    ],
)
lib/gem/BUILD: 
load("@rules_ruby//ruby:defs.bzl", "rb_library")

package(default_visibility = ["//:__subpackages__"])

rb_library(
    name = "add",
    srcs = ["add.rb"],
)

rb_library(
    name = "subtract",
    srcs = ["subtract.rb"],
)

rb_library(
    name = "version",
    srcs = ["version.rb"],
)
Once the packages are defined, you can use them in other targets such as rb_gem_build() to build a Ruby gem. See examples of using other rules.

​
Attributes

​
name
name
required
A unique name for this target.
​
srcs
list of labels
default:"[]"
List of Ruby source files used to build the library.
​
deps
list of labels
default:"[]"
List of other Ruby libraries the target depends on.
​
data
list of labels
default:"[]"
List of runtime dependencies needed by a program that depends on this library.
​
bundle_env
dictionary: String → String
default:"{}"
List of bundle environment variables to set when building the library.

​
Rule: rb_test

Runs a Ruby test. Suppose you have the following Ruby gem, where rb_library() is used in BUILD files to define the packages for the gem. 
|-- BUILD
|-- Gemfile
|-- WORKSPACE
|-- gem.gemspec
|-- lib
|   |-- BUILD
|   |-- gem
|   |   |-- BUILD
|   |   |-- add.rb
|   |   |-- subtract.rb
|   |   `-- version.rb
|   `-- gem.rb
`-- spec
    |-- BUILD
    |-- add_spec.rb
    |-- spec_helper.rb
    `-- subtract_spec.rb
You can run all tests inside spec/ by defining individual targets: spec/BUILD: 
load("@rules_ruby//ruby:defs.bzl", "rb_library", "rb_test")

rb_library(
    name = "spec_helper",
    srcs = ["spec_helper.rb"],
)

rb_test(
    name = "add",
    srcs = ["add_spec.rb"],
    args = ["spec/add_spec.rb"],
    main = "@bundle//bin:rspec",
    deps = [
        ":spec_helper",
        "@bundle",
    ],
)

rb_test(
    name = "subtract",
    srcs = ["subtract_spec.rb"],
    args = ["spec/subtract_spec.rb"],
    main = "@bundle//bin:rspec",
    deps = [
        ":spec_helper",
        "@bundle",
    ],
)

$ bazel test spec/...
...
//spec:add                                                               PASSED in 0.4s
//spec:subtract                                                          PASSED in 0.4s

Executed 2 out of 2 tests: 2 tests pass.
Since rb_test() is a wrapper around rb_binary(), you can also use it to run a Ruby binary script available in Gemfile dependencies, by passing main argument with a path to a Bundler binary stub. BUILD: 
load("@rules_ruby//ruby:defs.bzl", "rb_test")

package(default_visibility = ["//:__subpackages__"])

rb_test(
    name = "rubocop",
    args = ["lib/"],
    main = "@bundle//bin:rubocop",
    tags = ["no-sandbox"],
    deps = [
        "//lib:gem",
        "@bundle",
    ],
)

$ bazel test :rubocop
...
//:rubocop                                                               PASSED in 0.8s

Executed 1 out of 1 test: 1 test passes.

​
Code Coverage

To enable code coverage, run tests with the coverage command: 
bazel coverage //...
[!NOTE] Code coverage is currently not supported on Windows.
See the README for more details. Note that you can also run every test target passing extra arguments to the Ruby script. For example, you can re-use :rubocop target to perform autocorrect: 
$ bazel run :rubocop -- --autocorrect-all
...
Inspecting 11 files
.C.........

Offenses:

gem.gemspec:1:1: C: [Corrected] Style/FrozenStringLiteralComment: Missing frozen string literal comment.
root = File.expand_path(__dir__)
^
gem.gemspec:2:1: C: [Corrected] Layout/EmptyLineAfterMagicComment: Add an empty line after magic comments.
root = File.expand_path(__dir__)
^

11 files inspected, 2 offenses detected, 2 offenses corrected
Kind: Test rule

​
Attributes

​
name
name
required
A unique name for this target.
​
main
label
default:"None"
Ruby script to run. It may also be a binary stub generated by Bundler. If omitted, it defaults to the Ruby interpreter.Use a built-in args attribute to pass extra arguments to the script.
​
env
dictionary: String → String
default:"{}"
Environment variables to use during execution.Supports $(location) expansion for targets from srcs, data and deps.
​
env_inherit
list of strings
default:"[]"
List of environment variable names to be inherited by the test runner.
​
ruby
label
default:"None"
Override Ruby toolchain to use when running the script.
​
coverage_filters
list of strings
default:"[]"
Additional coverage filters to add to SimpleCov. Only applied during ‘bazel coverage’.
​
srcs
list of labels
default:"[]"
List of Ruby source files used to build the library.
​
data
list of labels
default:"[]"
List of runtime dependencies needed by a program that depends on this library.
​
deps
list of labels
default:"[]"
List of other Ruby libraries the target depends on.