diff --git a/README.md b/README.md
index 4164111349..f6b1441a95 100644
--- a/README.md
+++ b/README.md
@@ -5,44 +5,40 @@
 ```bash
 git clone -b linked-examples https://github.com/willcrichton/rust
 cd rust
-./x.py --stage 1 build
-export CUSTOM_RUSTDOC=$(pwd)/build/x86_64-apple-darwin/stage1/bin/rustdoc
+./x.py build
+# replace `apple-darwin` with your current target as appropriate
+rustup toolchain link custom-rustdoc build/x86_64-apple-darwin/stage1
 cd ..
 git clone https://github.com/willcrichton/example-analyzer
-cd example_analyzer
-rustup toolchain install nightly --profile default --component rustc-dev
-rustup override set nightly
+cd example-analyzer
 cargo build
 ```
 
 ## Example
 
-
 ```bash
+# NOTE: the directory you run this from is important since the project uses
+# `rust-toolchain`
+# On MacOS, use `DYLD_LIBRARY_PATH` instead.
+export LD_LIBRARY_PATH=$(rustc --print sysroot)/lib
 cd doctest
-export DYLD_LIBRARY_PATH=$HOME/.rustup/toolchains/nightly-x86_64-apple-darwin/lib:$DYLD_LIBRARY_PATH
 ../target/debug/example-analyzer
-cargo clean && cargo doc -vv
-# copy the command within Running `...` and:
-# 1. replace rustdoc with $CUSTOM_RUSTDOC
-# 2. add the flag "--call-locations .call_locations.json" to the end
-# 3. run the command
-open target/doc/doctest/index.html
+cargo +custom-rustdoc rustdoc --open -- --call-locations .call_locations.json
 ```
 
 ## Development
 
-If you change the Rust repo (ie rustdoc) then run:
+If you change the Rust repo (i.e. rustdoc) then run:
 
 ```
-./x.py --stage 1 build
-# also re-run the $CUSTOM_RUSTDOC command
+(cd ../../rust && ./x.py build)
+# also re-run `cargo rustdoc`
 ```
 
 If you change example-analyzer then run:
 
 ```
-cargo build
+(cd .. && cargo build)
 ../target/debug/example-analyzer
-# also the $CUSTOM_RUSTDOC command
+# also re-run `cargo rustdoc`
 ```
diff --git a/rust-toolchain b/rust-toolchain
new file mode 100644
index 0000000000..3a473ccaf0
--- /dev/null
+++ b/rust-toolchain
@@ -0,0 +1,3 @@
+[toolchain]
+channel = "nightly-2020-12-11"
+components = ["rustc-dev", "llvm-tools-preview"]
diff --git a/src/main.rs b/src/main.rs
index 224183bfb0..214bcc7205 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -8,7 +8,6 @@ use rustc_hir::{
 use rustc_middle::hir::map::Map;
 use rustc_middle::ty::{TyCtxt, TyKind};
 use std::collections::HashMap;
-use std::env;
 use std::fs;
 use std::process::Command;
 
@@ -93,7 +92,37 @@ impl<'a> rustc_driver::Callbacks for Callbacks<'a> {
     }
 }
 
+// absolutely awful hack to fix the sysroot when running out-of-tree
+// Taken from #78926, which took it from src/bin/miri.rs, which in turn took it from clippy ... rustc is a mess.
+// FIXME(jyn514): implement https://github.com/rust-lang/rust/pull/78926#issuecomment-726653035 instead
+// FIXME(jyn514): Why is this a compile-time constant? Won't that break when this is distributed?
+// maybe use `rustc --print sysroot` instead?
+
+/// Returns the "default sysroot" that will be used if no `--sysroot` flag is set.
+/// Should be a compile-time constant.
+fn compile_time_sysroot() -> String {
+    /* NOTE: this doesn't matter for example-analyzer, which is always built out-of-tree,
+     * but might matter if it's ever incorporated into rustdoc.
+    if option_env!("RUSTC_STAGE").is_some() {
+        // This is being built as part of rustc, and gets shipped with rustup.
+        // We can rely on the sysroot computation in librustc_session.
+        return None;
+    }
+    */
+    // For builds outside rustc, we need to ensure that we got a sysroot
+    // that gets used as a default.  The sysroot computation in librustc_session would
+    // end up somewhere in the build dir (see `get_or_default_sysroot`).
+    // Taken from PR <https://github.com/Manishearth/rust-clippy/pull/911>.
+    let home = option_env!("RUSTUP_HOME").or(option_env!("MULTIRUST_HOME"));
+    let toolchain = option_env!("RUSTUP_TOOLCHAIN").or(option_env!("MULTIRUST_TOOLCHAIN"));
+    match (home, toolchain) {
+        (Some(home), Some(toolchain)) => format!("{}/toolchains/{}", home, toolchain),
+        _ => option_env!("RUST_SYSROOT").expect("to build example-analyzer without rustup, set RUST_SYSROOT to `rustc --print sysroot`").into(),
+    }
+}
+
 fn main() {
+    let sysroot = compile_time_sysroot();
     // Run Cargo to get the `rustc` commands used to check each example.
     // This gives us all the necessary flags (eg --extern) to get the example to compile.
     let cargo_output = {
@@ -129,6 +158,7 @@ fn main() {
         let mut args: Vec<_> = command
             .split(" ")
             .filter(|s| *s != "--error-format=json" && *s != "--json=diagnostic-rendered-ansi")
+            .chain(vec!["--sysroot", &sysroot])
             .collect();
 
         // FIXME(willcrichton): when compiling warp, for some reason the --cfg flags
@@ -145,11 +175,6 @@ fn main() {
             args.remove(*i);
         }
 
-        // Add sysroot to compiler args
-        let toolchain_path = env::var("HOME").unwrap()
-            + "/.rustup/toolchains/nightly-2020-12-09-x86_64-apple-darwin";
-        args.extend(vec!["--sysroot", &toolchain_path]);
-
         let args: Vec<_> = args.into_iter().map(|arg| arg.to_string()).collect();
 
         // Try to find file name from the arg list so we can save it in the call locations