Warn users of Tier 2 platforms, and explain what that means

[ethulhu]

TL;DR: Please notify users of Tier 2 platforms a) that it is a Tier 2 platform, and b) what that means.

Describe the problem you are trying to solve

• I have an AArch64 MacBook.
• I tried to use rustup doc, which failed because the files were not there.
• I tried to use rustup component add rust-docs, which failed because toolchain 'stable-aarch64-apple-darwin' does not contain component 'rust-docs' for target 'aarch64-apple-darwin'; did you mean 'rustc-docs'?.
• After much searching, I found a forum post saying that "Tier 2 platforms do not build documentation".
• I followed the link and confirmed that AArch64 macOS is indeed Tier 2. However, that link does not reiterate under the Tier 2 heading that documentation is not available.

Describe the solution you'd like

1. An explicit note on the Platform Support page that Tier 2 does not get documentation.

2. Some kind of notice to the user to explain what's going on, for example:

   % rustup doc
   error: couldn't open browser: command 'open' did not execute successfully; exit status: 1
   The file /Users/eth/.rustup/toolchains/stable-aarch64-apple-darwin/share/doc/rust/html/index.html does not exist.
   
   Have you installed the 'rust-docs' component?

   or

   % rustup component add rust-docs
   error: toolchain 'stable-aarch64-apple-darwin' does not contain component 'rust-docs' for target 'aarch64-apple-darwin'; did you mean 'rustc-docs'?
   
   note: 'aarch64-apple-darwin' is a Tier 2 platform, and so the 'rust-docs' component is not available. Please see https://doc.rust-lang.org/rustc/platform-support.html for more information.

[kinnison]

For us to be able to explain the platform tier, that information would need to be exported to us in the channel metadata.

@pietroalbini do you think we might put something together to allow rustup to indicate tier levels on toolchain installation? We could just include the tier data as another table in the channel toml perhaps?

[pietroalbini]

I don't think I'll have the time to think about an implementation for this, but it'd be nice to include the information somehow in manifests :)

[jyn514]

An explicit note on the Platform Support page that Tier 2 does not get documentation.

You can do this by making a PR to rust-lang/rust, the relevant code is https://github.com/rust-lang/rust/blob/master/src/doc/rustc/src/platform-support.md#tier-2.

[jyn514]

For us to be able to explain the platform tier, that information would need to be exported to us in the channel metadata.

Another alternative is, if rustup doc fails, to see if the rust-docs component exists, and if not mention that it's not built for all targets.

[amalik18]

@rustbot claim

[amalik18]

PR: rust-lang/rust#87677

[amalik18]

PR has been merged. Please close.

[workingjubilee]

This has 2 parts to it, I believe there is no Rustup-side warning yet.