-# Miri
+# Miri [[slides](https://solson.me/miri-slides.pdf)] [[report](https://solson.me/miri-report.pdf)] [](https://travis-ci.org/solson/miri) [](https://ci.appveyor.com/project/solson63299/miri)
-[[slides](https://solson.me/miri-slides.pdf)]
-[[report](https://solson.me/miri-report.pdf)]
An experimental interpreter for [Rust][rust]'s [mid-level intermediate
representation][mir] (MIR). This project began as part of my work for the
undergraduate research course at the [University of Saskatchewan][usask].
-[](https://travis-ci.org/tsion/miri)
+## Installing Rust
-## Download Rust nightly
+I recommend that you install [rustup][rustup] and then use it to install the
+current Rust nightly version:
-I currently recommend that you install [multirust][multirust] and then use it to
-install the current rustc nightly version that works with Miri:
+```sh
+rustup update nightly
+```
+
+You should also make `nightly` the default version for your Miri directory by
+running the following command while you're in it. If you don't do this, you can
+run the later `cargo` commands by using `cargo +nightly` instead.
+
+```sh
+rustup override add nightly
+```
+
+## Building Miri
+
+```sh
+cargo build
+```
+
+If Miri fails to build, it's likely because a change in the latest nightly
+compiler broke it. You could try an older nightly with `rustup update
+nightly-<date>` where `<date>` is a few days or weeks ago, e.g. `2016-05-20` for
+May 20th. Otherwise, you could notify me in an issue or on IRC. Or, if you know
+how to fix it, you could send a PR. :smile:
+
+## Running tests
```sh
-multirust update nightly-2016-04-11
+cargo run --bin miri tests/run-pass-fullmir/vecs.rs # Or whatever test you like.
```
-## Build
+## Debugging
+
+You can get detailed, statement-by-statement traces by setting the `MIRI_LOG`
+environment variable to `trace`. These traces are indented based on call stack
+depth. You can get a much less verbose set of information with other logging
+levels such as `warn`.
+
+## Running miri on your own project('s test suite)
+
+Install miri as a cargo subcommand with `cargo install --debug`.
+Then, inside your own project, use `cargo +nightly miri` to run your project, if it is
+a bin project, or run `cargo +nightly miri test` to run all tests in your project
+through miri.
+
+## 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:
```sh
-multirust run nightly-2016-04-11 cargo build
+rustup component add rust-src
+cargo install xargo
+cd xargo/
+RUSTFLAGS='-Zalways-encode-mir' xargo build
```
-## Run a test
+Now you can run miri against the libstd compiled by xargo:
```sh
-multirust run nightly-2016-04-11 cargo run -- \
- --sysroot $HOME/.multirust/toolchains/nightly-2016-04-11 \
- test/filename.rs
+MIRI_SYSROOT=~/.xargo/HOST cargo run --bin miri tests/run-pass-fullmir/vecs.rs
```
-If you are using [rustup][rustup] (the name of the multirust rewrite in Rust),
-the `sysroot` path will also include your build target (e.g.
-`$HOME/.multirust/toolchains/nightly-2016-04-11-x86_64-apple-darwin`). You can
-see the current toolchain's directory by running `rustup which cargo` (ignoring
-the trailing `/bin/cargo`).
+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).
+
+## Contributing and getting help
-If you installed without using multirust or rustup, you'll need to adjust the
-command to run your cargo and set the `sysroot` to the directory where your
-Rust compiler is installed (`$sysroot/bin/rustc` should be a valid path).
+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 (`scott`) on
+Mozilla IRC in any of the Rust IRC channels (`#rust`, `#rust-offtopic`, etc).
## License
[rust]: https://www.rust-lang.org/
[mir]: https://github.com/rust-lang/rfcs/blob/master/text/1211-mir.md
[usask]: https://www.usask.ca/
-[multirust]: https://github.com/brson/multirust
[rustup]: https://www.rustup.rs
projects / rust.git / blobdiff