Document what 'sysroot' means

src/appendix/glossary.md

@@ -72,6 +72,7 @@ Term                                           | Meaning
 <span id="soundness">soundness</span>          |  A technical term in type theory. Roughly, if a type system is sound, then a program that type-checks is type-safe. That is, one can never (in safe rust) force a value into a variable of the wrong type. (see "completeness").
 <span id="span">span</span>                    |  A location in the user's source code, used for error reporting primarily. These are like a file-name/line-number/column tuple on steroids: they carry a start/end point, and also track macro expansions and compiler desugaring. All while being packed into a few bytes (really, it's an index into a table). See the Span datatype for more.
 <span id="substs">substs</span>                |  The substitutions for a given generic type or item (e.g. the `i32`, `u32` in `HashMap<i32, u32>`).
+<span id="sysroot">sysroot</span>              |  The directory for build artifacts that are loaded by the compiler at runtime. ([see more](../building/bootstrapping.html#what-is-a-sysroot))
 <span id="tag">Tag</span>                      |  The "tag" of an enum/generator encodes the [discriminant](#discriminant) of the active variant/state.  Tags can either be "direct" (simply storing the discriminant in a field) or use a ["niche"](#niche).
 <span id="tcx">tcx</span>                      |  The "typing context", main data structure of the compiler. ([see more](../ty.md))
 <span id="lifetime-tcx">`'tcx`</span>          |  The lifetime of the allocation arena. ([see more](../ty.md))

src/building/bootstrapping.md

@@ -264,6 +264,65 @@ is built by the _beta_ compiler, but using the _master_ version of libstd!
 The only time `rustc` uses `cfg(bootstrap)` is when it adds internal lints
 that use diagnostic items. This happens very rarely.
 
+### What is a 'sysroot'?
+
+When you build a project with cargo, the build artifacts for dependendencies
+are normally stored in `target/debug/deps`. This only contains dependencies cargo
+knows about; in particular, it doesn't have the standard library. Where do
+`std` or `proc_macro` come from? It comes from the **sysroot**, the root
+of a number of directories where the compiler loads build artifacts at runtime.
+The sysroot doesn't just store the standard library, though - it includes
+anything that needs to be loaded at runtime. That includes (but is not limited
+to):
+
+- `libstd`/`libtest`/`libproc_macro`
+- The compiler crates themselves, when using `rustc_private`. In-tree these
+  are always present; out of tree, you need to install `rustc-dev` with rustup.
+- `libLLVM.so`, the shared object file for the LLVM project. In-tree this is
+  either built from source or downloaded from CI; out-of-tree, you need to
+  install `llvm-tools-preview` with rustup.
+
+All the artifacts listed so far are *compiler* runtime dependencies. You can
+see them with `rustc --print sysroot`:
+
+```
+$ ls $(rustc --print sysroot)/lib
+libchalk_derive-0685d79833dc9b2b.so  libstd-25c6acf8063a3802.so
+libLLVM-11-rust-1.50.0-nightly.so    libtest-57470d2aa8f7aa83.so
+librustc_driver-4f0cc9f50e53f0ba.so  libtracing_attributes-e4be92c35ab2a33b.so
+librustc_macros-5f0ec4a119c6ac86.so  rustlib
+```
+
+There are also runtime dependencies for the standard library! These are in
+`lib/rustlib`, not `lib/` directly.
+
+```
+$ ls $(rustc --print sysroot)/lib/rustlib/x86_64-unknown-linux-gnu/lib | head -n 5
+libaddr2line-6c8e02b8fedc1e5f.rlib
+libadler-9ef2480568df55af.rlib
+liballoc-9c4002b5f79ba0e1.rlib
+libcfg_if-512eb53291f6de7e.rlib
+libcompiler_builtins-ef2408da76957905.rlib
+```
+
+`rustlib` includes libraries like `hashbrown` and `cfg_if`, which are not part
+of the public API of the standard library, but are used to implement it.
+`rustlib` is part of the search path for linkers, but `lib` will never be part
+of the search path.
+
+Since `rustlib` is part of the search path, it means we have to be careful
+about which crates are included in it. In particular, all crates except for
+the standard library are built with the flag `-Z force-unstable-if-unmarked`,
+which means that you have to use `#![feature(rustc_private)]` in order to
+load it (as opposed to the standard library, which is always available).
+
+You can find more discussion about sysroots in:
+- The [rustdoc PR] explaining why it uses `extern crate` for dependencies loaded from sysroot
+- [Discussions about sysroot on Zulip](https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp/topic/deps.20in.20sysroot/)
+- [Discussions about building rustdoc out of tree](https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp/topic/How.20to.20create.20an.20executable.20accessing.20.60rustc_private.60.3F)
+
+[rustdoc PR]: https://github.com/rust-lang/rust/pull/76728
+
 ### Directories and artifacts generated by x.py
 
 The following tables indicate the outputs of various stage actions: