diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d6436873938e..c673e107d55d 100644 --- a/CONTRIBUTING.md +++ b/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: +``` +./rustup-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 +./rustup-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 diff --git a/rustup-toolchain b/rustup-toolchain new file mode 100755 index 000000000000..4e8e0b01ebc4 --- /dev/null +++ b/rustup-toolchain @@ -0,0 +1,46 @@ +#!/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: +# +# ./rustup-toolchain: Update "miri" toolchain to match `rust-version` (the known-good version for this commit). +# +# ./rustup-toolchain HEAD: Update "miri" toolchain and `rust-version` file to latest rustc HEAD. +# +# ./rustup-toolchain $COMMIT: Update "miri" toolchain and `rust-version` file to match that commit. + +# Make sure rustup-toolchain-install-master is installed. +if ! which rustup-toolchain-install-master >/dev/null; then + echo "Please install rustup-toolchain-install-master by running 'cargo install rustup-toolchain-install-master'" + exit 1 +fi + +# 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 2>/dev/null | 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 + +# Install and setup new toolchain. +rustup toolchain uninstall miri +rustup-toolchain-install-master -n miri -c rust-src -c rustc-dev -- "$NEW_COMMIT" +rustup override set miri + +# Cleanup. +cargo clean