Squashed 'third_party/rules_rust/' content from commit bf59038ca
git-subtree-dir: third_party/rules_rust
git-subtree-split: bf59038cac11798cbaef9f3bf965bad8182b97fa
Signed-off-by: Brian Silverman <bsilver16384@gmail.com>
Change-Id: I5a20e403203d670df467ea97dde9a4ac40339a8d
diff --git a/docs/rust_fmt.vm b/docs/rust_fmt.vm
new file mode 100644
index 0000000..47d5af0
--- /dev/null
+++ b/docs/rust_fmt.vm
@@ -0,0 +1,41 @@
+#[[
+## Overview
+]]#
+
+[Rustfmt][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][rsg] that
+has been formalized through the [style RFC process][rfcp]. A complete list of all
+configuration options can be found in the [Rustfmt GitHub Pages][rgp].
+
+
+#[[
+### 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 check can be added to your build phase using the [rustfmt_aspect](#rustfmt-aspect)
+aspect. Simply add the following to a `.bazelrc` file to enable this check.
+
+```text
+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//:rustfmt.toml` setting which determines the
+[configuration file][rgp] 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:
+
+```text
+build --@rules_rust//:rustfmt.toml=//:rustfmt.toml
+```
+
+[rustfmt]: https://github.com/rust-lang/rustfmt#readme
+[rsg]: https://github.com/rust-lang-nursery/fmt-rfcs/blob/master/guide/guide.md
+[rfcp]: https://github.com/rust-lang-nursery/fmt-rfcs
+[rgp]: https://rust-lang.github.io/rustfmt/