From 8923b589bd42838842d8acb20e66637a6fee8765 Mon Sep 17 00:00:00 2001 From: Adam Gemmell Date: Wed, 28 Feb 2024 15:19:30 +0000 Subject: [PATCH] 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 https://github.com/rust-lang/wg-cargo-std-aware/issues/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 https://github.com/rust-lang/rust/issues/27242 https://github.com/rust-lang/rust/issues/103765). Note that the message says "platform" and "environment" because, since https://github.com/rust-lang/rust/pull/120232, libstd can be built for some JSON targets. This is still unsupported (all JSON targets probably should be unstable https://github.com/rust-lang/wg-cargo-std-aware/issues/90), but a JSON target with the right configuration should hopefully have some partial libstd support. I propose closing https://github.com/rust-lang/wg-cargo-std-aware/issues/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 https://github.com/rust-lang/wg-cargo-std-aware/issues/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. --- library/std/src/lib.rs | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/library/std/src/lib.rs b/library/std/src/lib.rs index 31a8711e0eb97..049edfc389e90 100644 --- a/library/std/src/lib.rs +++ b/library/std/src/lib.rs @@ -220,7 +220,16 @@ #![cfg_attr(feature = "miri-test-libstd", feature(rustc_private))] // #![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/",