From 86aa8352c695a59db5822f267b6c64ccf601220d Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Wed, 24 Oct 2018 15:29:48 +0200 Subject: [PATCH] Work on miri installation and usage instructions --- README.md | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 7597c9a0e11b..c5ac81729994 100644 --- a/README.md +++ b/README.md @@ -7,15 +7,23 @@ undergraduate research course at the [University of Saskatchewan][usask]. ## Building Miri -I recommend that you install [rustup][rustup] to obtain Rust. Miri comes with a -`rust-version` file describing the latest supported nightly version of the Rust -compiler toolchain. Then all you have to do is: +I recommend that you install [rustup][rustup] to obtain Rust. Then all you have +to do is: ```sh cargo +nightly build ``` -with `+nightly` replaced with the appropriate nightly version of Rust. +This uses the very latest Rust version. If you experience any problem, refer to +the `rust-version` file which contains a particular Rust nightly version that +has been tested against the version of miri you are using. Make sure to use +that particular `nightly-YYYY-MM-DD` whenever the instructions just say +`nightly`. + +To avoid repeating the nightly version all the time, you can use +`rustup override set nightly` (or `rustup override set nightly-YYYY-MM-DD`), +which means `nightly` Rust will automatically be used whenever you are working +in this directory. ## Running Miri @@ -41,18 +49,23 @@ Now you can run Miri against the libstd compiled by xargo: MIRI_SYSROOT=~/.xargo/HOST cargo +nightly run tests/run-pass-fullmir/hashmap.rs ``` -Notice that you will have to re-run the last step of the preparations above when -your toolchain changes (e.g., when you update the nightly). - -You can also set `-Zmiri-start-fn` to make Miri start evaluation with the -`start_fn` lang item, instead of starting at the `main` function. +Notice that you will have to re-run the last step of the preparations above +(`xargo/build.sh`) when your toolchain changes (e.g., when you update the +nightly). ## Running Miri on your own project('s test suite) -Install Miri as a cargo subcommand with `cargo install +nightly --all-features --path .`. +Install Miri as a cargo subcommand with `cargo install +nightly --all-features +--path .`. Be aware that if you used `rustup override set` to fix a particular +Rust version for the miri directory, that will *not* apply to your own project +directory! You have to use a consistent Rust version for building miri and your +project for this to work, so remember to either always specify the nightly +version manually, overriding it in your project directory as well, or use +`rustup default nightly` (or `rustup default nightly-YYYY-MM-DD`) to globally +make `nightly` the default toolchain. -Compile your project and its dependencies against a MIR-enabled libstd as described -above: +We assume that you have prepared a MIR-enabled libstd as described above. Now +compile your project and its dependencies against that libstd: 1. Run `cargo clean` to eliminate any cached dependencies that were built against the non-MIR `libstd`.