Improve Toolchain documentation with recommendations and guidance
- Dominant language
- Java
- Stars
- 25.8k
- Forks
- 4.6k
- Avg merge
- 2d 20h
- Merged PRs (30d)
- 72
Description
### Page link:
https://bazel.build/extending/toolchains
### Problem description (include actual vs expected text, if applicable):
The Toolchains documentation is very abstract. For example, under _"Writing rules that use toolchains"_ it starts with the following text:
> Under the toolchain framework, instead of having rules depend directly on tools, they instead depend on toolchain types. A toolchain type is a simple target that represents a class of tools that serve the same role for different platforms. For instance, you can declare a type that represents the bar compiler:
In the examples it then uses `toolchain_type(name = "toolchain_type")`.
Neither the name `bar` nor `toolchain_type` is helpful. Those abstract examples make it hard to communicated what a good toolchain looks like.
What would I define type?
Would I define a single type?
Is there a situation where I should consider having more than one type?
What is a real world example for a type (other than being an abstraction)?
Complexity increases when platforms and transitions come into play. This can lead to questions that are unanswered and require help from subject experts. It seems that there is only one active expert in the community being able to answer those.
Example:
https://github.com/bazel-contrib/rules_nodejs/issues/3854
When researching the topic I had no idea `rules_nodejs` should be having two toolchain types.
The rules authors/maintainers also didn't seem to know that.
`rules_java` has multiple toolchain tupes. But in contrast, `rules_go` does not need separate toolchain types.
From communication in Slack it became obvious (because it produces ready to run binaries):
> Because we only have the "exec" flavor of a toolchain in rules_go: We use a Go SDK in a build rule to compile code. We don't have a use case for, say, building a container image that contains a Go SDK to be run in prod. If we needed that, we would need a separate toolchain type
>
> This is a common complexity of languages that need an interpreter. Even rules_java got this wrong for a long time and it took quite a bit of work to unravel all the false assumptions. As a result, it now has three (!) distinct toolchain types.
>
> https://github.com/bazelbuild/rules_java/blob/52aa53a7b7e56a4e545fbda2323db181d3c8ee3d/toolchains/BUILD#L51
The [link to the rules_java comment](https://github.com/bazelbuild/rules_java/blob/52aa53a7b7e56a4e545fbda2323db181d3c8ee3d/toolchains/BUILD#L51-L88) is really good info.
### Any other information you'd like to share?
A good documentation should communicate not only how to implement things but also how to design these. Bonus points if the examples aren't abstract foos and bars but real world examples which are familiar to readers.
Contributor guide
Research direction
Start with the Toolchains documentation at bazel.build/extending/toolchains, especially “Writing rules that use toolchains,” then review the linked rules_java BUILD comment and rules_nodejs issue 3854. Done means the page explains how to design toolchain types and includes concrete, real-world guidance beyond the abstract foo and bar examples.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go, java, nodejs
- Domain
- build-system, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100