Document restricted_std

[adamgemmell]

This PR aims to pin down exactly what restricted_std is meant to achieve and what it isn't.

This commit fixes rust-lang/wg-cargo-std-aware#87 by explaining why the error appears and what the choices the user has. The error describes how std cannot function without knowing about some form of OS/platform support. Any features of std that work without an OS should be moved to core/alloc (see #27242 #103765).

Note that the message says "platform" and "environment" because, since #120232, libstd can be built for some JSON targets. This is still unsupported (all JSON targets probably should be unstable rust-lang/wg-cargo-std-aware#90), but a JSON target with the right configuration should hopefully have some partial libstd support.

I propose closing rust-lang/wg-cargo-std-aware#69 as "Won't fix" since any support of std without properly configured os, vendor or env fields is very fragile considering future upgrades of Rust or dependencies. In addition there's no likely path to it being fixed long term (making std buildable for all targets being the only solution). This is distinct from tier 3 platforms with limited std support implemented (and as such aren't restricted_std) because these platforms can conceptually work in the future and std support should mainly improve over time.

The alternative to closing rust-lang/wg-cargo-std-aware#69 is a new crate feature for std which escapes the restricted_std mechanism in build.rs. It could be used with the -Zbuild-std-features flag if we keep it permanently unstable, which I hope we can do anyway. A minor side-effect in this scenario is that std wouldn't be marked as unstable if documentation for it were generated with build-std.

cc @ehuss

[rustbot]

r? @Amanieu

rustbot has assigned @Amanieu.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[Amanieu]

r? @ehuss

[ehuss]

Thanks! I'm still not sure what the long-term solution will be here, particularly since I think this will be a common problem. There might need to be other things like explicit statements of compatibility in Cargo.toml, or having rustc know and report when a platform has std support. I don't know what that will ultimately look like.

This is a definite improvement, though!

@bors r+ rollup

[bors]

📌 Commit 8923b58 has been approved by ehuss

It is now in the queue for this repository.

[adamgemmell]

@ehuss Makes sense. It looks like the target spec recently gained a mechanism to report whether it supports std. Maybe the best path forwards then is to use that.

If we do that, I think restricted_std should stay in case a JSON target says it supports std but doesn't set it's os/env fields to something std knows about. In that case #69 could be closed with the answer "use a different target" or "edit your JSON spec"