rules_verible

Bazel rules that wrap the Verible SystemVerilog/Verilog tools — verible-verilog-format, verible-verilog-lint, and verible-verilog-diff — for projects that build with rules_verilog.

Overview

Each tool ships as a combination of an aspect (run via bazel build --config=...), a test rule, and a fixer binary (run via bazel run). Process wrappers are written in C++ (POSIX + Win32) so the rule set works on every platform Verible itself ships for, with no scripting-language dependency.

• verible_toolchain — registers the three Verible binaries (verible-verilog-format, verible-verilog-lint, verible-verilog-diff). Default toolchains are auto-registered per-platform using prebuilt release tarballs.
• verible_format_aspect / verible_format_test — check that VerilogInfo targets are correctly formatted.
• verible_lint_aspect / verible_lint_test — lint VerilogInfo targets.
• verible_diff_test — token-level diff between two Verilog/SystemVerilog files (format mode by default).
• bazel run //verible:format_fix -- //... — rewrites Verilog sources in-place via verible-verilog-format --inplace.
• bazel run //verible:lint_fix -- //... — applies verible-verilog-lint --autofix=inplace across the workspace.

Rule API details are generated from the Starlark sources in the sections linked from Summary.

Quick start

Add to MODULE.bazel:

bazel_dep(name = "rules_verilog", version = "1.1.1")
bazel_dep(name = "rules_verible", version = "{version}")

Then in a BUILD.bazel:

load("@rules_verilog//verilog:defs.bzl", "verilog_library")
load("@rules_verible//verible:defs.bzl", "verible_format_test", "verible_lint_test")

verilog_library(name = "adder", srcs = ["adder.sv"])

verible_format_test(name = "adder_format_test", target = ":adder")
verible_lint_test(name = "adder_lint_test", target = ":adder")

Providing a Verible config

Three label_flags in @rules_verible//verible control what config the aspects and test rules pass to Verible. Their defaults are no-op files, so out of the box nothing changes; point any of them at your own file(s) to apply project-wide settings:

Wire them up in .bazelrc:

build --@rules_verible//verible:rules_config=//tools/verible:project.rules_config
build --@rules_verible//verible:lint_flagfiles=//tools/verible:lint_flagfiles
build --@rules_verible//verible:format_flagfiles=//tools/verible:format_flagfiles

Where the filegroup targets look like:

filegroup(name = "lint_flagfiles",   srcs = ["base.flagfile", "team.flagfile"])
filegroup(name = "format_flagfiles", srcs = ["format.flagfile"])

Individual test targets can override the flag defaults per target. flagfiles takes a single label — either a file or a filegroup wrapping multiple files:

verible_lint_test(
    name = "adder_lint_test",
    target = ":adder",
    rules_config = "//tools/verible:stricter.rules_config",
    flagfiles    = "//tools/verible:extra.flagfile",
)

Enabling the aspects in your .bazelrc

The aspect-driven checks (the --config=verible_format, --config=verible_lint, and combined --config=verible flags) are not auto-registered downstream. Add the following block to your repo's .bazelrc to opt in:

# Enable verible-verilog-format checks for all targets in the workspace.
# Usage: bazel build --config=verible_format //...
build:verible_format --aspects=@rules_verible//verible:verible_format_aspect.bzl%verible_format_aspect
build:verible_format --output_groups=+verible_format_checks

# Enable verible-verilog-lint checks for all targets in the workspace.
# Usage: bazel build --config=verible_lint //...
build:verible_lint --aspects=@rules_verible//verible:verible_lint_aspect.bzl%verible_lint_aspect
build:verible_lint --output_groups=+verible_lint_checks

# Composite: run both at once.
# Usage: bazel build --config=verible //...
build:verible --config=verible_format
build:verible --config=verible_lint

Aspects propagate across every transitive VerilogInfo-providing dependency, so a single bazel build --config=verible //some:top_target checks the whole graph reachable from //some:top_target. To exclude a verilog_library from the sweep, tag it with one of:

The bazel run //verible:format_fix / lint_fix fixer binaries honor the same tag set when discovering Verilog sources via bazel query.

Where the Verible binaries come from

Verible binaries come from the upstream GitHub releases via a module extension; supported platforms are linux x86_64, linux aarch64, macOS, and windows x86_64. To override (e.g. point at a system-installed or vendored Verible), register your own verible_toolchain(...) instance ahead of the defaults — see the verible_toolchain page.

Rules

• verible_toolchain
• verible_format_aspect
• verible_format_test
• verible_lint_aspect
• verible_lint_test
• verible_diff_test

verible_toolchain rule

Rules

• verible_toolchain

verible_toolchain

load("@rules_verible//verible:verible_toolchain.bzl", "verible_toolchain")

verible_toolchain(name, verible_diff, verible_format, verible_lint)

A toolchain that exposes the Verible tools.

A single instance holds every Verible binary rules_verible knows about (verible-verilog-format, verible-verilog-lint, verible-verilog-diff). The format, lint, and diff pipelines all consume the same //verible:toolchain_type and pull whichever binary they need from the resolved ToolchainInfo.

The rule also provides platform_common.TemplateVariableInfo exposing VERIBLE_FORMAT_RLOCATIONPATH, VERIBLE_LINT_RLOCATIONPATH, and VERIBLE_DIFF_RLOCATIONPATH, so a downstream cc_binary can reference each binary's runfiles key via env = {"VERIBLE_..._RLOCATIONPATH": "$(VERIBLE_..._RLOCATIONPATH)"}.

The default toolchain registered by //verible/toolchain:all points at the prebuilt Verible releases for linux x86_64, linux aarch64, macOS, and windows x86_64. To override (e.g. point at a vendored or system-installed Verible), instantiate this rule yourself and register_toolchains(...) it ahead of the defaults in your MODULE.bazel.

ATTRIBUTES

verible_format_aspect rule

Aspects

• verible_format_aspect

verible_format_aspect

load("@rules_verible//verible:verible_format_aspect.bzl", "verible_format_aspect")

verible_format_aspect()

Aspect that runs verible-verilog-format --verify on every VerilogInfo target.

ASPECT ATTRIBUTES

ATTRIBUTES

verible_format_test rule

Rules

• verible_format_test

verible_format_test

load("@rules_verible//verible:verible_format_test.bzl", "verible_format_test")

verible_format_test(name, flagfiles, target)

Test rule that runs verible-verilog-format --verify against a VerilogInfo target.

ATTRIBUTES

verible_lint_aspect aspect

Aspects

• verible_lint_aspect

verible_lint_aspect

load("@rules_verible//verible:verible_lint_aspect.bzl", "verible_lint_aspect")

verible_lint_aspect()

Aspect that runs verible-verilog-lint on every VerilogInfo target.

ASPECT ATTRIBUTES

ATTRIBUTES

verible_lint_test rule

Rules

• verible_lint_test

verible_lint_test

load("@rules_verible//verible:verible_lint_test.bzl", "verible_lint_test")

verible_lint_test(name, flagfiles, rules_config, target)

Test rule that runs verible-verilog-lint against a VerilogInfo target.

ATTRIBUTES

verible_diff_test rule

Rules

• verible_diff_test

verible_diff_test

load("@rules_verible//verible:verible_diff_test.bzl", "verible_diff_test")

verible_diff_test(name, file1, file2, mode)

Test rule that runs verible-verilog-diff between two Verilog sources.

By default the comparison uses format mode, which ignores whitespace and compares token texts — useful for verifying that some transformed source still parses to the same tokens as a golden reference. Set mode = "obfuscate" to compare token-text lengths only, the standard recipe for verifying verible-verilog-obfuscate output.

The test exits 0 when the sources are equivalent under the chosen mode, and with the diff binary's non-zero status (1) otherwise; the per-token mismatch report is emitted to the test log.

ATTRIBUTES