rustfmt - rules

Overview

Rustfmt is a tool for formatting Rust code according to style guidelines. By default, Rustfmt uses a style which conforms to the Rust style guide that has been formalized through the style RFC process. A complete list of all configuration options can be found in the Rustfmt GitHub Pages.

Setup

Formatting your Rust targets' source code requires no setup outside of loading rules_rust in your workspace. Simply run bazel run @rules_rust//:rustfmt to format source code.

In addition to this formatter, a simple check can be performed using the rustfmt_aspect aspect by running

bazel build --aspects=@rules_rust//rust:defs.bzl%rustfmt_aspect --output_groups=rustfmt_checks

Add the following to a .bazelrc file to enable this check during the build phase.

build --aspects=@rules_rust//rust:defs.bzl%rustfmt_aspect
build --output_groups=+rustfmt_checks

It's recommended to only enable this aspect in your CI environment so formatting issues do not impact user's ability to rapidly iterate on changes.

The rustfmt_aspect also uses a --@rules_rust//rust/settings:rustfmt.toml setting which determines the configuration file used by the formatter (@rules_rust//tools/rustfmt) and the aspect (rustfmt_aspect). This flag can be added to your .bazelrc file to ensure a consistent config file is used whenever rustfmt is run:

build --@rules_rust//rust/settings:rustfmt.toml=//:rustfmt.toml

Rules

rustfmt_test

Aspects

rustfmt_aspect

rustfmt_test

load("@rules_rust//rust:defs.bzl", "rustfmt_test")

rustfmt_test(name, platform, targets, transitive)

A test rule that runs rustfmt --check over a set of Rust targets.

By default (transitive = False), only the exact targets listed are checked. Set transitive = True to walk deps, proc_macro_deps, and crate so that listing a top-level target checks its whole crate graph.

The rustfmt actions run during the build phase, so a formatting failure fails bazel test before the test executable is invoked. The rule also exposes the collected markers under the rustfmt_checks output group, so bazel build //x:my_fmt_test --output_groups=rustfmt_checks drives the rustfmt actions without running the test.

An optional platform attribute transitions targets to the given platform before running rustfmt.

Example:

load("@rules_rust//rust:defs.bzl", "rust_binary", "rust_library", "rustfmt_test")

rust_library(
    name = "lib",
    srcs = ["src/lib.rs"],
    edition = "2021",
)

rust_binary(
    name = "app",
    srcs = ["src/main.rs"],
    edition = "2021",
    deps = [":lib"],
)

rustfmt_test(
    name = "fmt_app_only_test",
    targets = [":app"]
)

rustfmt_test(
    name = "fmt_tree_test",
    targets = [":app"],
    transitive = True,
)

Targets tagged no_format, no_rustfmt, or norustfmt are skipped.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
platform	Optional platform to transition `targets` to before running the aspect. When set, `--platforms` is switched to this label for the duration of this rule's aspect actions.	Label	optional	`None`
targets	Rust targets to run `rustfmt --check` on.	List of labels	optional	`[]`
transitive	If True, lint `targets` and every crate reachable via `deps`, `proc_macro_deps`, and `crate`. If False, lint only the exact targets listed.	Boolean	optional	`False`

rustfmt_aspect

load("@rules_rust//rust:defs.bzl", "rustfmt_aspect")

rustfmt_aspect()

This aspect is used to gather information about a crate for use in rustfmt and perform rustfmt checks

Output Groups:

rustfmt_checks: Executes rustfmt --check on the specified target.

The build setting @rules_rust//rust/settings:rustfmt.toml is used to control the Rustfmt configuration settings used at runtime.

This aspect is executed on any target which provides the CrateInfo provider. However users may tag a target with no-rustfmt or no-format to have it skipped. Additionally, generated source files are also ignored by this aspect.

ASPECT ATTRIBUTES

ATTRIBUTES