1<!-- Generated with Stardoc: http://skydoc.bazel.build --> 2# Rust Fmt 3 4* [rustfmt_aspect](#rustfmt_aspect) 5* [rustfmt_test](#rustfmt_test) 6* [rustfmt_toolchain](#rustfmt_toolchain) 7 8 9## Overview 10 11 12[Rustfmt][rustfmt] is a tool for formatting Rust code according to style guidelines. 13By default, Rustfmt uses a style which conforms to the [Rust style guide][rsg] that 14has been formalized through the [style RFC process][rfcp]. A complete list of all 15configuration options can be found in the [Rustfmt GitHub Pages][rgp]. 16 17 18 19### Setup 20 21 22Formatting your Rust targets' source code requires no setup outside of loading `rules_rust` 23in your workspace. Simply run `bazel run @rules_rust//:rustfmt` to format source code. 24 25In addition to this formatter, a simple check can be performed using the [rustfmt_aspect](#rustfmt-aspect) aspect by running 26```text 27bazel build --aspects=@rules_rust//rust:defs.bzl%rustfmt_aspect --output_groups=rustfmt_checks 28``` 29 30Add the following to a `.bazelrc` file to enable this check during the build phase. 31 32```text 33build --aspects=@rules_rust//rust:defs.bzl%rustfmt_aspect 34build --output_groups=+rustfmt_checks 35``` 36 37It's recommended to only enable this aspect in your CI environment so formatting issues do not 38impact user's ability to rapidly iterate on changes. 39 40The `rustfmt_aspect` also uses a `--@rules_rust//:rustfmt.toml` setting which determines the 41[configuration file][rgp] used by the formatter (`@rules_rust//tools/rustfmt`) and the aspect 42(`rustfmt_aspect`). This flag can be added to your `.bazelrc` file to ensure a consistent config 43file is used whenever `rustfmt` is run: 44 45```text 46build --@rules_rust//:rustfmt.toml=//:rustfmt.toml 47``` 48 49### Tips 50 51 52Any target which uses Bazel generated sources will cause the `@rules_rust//tools/rustfmt` tool to fail with 53``failed to resolve mod `MOD` ``. To avoid failures, [`skip_children = true`](https://rust-lang.github.io/rustfmt/?version=v1.6.0&search=skip_chil#skip_children) 54is recommended to be set in the workspace's `rustfmt.toml` file which allows rustfmt to run on these targets 55without failing. 56 57[rustfmt]: https://github.com/rust-lang/rustfmt#readme 58[rsg]: https://github.com/rust-lang-nursery/fmt-rfcs/blob/master/guide/guide.md 59[rfcp]: https://github.com/rust-lang-nursery/fmt-rfcs 60[rgp]: https://rust-lang.github.io/rustfmt/ 61 62<a id="rustfmt_test"></a> 63 64## rustfmt_test 65 66<pre> 67rustfmt_test(<a href="#rustfmt_test-name">name</a>, <a href="#rustfmt_test-targets">targets</a>) 68</pre> 69 70A test rule for performing `rustfmt --check` on a set of targets 71 72**ATTRIBUTES** 73 74 75| Name | Description | Type | Mandatory | Default | 76| :------------- | :------------- | :------------- | :------------- | :------------- | 77| <a id="rustfmt_test-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 78| <a id="rustfmt_test-targets"></a>targets | Rust targets to run `rustfmt --check` on. | <a href="https://bazel.build/concepts/labels">List of labels</a> | optional | `[]` | 79 80 81<a id="rustfmt_toolchain"></a> 82 83## rustfmt_toolchain 84 85<pre> 86rustfmt_toolchain(<a href="#rustfmt_toolchain-name">name</a>, <a href="#rustfmt_toolchain-rustc">rustc</a>, <a href="#rustfmt_toolchain-rustc_lib">rustc_lib</a>, <a href="#rustfmt_toolchain-rustfmt">rustfmt</a>) 87</pre> 88 89A toolchain for [rustfmt](https://rust-lang.github.io/rustfmt/) 90 91**ATTRIBUTES** 92 93 94| Name | Description | Type | Mandatory | Default | 95| :------------- | :------------- | :------------- | :------------- | :------------- | 96| <a id="rustfmt_toolchain-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 97| <a id="rustfmt_toolchain-rustc"></a>rustc | The location of the `rustc` binary. Can be a direct source or a filegroup containing one item. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 98| <a id="rustfmt_toolchain-rustc_lib"></a>rustc_lib | The libraries used by rustc during compilation. | <a href="https://bazel.build/concepts/labels">Label</a> | optional | `None` | 99| <a id="rustfmt_toolchain-rustfmt"></a>rustfmt | The location of the `rustfmt` binary. Can be a direct source or a filegroup containing one item. | <a href="https://bazel.build/concepts/labels">Label</a> | required | | 100 101 102<a id="rustfmt_aspect"></a> 103 104## rustfmt_aspect 105 106<pre> 107rustfmt_aspect(<a href="#rustfmt_aspect-name">name</a>) 108</pre> 109 110This aspect is used to gather information about a crate for use in rustfmt and perform rustfmt checks 111 112Output Groups: 113 114- `rustfmt_checks`: Executes `rustfmt --check` on the specified target. 115 116The build setting `@rules_rust//:rustfmt.toml` is used to control the Rustfmt [configuration settings][cs] 117used at runtime. 118 119[cs]: https://rust-lang.github.io/rustfmt/ 120 121This aspect is executed on any target which provides the `CrateInfo` provider. However 122users may tag a target with `no-rustfmt` or `no-format` to have it skipped. Additionally, 123generated source files are also ignored by this aspect. 124 125**ASPECT ATTRIBUTES** 126 127 128 129**ATTRIBUTES** 130 131 132| Name | Description | Type | Mandatory | Default | 133| :------------- | :------------- | :------------- | :------------- | :------------- | 134| <a id="rustfmt_aspect-name"></a>name | A unique name for this target. | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required | | 135 136 137