From 43fa1342f0a36e09db905b436f211375db7b05f4 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Sun, 29 Nov 2020 10:20:24 -0500 Subject: [PATCH] Document what 'sysroot' means --- src/appendix/glossary.md | 1 + src/building/bootstrapping.md | 59 +++++++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+) diff --git a/src/appendix/glossary.md b/src/appendix/glossary.md index 58ec39e4..8ecd4f61 100644 --- a/src/appendix/glossary.md +++ b/src/appendix/glossary.md @@ -72,6 +72,7 @@ Term | Meaning soundness | 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 | 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. substs | The substitutions for a given generic type or item (e.g. the `i32`, `u32` in `HashMap`). +sysroot | The directory for build artifacts that are loaded by the compiler at runtime. ([see more](../building/bootstrapping.html#what-is-a-sysroot)) Tag | 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). tcx | The "typing context", main data structure of the compiler. ([see more](../ty.md)) `'tcx` | The lifetime of the allocation arena. ([see more](../ty.md)) diff --git a/src/building/bootstrapping.md b/src/building/bootstrapping.md index 0921755a..1d420a97 100644 --- a/src/building/bootstrapping.md +++ b/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: