Skip to content

repository_rules.md

Latest commit

 

History

History
235 lines (173 loc) · 12.2 KB

repository_rules.md

File metadata and controls

235 lines (173 loc) · 12.2 KB

Public API for repository rules

rb_bundle

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

rb_bundle(toolchain, **kwargs)

Wraps rb_bundle_rule() providing default toolchain name.

PARAMETERS

Name Description Default Value
toolchain default Ruby toolchain BUILD "@ruby//:BUILD"
kwargs underlying attrs passed to rb_bundle_rule() none

rb_register_toolchains

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

rb_register_toolchains(name, version, version_file, msys2_packages, portable_ruby,
                       portable_ruby_checksums, register, **kwargs)

Register a Ruby toolchain and lazily download the Ruby Interpreter.

  • (For MRI on Linux and macOS) Installed using ruby-build.
  • (For MRI on Windows) Installed using RubyInstaller.
  • (For JRuby on any OS) Downloaded and installed directly from official website.
  • (For TruffleRuby on Linux and macOS) Installed using ruby-build.
  • (With portable_ruby) Portable Ruby downloaded from jdx/ruby.
  • (For "system") Ruby found on the PATH is used. Please note that builds are not hermetic in this case.

WORKSPACE:

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

rb_register_toolchains(
    version = "3.0.6"
)

Once registered, you can use the toolchain directly as it provides all the binaries:

$ bazel run @ruby -- -e "puts RUBY_VERSION"
$ bazel run @ruby//:bundle -- update
$ bazel run @ruby//:gem -- install rails

You can also use Ruby engine targets to select() depending on installed Ruby interpreter:

BUILD:

rb_library(
    name = "my_lib",
    srcs = ["my_lib.rb"],
    deps = select({
        "@ruby//engine:jruby": [":my_jruby_lib"],
        "@ruby//engine:truffleruby": ["//:my_truffleruby_lib"],
        "@ruby//engine:ruby": ["//:my__lib"],
        "//conditions:default": [],
    }),
)

PARAMETERS

Name Description Default Value
name base name of resulting repositories, by default "ruby" "ruby"
version a semver version of MRI, or a string like [interpreter type]-[version], or "system" None
version_file .ruby-version or .tool-versions file to read version from None
msys2_packages extra MSYS2 packages to install ["libyaml"]
portable_ruby when True, downloads portable Ruby from jdx/ruby instead of compiling via ruby-build. Has no effect on JRuby, TruffleRuby, or Windows. False
portable_ruby_checksums platform checksums for portable Ruby downloads, overriding built-in checksums. Keys: linux-x86_64, linux-arm64, macos-arm64, macos-x86_64. {}
register whether to register the resulting toolchains, should be False under bzlmod True
kwargs additional parameters to the downloader for this interpreter type none

rb_bundle_fetch

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

rb_bundle_fetch(name, srcs, auth_patterns, bundler_checksums, bundler_remote, env, gem_checksums,
                gemfile, gemfile_lock, jar_checksums, netrc, repo_mapping, ruby)

Fetches Bundler dependencies to be automatically installed by other targets.

Currently doesn't support installing gems from Git repositories, see #62.

WORKSPACE:

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

rb_bundle_fetch(
    name = "bundle",
    gemfile = "//:Gemfile",
    gemfile_lock = "//:Gemfile.lock",
    srcs = [
        "//:gem.gemspec",
        "//:lib/gem/version.rb",
    ]
)

Checksums for gems in Gemfile.lock are printed by the ruleset during the build. It's recommended to add them to gem_checksums attribute.

WORKSPACE:

rb_bundle_fetch(
    name = "bundle",
    gemfile = "//:Gemfile",
    gemfile_lock = "//:Gemfile.lock",
    gem_checksums = {
        "ast-2.4.2": "1e280232e6a33754cde542bc5ef85520b74db2aac73ec14acef453784447cc12",
        "concurrent-ruby-1.2.2": "3879119b8b75e3b62616acc256c64a134d0b0a7a9a3fcba5a233025bcde22c4f",
    },
)

All the installed gems can be accessed using @bundle target and additionally gems binary files can also be used via BUILD rules or directly with bazel run:

BUILD:

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

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

rb_test(
    name = "rubocop",
    main = "@bundle//bin:rubocop",
    deps = ["@bundle"],
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this repository. Name required
srcs List of Ruby source files necessary during installation. List of labels optional []
auth_patterns A list of patterns to match against urls for which the auth object should be used. Dictionary: String -> String optional {}
bundler_checksums Custom map from Bundler version to its SHA-256 checksum. Dictionary: String -> String optional {}
bundler_remote Remote to fetch the bundler gem from. String optional "https://rubygems.org/"
env Environment variables to use during installation. Dictionary: String -> String optional {}
gem_checksums SHA-256 checksums for remote gems. Keys are gem names (e.g. foobar-1.2.3), values are SHA-256 checksums. Dictionary: String -> String optional {}
gemfile Gemfile to install dependencies from. Label required
gemfile_lock Gemfile.lock to install dependencies from. Label required
jar_checksums SHA-256 checksums for JAR dependencies. Keys are Maven coordinates (e.g. org.yaml:snakeyaml:1.33), values are SHA-256 checksums. Dictionary: String -> String optional {}
netrc Path to .netrc file to read credentials from String optional ""
repo_mapping In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target).

This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension's implementation function).		 Dictionary: String -> String optional
ruby Override Ruby toolchain to use for installation. Label optional None

rb_bundle_rule

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

rb_bundle_rule(name, srcs, env, gemfile, repo_mapping, toolchain)

(Deprecated) Use rb_bundle_fetch() instead.

Installs Bundler dependencies and registers an external repository that can be used by other targets.

WORKSPACE:

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

rb_bundle(
    name = "bundle",
    gemfile = "//:Gemfile",
    srcs = [
        "//:gem.gemspec",
        "//:lib/gem/version.rb",
    ]
)

All the installed gems can be accessed using @bundle target and additionally gems binary files can also be used:

BUILD:

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

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

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

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this repository. 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 optional None
repo_mapping In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target).

This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension's implementation function).		 Dictionary: String -> String optional
toolchain - Label required