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",
        "cpu": "x86_64|arm64"
      }
    ]
  }
}

The lockfile supports the following binary kinds:

file: the URL refers to a file to download
- sha256: the sha256 of the downloaded file
archive: the URL referes to an archive to download, specify additional options:
- file: executable file within the archive
- sha256: the sha256 of the downloaded archive
pkg: the URL refers to a MacOS pkg archive to download, specify additional options:
- file: executable file within the archive
- sha256: the sha256 of the downloaded pkg archive

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.

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 https://github.com/bazelbuild/bazel/issues/3325.

To run a tool in the current working directory, use the convenience target @multitool//tools/tool-name:cwd.

A common pattern we recommend to further simplify invoking tools for repository users it to:

Create a tools/ directory

Create an executable shell script tools/_run_multitool.sh with the following code:

#!/usr/bin/env bash
bazel run "@multitool//tools/$( basename $0 ):cwd" -- "$@"

Create symlinks of tools/tool-name to tools/_run_multitool.sh