add toolchain mgmt script

Author: RalfJung

CONTRIBUTING.md

@@ -12,6 +12,22 @@ on the [Rust Zulip].
 
 [Rust Zulip]: https://rust-lang.zulipchat.com
 
+## Building Miri with a pre-built rustc
+
+Miri heavily relies on internal rustc interfaces to execute MIR.  Still, some
+things (like adding support for a new intrinsic or a shim for an external
+function being called) can be done by working just on the Miri side.
+
+The `rust-version` file contains the commit hash of rustc that Miri is currently
+tested against. Other versions will likely not work. After installing
+[`rustup-toolchain-install-master`], you can run the following command to
+install that exact version of rustc as a toolchain:
+```
+./toolchain
+```
+
+[`rustup-toolchain-install-master`]: https://github.com/kennytm/rustup-toolchain-install-master
+
 ### Fixing Miri when rustc changes
 
 Miri is heavily tied to rustc internals, so it is very common that rustc changes
@@ -20,36 +36,12 @@ Usually, Miri will require changes similar to the other consumers of the changed
 rustc API, so reading the rustc PR diff is a good way to get an idea for what is
 needed.
 
-When submitting a PR against Miri after fixing it for rustc changes, make sure
-you update the `rust-version` file.  That file always contains the exact rustc
-git commit with which Miri works, and it is the version that our CI tests Miri
-against.
-
-## Building Miri with a nightly rustc
-
-Miri heavily relies on internal rustc interfaces to execute MIR.  Still, some
-things (like adding support for a new intrinsic or a shim for an external
-function being called) can be done by working just on the Miri side.
-
-To prepare, make sure you are using a nightly Rust compiler.  You also need to
-have the `rust-src` and `rustc-dev` components installed, which you can add via
-`rustup component add rust-src rustc-dev`.  Then you should be able to just
-`cargo build` Miri.
-
-In case this fails, your nightly might be incompatible with Miri master.  The
-`rust-version` file contains the commit hash of rustc that Miri is currently
-tested against; you can use that to find a nightly that works or you might have
-to wait for the next nightly to get released. You can also use
-[`rustup-toolchain-install-master`](https://github.com/kennytm/rustup-toolchain-install-master)
-to install that exact version of rustc as a toolchain:
+To update the `rustc-version` file and install the latest rustc, you can run:
 ```
-rustup-toolchain-install-master $(cat rust-version) -c rust-src -c rustc-dev
+./toolchain HEAD
 ```
 
-Another common problem is outdated dependencies: Miri does not come with a
-lockfile (it cannot, due to how it gets embedded into the rustc build). So you
-have to run `cargo update` every now and then yourself to make sure you are
-using the latest versions of everything (which is what gets tested on CI).
+Now try `./miri test`, and submit a PR once that works again.
 
 ## Testing the Miri driver
 [testing-miri]: #testing-the-miri-driver

toolchain

@@ -0,0 +1,40 @@
+#!/bin/bash
+set -e
+# Manages a rustup toolchain called "miri".
+#
+# All commands set "miri" as the override toolchain for the current directory,
+# and make the `rust-version` file match that toolchain.
+#
+# USAGE:
+#
+# ./toolchain: Update "miri" toolchain to match `rust-version` (the known-good version for this commit).
+# 
+# ./toolchain HEAD: Update "miri" toolchain and `rust-version` file to latest rustc HEAD.
+# 
+# ./toolchain $COMMIT: Update "miri" toolchain and `rust-version` file to match that commit.
+
+# Determine new commit.
+if [[ "$1" == "" ]]; then
+    NEW_COMMIT=$(cat rust-version)
+elif [[ "$1" == "HEAD" ]]; then
+    NEW_COMMIT=$(git ls-remote https://github.com/rust-lang/rust/ HEAD | cut -f 1)
+else
+    NEW_COMMIT="$1"
+fi
+echo "$NEW_COMMIT" > rust-version
+
+# Check if we already are at that commit.
+CUR_COMMIT=$(rustc +miri --version -v | egrep "^commit-hash: " | cut -d " " -f 2)
+if [[ "$CUR_COMMIT" == "$NEW_COMMIT" ]]; then
+    echo "miri toolchain is already at commit $CUR_COMMIT."
+    rustup override set miri
+    exit 0
+fi
+
+# Cleanup.
+cargo +nightly clean # Use nightly cargo as miri toolchain might be broken.
+rustup toolchain uninstall miri
+
+# Install and setup new toolchain.
+rustup-toolchain-install-master -n miri -c rust-src -c rustc-dev -- "$NEW_COMMIT"
+rustup override set miri