Skip to main content

Quick Start

Use this guide to run your first rtl_buddy test, regression, synthesis, and supporting commands in an already-installed project.

Run a test​

Run the test named basic using tests.yaml in the current directory:

uv run rb test basic

Specify a different test config file:

uv run rb test basic --test-config path/to/tests.yaml

Run all tests in a config:

uv run rb test

List available tests without running them:

uv run rb test --list

Run a regression​

uv run rb regression

This uses the regression config path from root_config.yaml. To specify a different file:

uv run rb regression --reg-config path/to/regression.yaml

Run synthesis​

List synthesis entries in a config:

uv run rb synth --list --synth-config path/to/synth.yaml

Run a synthesis entry:

uv run rb synth smoke_synth --synth-config path/to/synth.yaml

See Synthesis for synth.yaml, tool, and library configuration.

Run with randomization​

Run a test once with a new random seed:

uv run rb test basic --rnd-new

Run the same test 5 times with different seeds:

uv run rb randtest basic 5

Repeat a specific iteration from a previous randtest run:

uv run rb randtest basic 5 --rnd-rpt 3

Check logs​

rtl_buddy writes orchestration logs to rtl_buddy.log in the directory where it is run.

Simulation output for each test goes to artefacts/{test_name}/. A single run writes test.log, test.err, test.randseed, and (if coverage is enabled) coverage.dat directly there. Repeated runs (via randtest) write each iteration into a numbered subdirectory: artefacts/{test_name}/run-0001/, run-0002/, and so on. For convenience, the symlinks test.log, test.err, and test.randseed in the suite root always point to the latest run.

For machine-readable output (useful with CI or AI agents):

uv run rb --machine test basic

In machine mode, rtl_buddy.log is written as JSON Lines and console output is plain text. See For Agents for more on machine mode.

Next steps​