rules_multitool
v1.5.0
published 2 weeks ago
39 stars
13 forks
2 watchers
Apache License 2.0
public
1 assets
5,537,765 downloads
18 KB
Compatibility level 1
J9crcsYQrUwE+b6DkOTO292gbJGW2Av052QFLgvlPYI=
v1.5.0
June 13, 2025
[expand for release notes]

rules_multitool

An ergonomic approach to defining a single tool target that resolves to a matching os and CPU architecture variant of the tool.

Usage

For a quickstart, see the module example or workspace example.

Define a lockfile that references the tools to load:

{
  "$schema": "https://raw.githubusercontent.com/theoremlp/rules_multitool/main/lockfile.schema.json",
  "tool-name": {
    "binaries": [
      {
        "kind": "file",
        "url": "https://...",
        "sha256": "sha256 of the file",
        "os": "linux|macos|windows",
        "cpu": "x86_64|arm64"
      }
    ]
  }
}

The lockfile supports the following binary kinds:

Bazel Module Usage

Once your lockfile is defined, load the ruleset in your MODULE.bazel and create a hub that refers to your lockfile:

bazel_dep(name = "rules_multitool", version = "0.0.0")

multitool = use_extension("@rules_multitool//multitool:extension.bzl", "multitool")
multitool.hub(lockfile = "//:multitool.lock.json")
use_repo(multitool, "multitool")

Tools may then be accessed using @multitool//tools/tool-name.

It's safe to call multitool.hub(...) multiple times, with multiple lockfiles. All lockfiles will be combined with a last-write-wins strategy.

Lockfiles defined across modules and applying to the same hub (including implicitly to the default "multitool" hub) will be combined such that the priority follows a breadth-first search originating from the root module.

It's possible to define multiple multitool hubs to group related tools together. To define an alternate hub:

multitool.hub(hub_name = "alt_hub", lockfile = "//:other_tools.lock.json")
use_repo(multitool, "alt_hub")

# register the tools from this hub
register_toolchains("@alt_hub//toolchains:all")

These alternate hubs also combine lockfiles according to the hub_name and follow the same merging rules as the default hub.

Workspace Usage

Instructions for using with WORKSPACE may be found in release notes.

Running tools in the current working directory

When running @multitool//tools/tool-name, Bazel will execute the tool at the root of the runfiles tree due to bazelbuild/bazel#3325.

It's possible to workaround this:

  • To run a tool in the current working directory, use the convenience target @multitool//tools/[tool-name]:cwd.
  • To run a tool in the Bazel module or workspace root, use the convenience target @multitool//tools/[tool-name]:workspace_root.

Alternatively, consider using https://registry.build/github/buildbuddy-io/bazel_env.bzl to put tools on the PATH.

Keeping Tools Up-to-Date

We provide a companion CLI multitool to help manage multitool lockfiles. The CLI supports basic updating of artifacts that come from GitHub releases, and may be extended in the future to support other common release channels.

See our docs on configuring a GitHub Action to check for updates and open PRs periodically.