rustc-dev-guide: document BOOTSTRAP_LOG and bootstrap tracing setup

Author: jieyouxu

src/doc/rustc-dev-guide/src/SUMMARY.md

@@ -75,6 +75,7 @@
 - [Prologue](./building/bootstrapping/intro.md)
 - [What Bootstrapping does](./building/bootstrapping/what-bootstrapping-does.md)
 - [How Bootstrap does it](./building/bootstrapping/how-bootstrap-does-it.md)
+- [`tracing` in bootstrap](./building/bootstrapping/bootstrap-tracing.md)
 
 # High-level Compiler Architecture
 

src/doc/rustc-dev-guide/src/building/bootstrapping/bootstrap-tracing.md

@@ -0,0 +1,36 @@
+# `tracing` in bootstrap
+
+To minimize bootstrap build times, `tracing` in bootstrap is gated behind the `logging` cargo feature, which in turn is activated by `bootstrap.py` (via `x.py`) if `BOOTSTRAP_LOG` env var is set.
+
+## Using `tracing` in bootstrap
+
+Due to the conditional compilation via the `logging` cargo feature, this means that `tracing` usages in bootstrap need to be also gated behind the `logging` feature:
+
+- `tracing` macros (like `trace!`) and anything from `tracing`, `tracing_subscriber` and `tracing-tree` will need to be gated by `#[cfg(feature = "logging")]`.
+- `tracing`'s `#[instrument(..)]` macro will need to be gated like `#![cfg_attr(feature = "logging", instrument(..))]`.
+
+## Enabling `logging` bootstrap feature in rust-analyzer
+
+You can adjust your `settings.json`'s `rust-analyzer.check.overrideCommand` and `rust-analyzer.cargo.buildScripts.overrideCommand` if you want to also enable `logging` cargo feature by default in your editor. This is mostly useful if you want proper r-a completions and such when working on bootstrap itself.
+
+```json
+"rust-analyzer.check.overrideCommand": [
+    "BOOTSTRAP_LOG=1", // <- BOOTSTRAP_LOG=1 won't enable tracing filter, but it will activate bootstrap's `logging` feature
+    "python3",
+    "x.py",
+    "check",
+    "--json-output",
+    "--build-dir=build-rust-analyzer"
+],
+```
+
+```json
+"rust-analyzer.cargo.buildScripts.overrideCommand": [
+    "BOOTSTRAP_LOG=1", // <- note this
+    "python3",
+    "x.py",
+    "check",
+    "--json-output",
+    "--build-dir=build-rust-analyzer"
+],
+```

src/doc/rustc-dev-guide/src/building/bootstrapping/intro.md

@@ -17,5 +17,8 @@ In this section, we give a high-level overview of
 [what Bootstrap does](./what-bootstrapping-does.md), followed by a high-level
 introduction to [how Bootstrap does it](./how-bootstrap-does-it.md).
 
+See also [tracing in bootstrap](./bootstrap-tracing.md) for structured debug
+logging.
+
 [boot]: https://en.wikipedia.org/wiki/Bootstrapping_(compilers)
 [ocaml-compiler]: https://github.com/rust-lang/rust/tree/ef75860a0a72f79f97216f8aaa5b388d98da6480/src/boot