I recommend that you install rustup to obtain Rust. Miri comes with a
rust-toolchain file so rustup will automatically pick a suitable nightly
version. Then all you have to do is:
cargo run tests/run-pass/vecs.rs # Or whatever test you like.
Running Miri with full libstd
Per default libstd does not contain the MIR of non-polymorphic functions. When Miri hits a call to such a function, execution terminates. To fix this, it is possible to compile libstd with full MIR:
rustup component add rust-src cargo install xargo xargo/build.sh
Now you can run Miri against the libstd compiled by xargo:
MIRI_SYSROOT=~/.xargo/HOST cargo 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
Running Miri on your own project('s test suite)
Install Miri as a cargo subcommand with
cargo install --all-features, and install
a full libstd as described above.
Then, inside your own project, use
MIRI_SYSROOT=~/.xargo/HOST cargo +nightly miri to run your project, if it is a bin project, or run
MIRI_SYSROOT=~/.xargo/HOST cargo +nightly miri test to run all tests in your
project through Miri.
Miri adds some extra
-Z flags to control its behavior:
-Zmiri-start-fn: This makes interpretation start with
lang_start(defined in libstd) instead of starting with
main. Requires full MIR!
-Zmiri-disable-validationdisables enforcing the validity invariant.
Development and Debugging
Since the heart of Miri (the main interpreter engine) lives in rustc, working on
Miri will often require using a locally built rustc. This includes getting a
trace of the execution, as distributed rustc has
The first-time setup for a local rustc looks as follows:
git clone https://github.com/rust-lang/rust/ rustc cd rustc cp config.toml.example config.toml # Now edit `config.toml` and set `debug-assertions = true` ./x.py build src/rustc # You may have to change the architecture in the next command rustup toolchain link custom build/x86_64-unknown-linux-gnu/stage2 # Now cd to your Miri directory rustup override set custom
build step can take 30 minutes and more.
Now you can
cargo build Miri, and you can
cargo test --tests. (
is needed to skip doctests because we have not built rustdoc for your custom
toolchain.) You can also set
environment variable to get a step-by-step trace.
If you changed something in rustc and want to re-build, run
./x.py build src/rustc --keep-stage 0
This avoids rebuilding the entire stage 0, which can save a lot of time.
Contributing and getting help
Check out the issues on this GitHub repository for some ideas. There's lots that
needs to be done that I haven't documented in the issues yet, however. For more
ideas or help with running or hacking on Miri, you can contact me (
Mozilla IRC in any of the Rust IRC channels (
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be dual licensed as above, without any additional terms or conditions.