xref: /aosp_15_r20/external/bazelbuild-rules_rust/docs/rust_analyzer.md (revision d4726bddaa87cc4778e7472feed243fa4b6c267f) 
1<!-- Generated with Stardoc: http://skydoc.bazel.build -->
2# Rust Analyzer
3
4* [rust_analyzer_aspect](#rust_analyzer_aspect)
5* [rust_analyzer_toolchain](#rust_analyzer_toolchain)
6
7
8## Overview
9
10For [non-Cargo projects](https://rust-analyzer.github.io/manual.html#non-cargo-based-projects),
11[rust-analyzer](https://rust-analyzer.github.io/) depends on a `rust-project.json` file at the
12root of the project that describes its structure. The `rust_analyzer` rule facilitates generating
13such a file.
14
15### Setup
16
17First, ensure `rules_rust` is setup in your workspace. By default, `rust_register_toolchains` will
18ensure a [rust_analyzer_toolchain](#rust_analyzer_toolchain) is registered within the WORKSPACE.
19
20Next, load the dependencies for the `rust-project.json` generator tool:
21
22```python
23load("@rules_rust//tools/rust_analyzer:deps.bzl", "rust_analyzer_dependencies")
24
25rust_analyzer_dependencies()
26```
27
28Finally, run `bazel run @rules_rust//tools/rust_analyzer:gen_rust_project`
29whenever dependencies change to regenerate the `rust-project.json` file. It
30should be added to `.gitignore` because it is effectively a build artifact.
31Once the `rust-project.json` has been generated in the project root,
32rust-analyzer can pick it up upon restart.
33
34For users who do not use `rust_register_toolchains` to register toolchains, the following can be added
35to their WORKSPACE to register a `rust_analyzer_toolchain`. Please make sure the Rust version used in
36this toolchain matches the version used by the currently registered toolchain or the sources/documentation
37will not match what's being compiled with and can lead to confusing results.
38
39```python
40load("@rules_rust//rust:repositories.bzl", "rust_analyzer_toolchain_repository")
41
42register_toolchains(rust_analyzer_toolchain_repository(
43    name = "rust_analyzer_toolchain",
44    # This should match the currently registered toolchain.
45    version = "1.63.0",
46))
47```
48
49#### VSCode
50
51To set this up using [VSCode](https://code.visualstudio.com/), users should first install the
52[rust_analyzer plugin](https://marketplace.visualstudio.com/items?itemName=matklad.rust-analyzer).
53With that in place, the following task can be added to the `.vscode/tasks.json` file of the workspace
54to ensure a `rust-project.json` file is created and up to date when the editor is opened.
55
56```json
57{
58    "version": "2.0.0",
59    "tasks": [
60        {
61            "label": "Generate rust-project.json",
62            "command": "bazel",
63            "args": ["run", "@rules_rust//tools/rust_analyzer:gen_rust_project"],
64            "options": {
65                "cwd": "${workspaceFolder}"
66            },
67            "group": "build",
68            "problemMatcher": [],
69            "presentation": {
70                "reveal": "never",
71                "panel": "dedicated",
72            },
73            "runOptions": {
74                "runOn": "folderOpen"
75            }
76        },
77    ]
78}
79```
80
81#### Alternative vscode option (prototype)
82
83Add the following to your bazelrc:
84```
85build --@rules_rust//:output_diagnostics=true --output_groups=+rust_lib_rustc_output,+rust_metadata_rustc_output
86```
87
88Then you can use a prototype [rust-analyzer plugin](https://marketplace.visualstudio.com/items?itemName=MattStark.bazel-rust-analyzer) that automatically collects the outputs whenever you recompile.
89
90
91
92<a id="rust_analyzer_toolchain"></a>
93
94## rust_analyzer_toolchain
95
96<pre>
97rust_analyzer_toolchain(<a href="#rust_analyzer_toolchain-name">name</a>, <a href="#rust_analyzer_toolchain-proc_macro_srv">proc_macro_srv</a>, <a href="#rust_analyzer_toolchain-rustc">rustc</a>, <a href="#rust_analyzer_toolchain-rustc_srcs">rustc_srcs</a>)
98</pre>
99
100A toolchain for [rust-analyzer](https://rust-analyzer.github.io/).
101
102**ATTRIBUTES**
103
104
105| Name  | Description | Type | Mandatory | Default |
106| :------------- | :------------- | :------------- | :------------- | :------------- |
107| <a id="rust_analyzer_toolchain-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
108| <a id="rust_analyzer_toolchain-proc_macro_srv"></a>proc_macro_srv |  The path to a `rust_analyzer_proc_macro_srv` binary.   | <a href="https://bazel.build/concepts/labels">Label</a> | optional |  `None`  |
109| <a id="rust_analyzer_toolchain-rustc"></a>rustc |  The path to a `rustc` binary.   | <a href="https://bazel.build/concepts/labels">Label</a> | required |  |
110| <a id="rust_analyzer_toolchain-rustc_srcs"></a>rustc_srcs |  The source code of rustc.   | <a href="https://bazel.build/concepts/labels">Label</a> | required |  |
111
112
113<a id="rust_analyzer_aspect"></a>
114
115## rust_analyzer_aspect
116
117<pre>
118rust_analyzer_aspect(<a href="#rust_analyzer_aspect-name">name</a>)
119</pre>
120
121Annotates rust rules with RustAnalyzerInfo later used to build a rust-project.json
122
123**ASPECT ATTRIBUTES**
124
125
126| Name | Type |
127| :------------- | :------------- |
128| deps| String |
129| proc_macro_deps| String |
130| crate| String |
131| actual| String |
132| proto| String |
133
134
135**ATTRIBUTES**
136
137
138| Name  | Description | Type | Mandatory | Default |
139| :------------- | :------------- | :------------- | :------------- | :------------- |
140| <a id="rust_analyzer_aspect-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/concepts/labels#target-names">Name</a> | required |  |
141
142
143