Quickstart

This guide takes you from nothing to a working workspace with a shell task, a hermetically built Go binary, and a passing test.

Install rbs

rbs ships as a single self-contained binary — there is no runtime to install and no system toolchain to set up, since rbs manages its own toolchains from the first build onward. Get the binary from your organization’s distribution channel (for example a private Homebrew tap), place it on your PATH, and verify it:

rbs --version

rbs --version — identifies the installed binary; expect its version string.

There is no public package registry release yet — ask your team where they publish rbs internally.

Create a workspace

A workspace is any directory tree whose root contains a WORKSPACE.rbs file. That file is the root marker and the place where workspace-wide configuration — most importantly toolchains — lives. It can start empty.

mkdir hello-reasonos
cd hello-reasonos
touch WORKSPACE.rbs

mkdir hello-reasonos — creates the practice directory; expect no output on success.
cd hello-reasonos — enters that directory; expect no output, with subsequent commands running there.
touch WORKSPACE.rbs — creates the empty workspace marker; expect no output and a new file.

Every rbs command you run below this directory finds the root automatically. (You can override discovery with --workspace-root or the RBS_WORKSPACE_ROOT environment variable.)

Define your first targets

Targets are declared in BUILD.rbs files. A directory with a BUILD.rbs file is a package. Create one at the workspace root:

# BUILD.rbs

# The simplest target: run a command.
native.task(
    name = "hello",
    command = ["echo", "Hello from rbs!"],
    description = "Print a greeting",
)

# A target that produces a file...
native.task(
    name = "write_greeting",
    command = ["bash", "-c", "echo 'Hello from rbs' > greeting.txt"],
    outputs = ["greeting.txt"],
    description = "Write the greeting to a file",
)

# ...and a target that depends on it.
native.task(
    name = "show_greeting",
    command = ["cat", "greeting.txt"],
    deps = [":write_greeting"],
    description = "Print the greeting file",
)

Build, run, and query

# Build one target
rbs build :hello

# Run a target — dependencies build first, in order
rbs run :show_greeting

# List every target in the workspace without building anything
rbs query //...

rbs build :hello — builds the greeting target; expect a successful build summary.
rbs run :show_greeting — runs the greeting-file target after its dependency; expect Hello from rbs.
rbs query //... — lists workspace targets without building; expect hello, write_greeting and show_greeting.

:show_greeting depends on :write_greeting, so rbs builds the producer before the consumer. Run it twice: the second invocation is served from the shared cache.Labels name targets as //package/path:target_name. From inside a package you can abbreviate to :target_name, and rbs also accepts a natural syntax — rbs build path/to/pkg target_a target_b — when that reads better.

Add a hermetic Go toolchain

So far the tasks used your shell. Now build something hermetically. Declare a Go toolchain in WORKSPACE.rbs — rbs downloads and caches the Go SDK on first use; no system Go installation is required:

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

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

Write a small program and a test:

// main.go
package main

import "fmt"

func Greeting(name string) string {
	return "Hello, " + name + "!"
}

func main() {
	fmt.Println(Greeting("ReasonOS"))
}

// main_test.go
package main

import "testing"

func TestGreeting(t *testing.T) {
	if Greeting("x") != "Hello, x!" {
		t.Fatal("unexpected greeting")
	}
}

Then add targets to BUILD.rbs:

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

go_binary(
    name = "greet",
    srcs = ["main.go"],
)

go_test(
    name = "greet_test",
    srcs = ["main.go", "main_test.go"],
)

Run and test it

# First build downloads the pinned Go SDK, then compiles
rbs run :greet

# Run the test target
rbs test :greet_test

# Keep testing as sources change (Ctrl+C stops watching)
rbs test :greet_test --watch

rbs run :greet — builds and runs the Go program; expect Hello, ReasonOS! after any first-use toolchain download.
rbs test :greet_test — runs the greeting test; expect a passing test result.
rbs test :greet_test --watch — keeps testing as sources change (--watch stays running); expect a test result followed by more runs after edits.

Where builds land

Build outputs, toolchain links, and other per-workspace state materialize under .rbs/ in the workspace root. That directory is disposable — action results live in the user-global shared cache, so deleting .rbs/ costs you nothing but a re-materialization. Add .rbs/ to your .gitignore.

Next steps

Core concepts

Understand packages, labels, the graph, the cache, and environments.

Example workspaces

A guided tour of runnable examples, from hello-world to full-platform demos.

Build commands

Everything build, run, test, query, and coverage can do.

Languages

Rules and toolchains for each supported language.

Getting Started

Build

Languages

Containers & Deploy

Infrastructure

CI & Remote Builds

Team Workflow

Where builds land

Next steps

Core concepts

Example workspaces

Build commands

Languages

​Where builds land

​Next steps

Core concepts

Example workspaces

Build commands

Languages

Where builds land

Next steps