Make the build process easier

Notice I didn't say simpler.

This does a quite a few things:

- Pins a version of nightly using `rust-toolchain`. This avoids
  confusion when rustc changes its API in a later version. When rebasing
  over rust-lang/master, rust-toolchain should also be updated.
- Replaces CUSTOM_RUSTDOC with `rustup toolchain link`, which allows
  determining the sysroot without hardcoding `.rustup/toolchain` in the
  instructions (*not* the binary).
- Replaces 'copy paste what cargo did with additional arguments' with `cargo rustdoc`
- Determines the sysroot in `src/main.rs` with rustup instead of
  hard-coding it. This is an absolute hack, see the comments for details,
  but it's used by clippy and miri so it works in practice.
- Minor changes to the README to distinguish the current directory

Author: jyn514

README.md

@@ -5,44 +5,39 @@
 ```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`
+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`
 ```

rust-toolchain

@@ -0,0 +1,3 @@
+[toolchain]
+channel = "nightly-2020-12-09"
+components = ["rustc-dev", "llvm-tools-preview"]

src/main.rs

@@ -77,7 +77,38 @@ use std::process::Command;
 use regex::Regex;
 use std::fs;
 
+// 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();
+
     Command::new("cargo")
         .args(&["clean", "--target-dir", "target/debug/examples"])
         .output().unwrap();
@@ -97,7 +128,8 @@ fn main() {
         .for_each(|command| {
             let args: Vec<_> = command
                 .split(" ")
-                .chain(vec!["--sysroot", "/Users/will/.rustup/toolchains/nightly-x86_64-apple-darwin"].into_iter())
+                // We need to overwrite the default that librustc_session would compute.
+                .chain(vec!["--sysroot", &sysroot])
                 .map(|s| s.to_string())
                 .collect();
             let file_name = args[4].to_string();     
@@ -109,4 +141,4 @@ fn main() {
 
     let json = rustc_serialize::json::encode(&calls).unwrap();
     fs::write(".call_locations.json", json).unwrap();
-}
+}