Merge pull request rust-lang#4919 from RalfJung/locally-built

CONTRIBUTING: explain how to build miri against a locally built rustc

Author: RalfJung

src/tools/miri/CONTRIBUTING.md

@@ -171,8 +171,8 @@ MIRI_LOG=rustc_mir::interpret=info,miri::stacked_borrows ./miri run tests/pass/v
 ```
 
 Note that you will only get `info`, `warn` or `error` messages if you use a prebuilt compiler.
-In order to get `debug` and `trace` level messages, you need to build miri with a locally built
-compiler that has `debug=true` set in `bootstrap.toml`.
+In order to get `debug` and `trace` level messages, you need to build miri with a [locally built
+compiler](#advanced-topic-building-miri-against-a-locally-compiled-rustc) that has `debug=true` set in `bootstrap.toml`.
 
 #### Debugging error messages
 
@@ -320,6 +320,33 @@ You can also directly run Miri on a Rust source file:
 ./x.py run miri --stage 1 --args src/tools/miri/tests/pass/hello.rs
 ```
 
+## Advanced topic: Building Miri against a locally compiled rustc
+
+Very rarely, it can be necessary to work with an out-of-tree Miri but build it against a rustc that
+was locally compiled. (Usually, you should instead work on the Miri that's in the Rust tree, as
+described in the previous subsection.)
+
+This requires a fully bootstrapped build:
+
+```sh
+# Build rustc, then build rustc with that rustc. This can take a while.
+./x build library --stage 3
+```
+
+You also need to set up a linked toolchain with rustup:
+
+```sh
+rustup toolchain link stage2 build/host/stage2
+```
+
+Then in the Miri folder, you can set this as the current toolchain and build against it:
+
+```sh
+rustup override set stage2
+# Prevent `./miri` from reseting the toolchain.
+export MIRI_AUTO_OPS=no
+```
+
 ## Advanced topic: Syncing with the rustc repo
 
 We use the [`josh-sync`](https://github.com/rust-lang/josh-sync) tool to transmit changes between the