Rollup merge of rust-lang#123360 - adamgemmell:dev/adagem01/restricte…

…d-std, r=ehuss

Document restricted_std

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 rust-lang#27242 rust-lang#103765).

Note that the message says "platform" and "environment" because, since rust-lang#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```

library/std/src/lib.rs

@@ -214,7 +214,16 @@
 //! [slice]: prim@slice
 
 #![cfg_attr(not(feature = "restricted-std"), stable(feature = "rust1", since = "1.0.0"))]
-#![cfg_attr(feature = "restricted-std", unstable(feature = "restricted_std", issue = "none"))]
+#![cfg_attr(
+    feature = "restricted-std",
+    unstable(
+        feature = "restricted_std",
+        issue = "none",
+        reason = "You have attempted to use a standard library built for a platform that it doesn't \
+            know how to support. Consider building it for a known environment, disabling it with \
+            `#![no_std]` or overriding this warning by enabling this feature".
+    )
+)]
 #![cfg_attr(not(bootstrap), rustc_preserve_ub_checks)]
 #![doc(
     html_playground_url = "https://play.rust-lang.org/",