toolchain docs should mention issues with repository names
- Dominant language
- Java
- Stars
- 25.8k
- Forks
- 4.6k
- Avg merge
- 2d 20h
- Merged PRs (30d)
- 72
Description
The [toolchains documentation](https://docs.bazel.build/versions/master/toolchains.html) gives details on creating a toolchain and using it in the same repository. Due to the way Starlark handles loads and target equivalence, when a toolchain is used via an external repository, it must be referred to by the fully qualified label (including the repository) everywhere, including in the rule definitions and toolchain definitions.
This can be exemplified by the [rules_rust repo](https://github.com/bazelbuild/rules_rust) repo:
1. The WORKSPACE defines the repository name as `io_bazel_rules_rust`: https://github.com/bazelbuild/rules_rust/blob/master/WORKSPACE#L1
2. The rules refer to the toolchain type by a fully-qualified label: https://github.com/bazelbuild/rules_rust/blob/master/rust/private/rust.bzl#L207
3. Toolchain declarations also use the fully-qualified label: https://github.com/bazelbuild/rules_rust/blob/master/rust/repositories.bzl#L151
4. All users must import the rules under the name `io_bazel_rules_rust`.
The documentation should be set up to describe this.
Ideally, error-checking code in toolchain resolution would also at least mention this case, but that's very very tricky.
Contributor guide
Assessment
This issue has not been assessed yet.