Added rust_analyzer_toolchain and repository rules for creating one (#1455)

* Added `rust_analyzer_toolchain` and repository rules for creating one

* Regenerate documentation

* Update rust/repositories.bzl

Co-authored-by: Daniel Wagner-Hall <[email protected]>

* Updated rust_analyzer_toolchain export

* Fixed rust_analyzer_toolchain_repository rule

Co-authored-by: Daniel Wagner-Hall <[email protected]>

Author: UebelAndre

WORKSPACE.bazel

@@ -4,7 +4,7 @@ load("@rules_rust//rust:repositories.bzl", "rules_rust_dependencies", "rust_regi
 
 rules_rust_dependencies()
 
-rust_register_toolchains(include_rustc_srcs = True)
+rust_register_toolchains()
 
 load("@rules_rust//crate_universe:repositories.bzl", "crate_universe_dependencies")
 

docs/BUILD.bazel

@@ -72,6 +72,7 @@ PAGES = dict([
         header_template = ":rust_analyzer.vm",
         symbols = [
             "rust_analyzer_aspect",
+            "rust_analyzer_toolchain",
         ],
     ),
     page(

docs/flatten.md

@@ -14,6 +14,7 @@
 * [incompatible_flag](#incompatible_flag)
 * [rules_rust_dependencies](#rules_rust_dependencies)
 * [rust_analyzer_aspect](#rust_analyzer_aspect)
+* [rust_analyzer_toolchain](#rust_analyzer_toolchain)
 * [rust_binary](#rust_binary)
 * [rust_bindgen](#rust_bindgen)
 * [rust_bindgen_dependencies](#rust_bindgen_dependencies)
@@ -177,6 +178,25 @@ A rule defining an incompatible flag.
 | <a id="incompatible_flag-issue"></a>issue |  The link to the github issue associated with this flag   | String | required |  |
 
 
+<a id="rust_analyzer_toolchain"></a>
+
+## rust_analyzer_toolchain
+
+<pre>
+rust_analyzer_toolchain(<a href="#rust_analyzer_toolchain-name">name</a>, <a href="#rust_analyzer_toolchain-rustc_srcs">rustc_srcs</a>)
+</pre>
+
+A toolchain for [rust-analyzer](https://rust-analyzer.github.io/).
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="rust_analyzer_toolchain-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
+| <a id="rust_analyzer_toolchain-rustc_srcs"></a>rustc_srcs |  The source code of rustc.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required |  |
+
+
 <a id="rust_binary"></a>
 
 ## rust_binary
@@ -1168,8 +1188,8 @@ See @rules_rust//rust:repositories.bzl for examples of defining the @rust_cpuX r
 ## rust_toolchain_repository_proxy
 
 <pre>
-rust_toolchain_repository_proxy(<a href="#rust_toolchain_repository_proxy-name">name</a>, <a href="#rust_toolchain_repository_proxy-exec_compatible_with">exec_compatible_with</a>, <a href="#rust_toolchain_repository_proxy-exec_triple">exec_triple</a>, <a href="#rust_toolchain_repository_proxy-parent_workspace_name">parent_workspace_name</a>,
-                                <a href="#rust_toolchain_repository_proxy-repo_mapping">repo_mapping</a>, <a href="#rust_toolchain_repository_proxy-target_compatible_with">target_compatible_with</a>, <a href="#rust_toolchain_repository_proxy-target_triple">target_triple</a>)
+rust_toolchain_repository_proxy(<a href="#rust_toolchain_repository_proxy-name">name</a>, <a href="#rust_toolchain_repository_proxy-exec_compatible_with">exec_compatible_with</a>, <a href="#rust_toolchain_repository_proxy-repo_mapping">repo_mapping</a>, <a href="#rust_toolchain_repository_proxy-target_compatible_with">target_compatible_with</a>,
+                                <a href="#rust_toolchain_repository_proxy-toolchain">toolchain</a>, <a href="#rust_toolchain_repository_proxy-toolchain_type">toolchain_type</a>)
 </pre>
 
 Generates a toolchain-bearing repository that declares the toolchains from some other rust_toolchain_repository.
@@ -1180,12 +1200,11 @@ Generates a toolchain-bearing repository that declares the toolchains from some
 | Name  | Description | Type | Mandatory | Default |
 | :------------- | :------------- | :------------- | :------------- | :------------- |
 | <a id="rust_toolchain_repository_proxy-name"></a>name |  A unique name for this repository.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
-| <a id="rust_toolchain_repository_proxy-exec_compatible_with"></a>exec_compatible_with |  TODO   | List of strings | optional | [] |
-| <a id="rust_toolchain_repository_proxy-exec_triple"></a>exec_triple |  The Rust-style target triple for the compilation platform   | String | required |  |
-| <a id="rust_toolchain_repository_proxy-parent_workspace_name"></a>parent_workspace_name |  The name of the other rust_toolchain_repository   | String | required |  |
+| <a id="rust_toolchain_repository_proxy-exec_compatible_with"></a>exec_compatible_with |  A list of constraints for the execution platform for this toolchain.   | List of strings | optional | [] |
 | <a id="rust_toolchain_repository_proxy-repo_mapping"></a>repo_mapping |  A dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.&lt;p&gt;For example, an entry <code>"@foo": "@bar"</code> declares that, for any time this repository depends on <code>@foo</code> (such as a dependency on <code>@foo//some:target</code>, it should actually resolve that dependency within globally-declared <code>@bar</code> (<code>@bar//some:target</code>).   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | required |  |
-| <a id="rust_toolchain_repository_proxy-target_compatible_with"></a>target_compatible_with |  TODO   | List of strings | optional | [] |
-| <a id="rust_toolchain_repository_proxy-target_triple"></a>target_triple |  The Rust-style target that this compiler builds for   | String | required |  |
+| <a id="rust_toolchain_repository_proxy-target_compatible_with"></a>target_compatible_with |  A list of constraints for the target platform for this toolchain.   | List of strings | optional | [] |
+| <a id="rust_toolchain_repository_proxy-toolchain"></a>toolchain |  The name of the toolchain implementation target.   | String | required |  |
+| <a id="rust_toolchain_repository_proxy-toolchain_type"></a>toolchain_type |  The toolchain type of the toolchain to declare   | String | required |  |
 
 
 <a id="rust_toolchain_tools_repository"></a>
@@ -1200,7 +1219,7 @@ rust_toolchain_tools_repository(<a href="#rust_toolchain_tools_repository-name">
 
 Composes a single workspace containing the toolchain components for compiling on a given platform to a series of target platforms.
 
-A given instance of this rule should be accompanied by a rust_toolchain_repository_proxy invocation to declare its toolchains to Bazel; the indirection allows separating toolchain selection from toolchain fetching.
+A given instance of this rule should be accompanied by a toolchain_repository_proxy invocation to declare its toolchains to Bazel; the indirection allows separating toolchain selection from toolchain fetching.
 
 **ATTRIBUTES**
 
@@ -1834,9 +1853,9 @@ N.B. A "proxy repository" is needed to allow for registering the toolchain (with
 | <a id="rust_toolchain_repository-target_triple"></a>target_triple |  The Rust-style target to build for.   |  none |
 | <a id="rust_toolchain_repository-exec_compatible_with"></a>exec_compatible_with |  A list of constraints for the execution platform for this toolchain.   |  <code>None</code> |
 | <a id="rust_toolchain_repository-target_compatible_with"></a>target_compatible_with |  A list of constraints for the target platform for this toolchain.   |  <code>None</code> |
-| <a id="rust_toolchain_repository-include_rustc_srcs"></a>include_rustc_srcs |  Whether to download rustc's src code. This is required in order to use rust-analyzer support. Defaults to False.   |  <code>False</code> |
-| <a id="rust_toolchain_repository-iso_date"></a>iso_date |  The date of the tool. Defaults to None.   |  <code>None</code> |
-| <a id="rust_toolchain_repository-rustfmt_version"></a>rustfmt_version |  The version of rustfmt to be associated with the toolchain. Defaults to None.   |  <code>None</code> |
+| <a id="rust_toolchain_repository-include_rustc_srcs"></a>include_rustc_srcs |  Whether to download rustc's src code. This is required in order to use rust-analyzer support.   |  <code>False</code> |
+| <a id="rust_toolchain_repository-iso_date"></a>iso_date |  The date of the tool.   |  <code>None</code> |
+| <a id="rust_toolchain_repository-rustfmt_version"></a>rustfmt_version |  The version of rustfmt to be associated with the toolchain.   |  <code>None</code> |
 | <a id="rust_toolchain_repository-edition"></a>edition |  The rust edition to be used by default (2015, 2018, or 2021). If absent, every rule is required to specify its <code>edition</code> attribute.   |  <code>None</code> |
 | <a id="rust_toolchain_repository-dev_components"></a>dev_components |  Whether to download the rustc-dev components. Requires version to be "nightly". Defaults to False.   |  <code>False</code> |
 | <a id="rust_toolchain_repository-sha256s"></a>sha256s |  A dict associating tool subdirectories to sha256 hashes. See [rust_repositories](#rust_repositories) for more details.   |  <code>None</code> |

docs/rust_analyzer.md

@@ -2,6 +2,7 @@
 # Rust Analyzer
 
 * [rust_analyzer_aspect](#rust_analyzer_aspect)
+* [rust_analyzer_toolchain](#rust_analyzer_toolchain)
 
 
 ## Overview
@@ -13,30 +14,38 @@ such a file.
 
 ### Setup
 
-First, add the following to the `WORKSPACE` file:
+First, ensure `rules_rust` is setup in your workspace. By default, `rust_register_toolchains` will
+ensure a [rust_analyzer_toolchain](#rust_analyzer_toolchain) is registered within the WORKSPACE.
+
+Next, load the dependencies for the `rust-project.json` generator tool:
 
 ```python
 load("@rules_rust//tools/rust_analyzer:deps.bzl", "rust_analyzer_dependencies")
 
 rust_analyzer_dependencies()
 ```
 
-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.
 
+For users who do not use `rust_register_toolchains` to register toolchains, the following can be added
+to their WORKSPACE to register a `rust_analyzer_toolchain`. Please make sure the Rust version used in
+this toolchain matches the version used by the currently registered toolchain or the sources/documentation
+# will not match what's being compiled with and can lead to confusing results.
+
+```python
+load("@rules_rust//rust:repositories.bzl", "rust_analyzer_toolchain_repository")
+
+register_toolchains(rust_analyzer_toolchain_repository(
+    name = "rust_analyzer_toolchain",
+    # This should match the currently registered toolchain.
+    version = "1.62.0",
+))
+```
+
 #### VSCode
 
 To set this up using [VSCode](https://code.visualstudio.com/), users should first install the
@@ -70,6 +79,25 @@ to ensure a `rust-project.json` file is created and up to date when the editor i
 ```
 
 
+<a id="rust_analyzer_toolchain"></a>
+
+## rust_analyzer_toolchain
+
+<pre>
+rust_analyzer_toolchain(<a href="#rust_analyzer_toolchain-name">name</a>, <a href="#rust_analyzer_toolchain-rustc_srcs">rustc_srcs</a>)
+</pre>
+
+A toolchain for [rust-analyzer](https://rust-analyzer.github.io/).
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="rust_analyzer_toolchain-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
+| <a id="rust_analyzer_toolchain-rustc_srcs"></a>rustc_srcs |  The source code of rustc.   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required |  |
+
+
 <a id="rust_analyzer_aspect"></a>
 
 ## rust_analyzer_aspect

docs/rust_analyzer.vm

@@ -8,30 +8,38 @@ such a file.
 
 ### Setup
 
-First, add the following to the `WORKSPACE` file:
+First, ensure `rules_rust` is setup in your workspace. By default, `rust_register_toolchains` will
+ensure a [rust_analyzer_toolchain](#rust_analyzer_toolchain) is registered within the WORKSPACE.
+
+Next, load the dependencies for the `rust-project.json` generator tool:
 
 ```python
 load("@rules_rust//tools/rust_analyzer:deps.bzl", "rust_analyzer_dependencies")
 
 rust_analyzer_dependencies()
 ```
 
-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.
 
+For users who do not use `rust_register_toolchains` to register toolchains, the following can be added
+to their WORKSPACE to register a `rust_analyzer_toolchain`. Please make sure the Rust version used in
+this toolchain matches the version used by the currently registered toolchain or the sources/documentation
+# will not match what's being compiled with and can lead to confusing results.
+
+```python
+load("@rules_rust//rust:repositories.bzl", "rust_analyzer_toolchain_repository")
+
+register_toolchains(rust_analyzer_toolchain_repository(
+    name = "rust_analyzer_toolchain",
+    # This should match the currently registered toolchain.
+    version = "1.62.0",
+))
+```
+
 #### VSCode
 
 To set this up using [VSCode](https://code.visualstudio.com/), users should first install the