Skip to content

Latest commit

 

History

History
663 lines (509 loc) · 21.9 KB

rules.md

File metadata and controls

663 lines (509 loc) · 21.9 KB
Raw

Public API for rules

rb_binary

rb_binary(name, deps, srcs, data, env, env_inherit, main, ruby)

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

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps List of other Ruby libraries the target depends on. List of labels optional []
srcs List of Ruby source files used to build the library. List of labels optional []
data List of runtime dependencies needed by a program that depends on this library. List of labels optional []
env Environment variables to use during execution.

Supports $(location) expansion for targets from srcs, data and deps.		 Dictionary: String -> String optional {}
env_inherit List of environment variable names to be inherited by the test runner. List of strings optional []
main 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.		 Label optional None
ruby Override Ruby toolchain to use when running the script. Label optional None

rb_bundle_install

rb_bundle_install(name, srcs, env, gemfile, gemfile_lock, gems, ruby)

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 Description Type Mandatory Default
name A unique name for this target. Name required
srcs List of Ruby source files used to build the library. List of labels optional []
env Environment variables to use during installation. Dictionary: String -> String optional {}
gemfile Gemfile to install dependencies from. Label required
gemfile_lock Gemfile.lock to install dependencies from. Label required
gems List of gems in vendor/cache that are used to install dependencies from. List of labels required
ruby Override Ruby toolchain to use when installing the gem. Label optional None

rb_gem

rb_gem(name, 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 Description Type Mandatory Default
name A unique name for this target. Name required
gem Gem file. Label required

rb_gem_build

rb_gem_build(name, deps, srcs, data, bundle_env, gemspec, ruby)

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 = ['[email protected]']
  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 Description Type Mandatory Default
name A unique name for this target. Name required
deps List of other Ruby libraries the target depends on. List of labels optional []
srcs List of Ruby source files used to build the library. List of labels optional []
data List of runtime dependencies needed by a program that depends on this library. List of labels optional []
bundle_env List of bundle environment variables to set when building the library. Dictionary: String -> String optional {}
gemspec Gemspec file to use for gem building. Label required
ruby Override Ruby toolchain to use when running the script. Label optional None

rb_gem_install

rb_gem_install(name, gem, ruby)

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 Description Type Mandatory Default
name A unique name for this target. Name required
gem Gem file to install. Label required
ruby Override Ruby toolchain to use when installing the gem. Label optional None

rb_gem_push

rb_gem_push(name, deps, srcs, data, bundle_env, env, env_inherit, gem, ruby)

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)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps List of other Ruby libraries the target depends on. List of labels optional []
srcs List of Ruby source files used to build the library. List of labels optional []
data List of runtime dependencies needed by a program that depends on this library. List of labels optional []
bundle_env List of bundle environment variables to set when building the library. Dictionary: String -> String optional {}
env Environment variables to use during execution.

Supports $(location) expansion for targets from srcs, data and deps.		 Dictionary: String -> String optional {}
env_inherit List of environment variable names to be inherited by the test runner. List of strings optional []
gem Gem file to push to RubyGems. You would usually use an output of rb_gem_build() target here. Label required
ruby Override Ruby toolchain to use when running the script. Label optional None

rb_library

rb_library(name, deps, srcs, data, bundle_env)

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 Description Type Mandatory Default
name A unique name for this target. Name required
deps List of other Ruby libraries the target depends on. List of labels optional []
srcs List of Ruby source files used to build the library. List of labels optional []
data List of runtime dependencies needed by a program that depends on this library. List of labels optional []
bundle_env List of bundle environment variables to set when building the library. Dictionary: String -> String optional {}

rb_test

rb_test(name, deps, srcs, data, env, env_inherit, main, ruby)

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.

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

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps List of other Ruby libraries the target depends on. List of labels optional []
srcs List of Ruby source files used to build the library. List of labels optional []
data List of runtime dependencies needed by a program that depends on this library. List of labels optional []
env Environment variables to use during execution.

Supports $(location) expansion for targets from srcs, data and deps.		 Dictionary: String -> String optional {}
env_inherit List of environment variable names to be inherited by the test runner. List of strings optional []
main 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.		 Label optional None
ruby Override Ruby toolchain to use when running the script. Label optional None