document RUSTC_BOOTSTRAP, RUSTC_OVERRIDE_VERSION_STRING, and -Z allow-features in the unstable book

Author: jyn514

src/doc/unstable-book/src/compiler-flags/allow-features.md

@@ -0,0 +1,14 @@
+# `allow-features`
+
+This feature is perma-unstable and has no tracking issue.
+
+----
+
+This flag allows limiting the features which can be enabled with `#![feature(...)]` attributes.
+By default, all features are allowed on nightly and no features are allowed on stable or beta (but see [`RUSTC_BOOTSTRAP`]).
+
+Features are comma-separated, for example `-Z allow-features=ffi_pure,f16`.
+If the flag is present, any feature listed will be allowed and any feature not listed will be disallowed.
+Any unrecognized feature is ignored.
+
+[`RUSTC_BOOTSTRAP`]: ./rustc-bootstrap.html

src/doc/unstable-book/src/compiler-flags/rustc-bootstrap.md

@@ -0,0 +1,56 @@
+# `RUSTC_BOOTSTRAP`
+
+This feature is perma-unstable and has no tracking issue.
+
+----
+
+The `RUSTC_BOOTSTRAP` environment variable tells rustc to act as if it is a nightly compiler;
+in particular, it allows `#![feature(...)]` attributes and `-Z` flags even on the stable release channel.
+
+Setting `RUSTC_BOOTSTRAP=1` instructs rustc to enable this for all crates.
+Setting `RUSTC_BOOTSTRAP=crate_name` instructs rustc to only apply this to crates named `crate_name`.
+Setting `RUSTC_BOOTSTRAP=-1` instructs rustc to act as if it is a stable compiler, even on the nightly release channel.
+Cargo disallows setting `cargo::rustc-env=RUSTC_BOOTSTRAP` in build scripts.
+Build systems can limit the features they enable with [`-Z allow-features=feature1,feature2`][Z-allow-features].
+Crates can fully opt out of unstable features by using [`#![forbid(unstable_features)]`][unstable-features] at the crate root (or any other way of enabling lints, such as `-F unstable-features`).
+
+[Z-allow-features]: ./allow-features.html
+[unstable-features]: ../../rustc/lints/listing/allowed-by-default.html#unstable-features
+
+## Why does this environment variable exist?
+
+`RUSTC_BOOTSTRAP`, as the name suggests, is used for bootstrapping the compiler from an earlier version.
+In particular, nightly is built with beta, and beta is built with stable.
+Since the standard library and compiler both use unstable features, `RUSTC_BOOTSTRAP` is required so that we can use the previous version to build them.
+
+## Why is this environment variable so easy to use for people not in the rust project?
+
+Originally, `RUSTC_BOOTSTRAP` required passing in a hash of the previous compiler version, to discourage using it for any purpose other than bootstrapping.
+That constraint was later relaxed; see <https://github.com/rust-lang/rust/issues/36548> for the discussion that happened at that time.
+
+People have at various times proposed re-adding the technical constraints.
+However, doing so is extremely disruptive for several major projects that we very much want to keep using the latest stable toolchain version, such as Firefox, Rust for Linux, and Chromium.
+We continue to allow `RUSTC_BOOTSTRAP` until we can come up with an alternative that does not disrupt our largest constituents.
+
+## Stability policy
+
+Despite being usable on stable, this is an unstable feature.
+Like any other unstable feature, we reserve the right to change or remove this feature in the future, as well as any other unstable feature that it enables.
+Using this feature opts you out of the normal stability/backwards compatibility guarantee of stable.
+
+Although we do not take technical measures to prevent it from being used, we strongly discourage using this feature.
+If at all possible, please contribute to stabilizing the features you care about instead of bypassing the Rust project's stability policy.
+
+For library crates, we especially discourage the use of this feature.
+The crates depending on you do not know that you use this feature, have little recourse if it breaks, and can be used in contexts that are hard to predict.
+
+For libraries that do use this feature, please document the versions you support (including a *maximum* as well as minimum version), and a mechanism to disable it.
+If you do not have a mechanism to disable the use of `RUSTC_BOOTSTRAP`, consider removing its use altogether, such that people can only use your library if they are already using a nightly toolchain.
+This leaves the choice of whether to opt-out of Rust's stability guarantees up to the end user building their code.
+
+## History
+
+- [Allowed without a hash](https://github.com/rust-lang/rust/pull/37265) ([discussion](https://github.com/rust-lang/rust/issues/36548))
+- [Extended to crate names](https://github.com/rust-lang/rust/pull/77802) ([discussion](https://github.com/rust-lang/cargo/issues/7088))
+- [Disallowed for build scripts](https://github.com/rust-lang/cargo/pull/9181) ([discussion](https://github.com/rust-lang/compiler-team/issues/350))
+- [Extended to emulate stable](https://github.com/rust-lang/rust/pull/132993) ([discussion](https://github.com/rust-lang/rust/issues/123404))

src/doc/unstable-book/src/compiler-flags/rustc-override-version-string.md

@@ -0,0 +1,39 @@
+# `RUSTC_OVERRIDE_VERSION_STRING`
+
+This feature is perma-unstable and has no tracking issue.
+
+----
+
+The `RUSTC_OVERRIDE_VERSION_STRING` environment variable overrides the version reported by `rustc --version`. For example:
+
+```console
+$ rustc --version
+rustc 1.87.0-nightly (43f0014ef 2025-03-25)
+$ env RUSTC_OVERRIDE_VERSION_STRING=1.81.0-nightly rustc --version
+rustc 1.81.0-nightly
+```
+
+Note that the version string is completely overwritten; i.e. rustc discards commit hash and commit date information unless it is explicitly included in the environment variable. The string only applies to the "release" part of the version; for example:
+```console
+$ RUSTC_OVERRIDE_VERSION_STRING="1.81.0-nightly (aaaaaaaaa 2025-03-22)" rustc -vV
+rustc 1.81.0-nightly (aaaaaaaaa 2025-03-22)
+binary: rustc
+commit-hash: 43f0014ef0f242418674f49052ed39b70f73bc1c
+commit-date: 2025-03-25
+host: x86_64-unknown-linux-gnu
+release: 1.81.0-nightly (aaaaaaaaa 2025-03-22)
+LLVM version: 20.1.1
+```
+
+Note here that `commit-hash` and `commit-date` do not match the values in the string, and `release` includes the fake hash and date.
+
+This variable has no effect on whether or not unstable features are allowed to be used. It only affects the output of `--version`.
+
+## Why does this environment variable exist?
+
+Various library crates have incomplete or incorrect feature detection.
+This environment variable allows bisecting crates that do incorrect detection with `version_check::supports_feature`.
+
+This is not intended to be used for any other case (and, except for bisection, is not particularly useful).
+
+See <https://github.com/rust-lang/rust/pull/124339> for further discussion.