Packages and targets

Every rbs workspace is a directory tree with a WORKSPACE.rbs file at its root. Inside it, any directory that contains a build file is a package, and each package declares one or more targets — the things you build, test, and run. Targets are addressed by labels like //services/api:server.

The workspace

The workspace root is marked by a WORKSPACE.rbs file. Every rbs command finds the root by walking up from your current directory, so you can run commands from anywhere inside the workspace. WORKSPACE.rbs is also where you declare the hermetic toolchains your workspace uses — rbs downloads and manages them itself, so nothing needs to be installed on the machine:

# WORKSPACE.rbs
load("@rbs//go/toolchain.rbs", "go_toolchain")

go_toolchain(
    name = "go",
    version = "1.24.3",
)

rbs keeps per-workspace build state in a .rbs/ directory next to WORKSPACE.rbs (build outputs, launchers, test logs). It is disposable — safe to delete, never commit it. Cached action results live in the shared content-addressed cache outside the workspace, so deleting .rbs/ does not throw away cached work.

You can point a command at a specific workspace with --workspace-root or the RBS_WORKSPACE_ROOT environment variable instead of relying on auto-discovery.

Packages and build files

A package is any directory containing a file named BUILD.rbs (lowercase build.rbs is also accepted). The package’s path relative to the workspace root is its name: the build file at services/api/BUILD.rbs defines the package services/api. A build file at the workspace root defines the root package. Build files are written in the RBS language — a small, deterministic, Python-like language. A build file loads the rules it needs and calls them to declare targets:

# services/api/BUILD.rbs
load("@rbs//go/rules.rbs", "go_binary", "go_library")

go_library(
    name = "core",
    srcs = glob(["internal/**/*.go"]),
)

go_binary(
    name = "server",
    srcs = ["main.go"],
    deps = [":core"],
)

glob() is available in every build file without a load. It matches files relative to the package directory:

glob(["src/**/*.ts"], exclude = ["src/**/*.test.ts"])

Directories starting with . are never treated as packages, so a build file inside a hidden directory is ignored.

Labels

A label names one target. The full form is //package/path:target_name:

Form	Meaning
`//services/api:server`	Target `server` in package `services/api`
`:server`	Target `server` in the current package (relative to your working directory)
`services/api:server`	Same as the `//` form, written relative to the workspace root
`server`	Bare name — target `server` in the current package

Inside a build file, use :name for targets in the same package and //package:name for targets in other packages.

Target patterns

The build, test, run, query, and coverage commands all accept the same pattern syntax for addressing sets of targets:

Pattern	Matches
`//...`	Every target in the workspace
`//services/...`	Every target in every package under `services/`
`...`	Every target under the current directory’s package
`//services/api:all`	Every target in exactly one package
`:all`	Every target in the current package
`//services/api:server`	One target

rbs build //...                # build everything
rbs query //services/...       # list all targets under services/
rbs test :all                  # run this package's tests

Most commands also accept a natural syntax: a package path followed by one or more target names, which is convenient for building several targets in one package:

rbs build services/api server migrate    # same as //services/api:server //services/api:migrate

Depending on other targets

The deps attribute wires targets together. rbs resolves the whole dependency closure, builds it in dependency order, and runs independent targets in parallel:

go_binary(
    name = "server",
    srcs = ["main.go"],
    deps = [
        ":core",                    # same package
        "//libs/auth:auth",         # another package
    ],
)

Third-party packages from a language ecosystem are addressed with @external:// labels, pinned to a version:

load("@rbs//web-vite/vitest.rbs", "vitest_test")

vitest_test(
    name = "counter_test",
    srcs = ["src/Counter.tsx", "src/Counter.test.tsx"],
    deps = [
        "@external://react:19.0.0",
        "@external://react-dom:19.0.0",
        "@external://@testing-library/react:16.3.0",
    ],
)

rbs resolves external dependencies itself and shares them across workspaces through the shared cache — there is no npm install or pip install step.

`load()` semantics

load() imports named symbols from another .rbs module. Four path forms exist:

load("@rbs//go/rules.rbs", "go_binary")      # built-in rules shipped with rbs
load("//tools/macros.rbs", "release_binary") # workspace-relative
load("helpers.rbs", "common_srcs")           # relative to the current package
load("@mycompany//lint/rules.rbs", "lint")   # an external rule package (managed by `rbs ext`)

You can rename a symbol as you load it:

load("@rbs//go/rules.rbs", go_bin = "go_binary")

Gotchas worth knowing

load() bindings are file-local — they are not re-exported. If module a.rbs loads y from x.rbs, a file that loads a.rbs does not see y. An aggregator module must re-export explicitly:

# prelude.rbs
load("x.rbs", _y = "y")
y = _y          # now loadable from prelude.rbs

Without the assignment, the aggregator silently exports nothing.

No implicit string concatenation. Adjacent string literals are a parse error in the RBS language. Use explicit + or join:

# WRONG - parse error
cmd = "echo hello" " world"

# Right
cmd = "echo hello" + " world"
lines = "\n".join(["a", "b", "c"])

Other language properties to keep in mind:

Build files are declarative: evaluating a build file only registers targets — no compilation or command runs until you invoke rbs build.
glob() is the way to enumerate source files; there is no general file I/O in build files.
Loaded modules are cached, so loading the same module from many files is cheap.

Getting Started

Build

Languages

Containers & Deploy

Infrastructure

CI & Remote Builds

Team Workflow

The workspace

Packages and build files

Labels

Target patterns

Depending on other targets

`load()` semantics

Gotchas worth knowing

​The workspace

​Packages and build files

​Labels

​Target patterns

​Depending on other targets

​load() semantics

​Gotchas worth knowing

The workspace

Packages and build files

Labels

Target patterns

Depending on other targets

`load()` semantics

Gotchas worth knowing