README.md

   1 # Miri [[slides](https://solson.me/miri-slides.pdf)] [[report](https://solson.me/miri-report.pdf)] [![Build Status](https://travis-ci.org/solson/miri.svg?branch=master)](https://travis-ci.org/solson/miri) [![Windows build status](https://ci.appveyor.com/api/projects/status/github/solson/miri?svg=true)](https://ci.appveyor.com/project/solson63299/miri)
   2
   3
   4 An experimental interpreter for [Rust][rust]'s [mid-level intermediate
   5 representation][mir] (MIR). This project began as part of my work for the
   6 undergraduate research course at the [University of Saskatchewan][usask].
   7
   8 ## Installing Rust
   9
  10 I recommend that you install [rustup][rustup] and then use it to install the
  11 current Rust nightly version:
  12
  13 ```sh
  14 rustup update nightly
  15 ```
  16
  17 You should also make `nightly` the default version for your Miri directory by
  18 running the following command while you're in it. If you don't do this, you can
  19 run the later `cargo` commands by using `cargo +nightly` instead.
  20
  21 ```sh
  22 rustup override add nightly
  23 ```
  24
  25 ## Building Miri
  26
  27 ```sh
  28 cargo build
  29 ```
  30
  31 If Miri fails to build, it's likely because a change in the latest nightly
  32 compiler broke it. You could try an older nightly with `rustup update
  33 nightly-<date>` where `<date>` is a few days or weeks ago, e.g. `2016-05-20` for
  34 May 20th. Otherwise, you could notify me in an issue or on IRC. Or, if you know
  35 how to fix it, you could send a PR. :smile:
  36
  37 ## Running tests
  38
  39 ```sh
  40 cargo run --bin miri tests/run-pass-fullmir/vecs.rs # Or whatever test you like.
  41 ```
  42
  43 ## Debugging
  44
  45 You can get detailed, statement-by-statement traces by setting the `MIRI_LOG`
  46 environment variable to `trace`. These traces are indented based on call stack
  47 depth. You can get a much less verbose set of information with other logging
  48 levels such as `warn`.
  49
  50 ## Running miri on your own project('s test suite)
  51
  52 Install miri as a cargo subcommand with `cargo install --debug`.
  53 Then, inside your own project, use `cargo +nightly miri` to run your project, if it is
  54 a bin project, or run `cargo +nightly miri test` to run all tests in your project
  55 through miri.
  56
  57 ## Running miri with full libstd
  58
  59 Per default libstd does not contain the MIR of non-polymorphic functions.  When
  60 miri hits a call to such a function, execution terminates.  To fix this, it is
  61 possible to compile libstd with full MIR:
  62
  63 ```sh
  64 rustup component add rust-src
  65 cargo install xargo
  66 cd xargo/
  67 RUSTFLAGS='-Zalways-encode-mir' xargo build
  68 ```
  69
  70 Now you can run miri against the libstd compiled by xargo:
  71
  72 ```sh
  73 MIRI_SYSROOT=~/.xargo/HOST cargo run --bin miri tests/run-pass-fullmir/vecs.rs
  74 ```
  75
  76 Notice that you will have to re-run the last step of the preparations above when
  77 your toolchain changes (e.g., when you update the nightly).
  78
  79 ## Contributing and getting help
  80
  81 Check out the issues on this GitHub repository for some ideas. There's lots that
  82 needs to be done that I haven't documented in the issues yet, however. For more
  83 ideas or help with running or hacking on Miri, you can contact me (`scott`) on
  84 Mozilla IRC in any of the Rust IRC channels (`#rust`, `#rust-offtopic`, etc).
  85
  86 ## License
  87
  88 Licensed under either of
  89   * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
  90     http://www.apache.org/licenses/LICENSE-2.0)
  91   * MIT license ([LICENSE-MIT](LICENSE-MIT) or
  92     http://opensource.org/licenses/MIT) at your option.
  93
  94 ### Contribution
  95
  96 Unless you explicitly state otherwise, any contribution intentionally submitted
  97 for inclusion in the work by you shall be dual licensed as above, without any
  98 additional terms or conditions.
  99
 100 [rust]: https://www.rust-lang.org/
 101 [mir]: https://github.com/rust-lang/rfcs/blob/master/text/1211-mir.md
 102 [usask]: https://www.usask.ca/
 103 [rustup]: https://www.rustup.rs