Skip to content

Commit 1a19065

Browse files
authored
[Doc] Improve documentation on toolchain registration with bzlmod (#3430)
Hi, this is referencing issue #2973 , i'm sorry i kinda forgot this was open too. Let me know if it is clear or if it needs modification. Parallelly, i removed refernces to a no longer existing file `flatten.md`. Is this correct, or do you want to open a separate issue/pr? Thanks!
1 parent 646b9a5 commit 1a19065

File tree

2 files changed

+38
-11
lines changed

2 files changed

+38
-11
lines changed

docs/src/index.md

Lines changed: 38 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ Note that rules_rust bzlmod support is still a work in progress. Most features s
2020
To use `rules_rust` in a project using bzlmod, add the following to your `MODULE.bazel` file:
2121

2222
```python
23-
bazel_dep(name = "rules_rust", version = "0.59.0")
23+
bazel_dep(name = "rules_rust", version = "0.61.0")
2424
```
2525

2626
Don't forget to substitute in your desired release's version number.
@@ -51,7 +51,38 @@ Don't forget to substitute in your desired release's version number and integrit
5151

5252
## Specifying Rust version
5353

54-
To build with a particular version of the Rust compiler, pass that version to [`rust_register_toolchains`](flatten.md#rust_register_toolchains):
54+
### Bzlmod
55+
56+
To use a particular version of the Rust compiler, pass that version to the `toolchain` method of the `rust` extension, like this:
57+
58+
```python
59+
rust = use_extension("@rules_rust//rust:extensions.bzl", "rust")
60+
rust.toolchain(
61+
edition = "2024",
62+
versions = [ "1.85.0" ],
63+
)
64+
```
65+
66+
As well as an exact version, `versions` can accept `nightly/{iso_date}` and `beta/{iso_date}` strings for toolchains from different release channels, as in
67+
68+
```python
69+
rust.toolchain(
70+
edition = "2021",
71+
versions = [ "nightly/1.85.0" ],
72+
)
73+
```
74+
75+
By default, a `stable` and `nightly` toolchain will be registered if no `toolchain` method is called (and thus no specific versions are registered). However, if only 1 version is passed and it is from the `nightly` or `beta` release channels (i.e. __not__ `stable`), then the following build setting flag must be present, either on the command line or set in the project's `.bazelrc` file:
76+
77+
```text
78+
build --@rules_rust//rust/toolchain/channel=nightly
79+
```
80+
81+
Failure to do so will result in rules attempting to match a `stable` toolchain when one was not registered, thus raising an error.
82+
83+
### WORKSPACE
84+
85+
To build with a particular version of the Rust compiler when using a WORKSPACE file, pass that version to `rust_register_toolchains`:
5586

5687
```python
5788
rust_register_toolchains(
@@ -62,7 +93,7 @@ rust_register_toolchains(
6293
)
6394
```
6495

65-
As well as an exact version, `versions` can accept `nightly/{iso_date}` and `beta/{iso_date}` strings for toolchains from different release channels.
96+
Like in the Bzlmod approach, as well as an exact version, `versions` can accept `nightly/{iso_date}` and `beta/{iso_date}` strings for toolchains from different release channels.
6697

6798
```python
6899
rust_register_toolchains(
@@ -73,15 +104,15 @@ rust_register_toolchains(
73104
)
74105
```
75106

76-
By default, a `stable` and `nightly` toolchain will be registered if no versions are passed to `rust_register_toolchains`. However,
77-
if only 1 version is passed and it is from the `nightly` or `beta` release channels (i.e. __not__ `stable`), then a build setting must
78-
also be set in the project's `.bazelrc` file.
107+
Here too a `stable` and `nightly` toolchain will be registered by default if no versions are passed to `rust_register_toolchains`. However,
108+
if only 1 version is passed and it is from the `nightly` or `beta` release channels (i.e. __not__ `stable`), then the following build setting flag must
109+
also be set either in the command line or in the project's `.bazelrc` file.
79110

80111
```text
81112
build --@rules_rust//rust/toolchain/channel=nightly
82113
```
83114

84-
Failure to do so will result in rules attempting to match a `stable` toolchain when one was not registered.
115+
Failure to do so will result in rules attempting to match a `stable` toolchain when one was not registered, thus raising an error.
85116

86117
## Supported bazel versions
87118

docs/src/rules.md

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,3 @@
1717
- [rust_prost](rust_prost.md): rules for generating [protobuf](https://developers.google.com/protocol-buffers) and [gRPC](https://grpc.io) stubs using [prost](https://github.com/tokio-rs/prost).
1818
- [rust_protobuf](rust_protobuf.md): rules for generating [protobuf](https://developers.google.com/protocol-buffers) and [gRPC](https://grpc.io) stubs with [rust-protobuf](https://github.com/stepancheg/rust-protobuf/)
1919
- [rust_wasm_bindgen](rust_wasm_bindgen.md): rules for generating [WebAssembly](https://www.rust-lang.org/what/wasm) bindings.
20-
21-
## Full API
22-
23-
You can also browse the [full API in one page](flatten.md).

0 commit comments

Comments
 (0)