rustc-dev-guide: document BOOTSTRAP_TRACING 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)
+- [Debugging bootstrap](./building/bootstrapping/debugging-bootstrap.md)
 
 # High-level Compiler Architecture
 

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

@@ -0,0 +1,40 @@
+# Debugging bootstrap
+
+> FIXME: this page could be expanded 
+
+## `tracing` in bootstrap
+
+To minimize bootstrap build times, `tracing` in bootstrap is gated behind the `tracing` cargo feature, which in turn is activated by `bootstrap.py` (via `x.py`) if `BOOTSTRAP_TRACING` env var is set.
+
+### Using `tracing` in bootstrap
+
+Due to the conditional compilation via the `tracing` cargo feature, this means that `tracing` usages in bootstrap need to be also gated behind the `tracing` feature:
+
+- `tracing` macros (like `trace!`) and anything from `tracing`, `tracing_subscriber` and `tracing-tree` will need to be gated by `#[cfg(feature = "tracing")]`.
+- `tracing`'s `#[instrument(..)]` macro will need to be gated like `#![cfg_attr(feature = "tracing", instrument(..))]`.
+
+### Enabling `tracing` 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_TRACING=1", // <- BOOTSTRAP_TRACING=1 won't enable tracing filter, but it will activate bootstrap's `tracing` feature
+    "python3",
+    "x.py",
+    "check",
+    "--json-output",
+    "--build-dir=build-rust-analyzer"
+],
+```
+
+```json
+"rust-analyzer.cargo.buildScripts.overrideCommand": [
+    "BOOTSTRAP_TRACING=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,7 @@ 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 [debugging bootstrap](./debugging-bootstrap.md).
+
 [boot]: https://en.wikipedia.org/wiki/Bootstrapping_(compilers)
 [ocaml-compiler]: https://github.com/rust-lang/rust/tree/ef75860a0a72f79f97216f8aaa5b388d98da6480/src/boot