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_analyzer.vm b/docs/rust_analyzer.vm
new file mode 100644
index 0000000..e366960
--- /dev/null
+++ b/docs/rust_analyzer.vm
@@ -0,0 +1,66 @@
+#[[
+## Overview
+
+For [non-Cargo projects](https://rust-analyzer.github.io/manual.html#non-cargo-based-projects),
+[rust-analyzer](https://rust-analyzer.github.io/) depends on a `rust-project.json` file at the
+root of the project that describes its structure. The `rust_analyzer` rule facilitates generating
+such a file.
+
+### Setup
+
+First, add the following to the `WORKSPACE` file:
+
+```python
+load("@rules_rust//tools/rust_analyzer:deps.bzl", "rust_analyzer_deps")
+
+rust_analyzer_deps()
+```
+
+Next, add the following lines to the `.bazelrc` file of your workspace:
+```
+build --repo_env=RULES_RUST_TOOLCHAIN_INCLUDE_RUSTC_SRCS=true
+```
+
+This will ensure rust source code is available to `rust-analyzer`. Users
+can also set `include_rustc_srcs = True` on any `rust_repository` or
+`rust_repositories` calls in the workspace but the environment variable
+has higher priority and can override the attribute.
+
+Finally, run `bazel run @rules_rust//tools/rust_analyzer:gen_rust_project`
+whenever dependencies change to regenerate the `rust-project.json` file. It
+should be added to `.gitignore` because it is effectively a build artifact.
+Once the `rust-project.json` has been generated in the project root,
+rust-analyzer can pick it up upon restart.
+
+#### VSCode
+
+To set this up using [VSCode](https://code.visualstudio.com/), users should first install the
+[rust_analyzer plugin](https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer).
+With that in place, the following task can be added to the `.vscode/tasks.json` file of the workspace
+to ensure a `rust-project.json` file is created and up to date when the editor is opened.
+
+```json
+{
+ "version": "2.0.0",
+ "tasks": [
+ {
+ "label": "Generate rust-project.json",
+ "command": "bazel",
+ "args": ["run", "@rules_rust//tools/rust_analyzer:gen_rust_project"],
+ "options": {
+ "cwd": "${workspaceFolder}"
+ },
+ "group": "build",
+ "problemMatcher": [],
+ "presentation": {
+ "reveal": "never",
+ "panel": "dedicated",
+ },
+ "runOptions": {
+ "runOn": "folderOpen"
+ }
+ },
+ ]
+}
+```
+]]#