README.md

   1 # Miri
   2
   3 [[slides](https://solson.me/miri-slides.pdf)]
   4 [[report](https://solson.me/miri-report.pdf)]
   5
   6 An experimental interpreter for [Rust][rust]'s [mid-level intermediate
   7 representation][mir] (MIR). This project began as part of my work for the
   8 undergraduate research course at the [University of Saskatchewan][usask].
   9
  10 [![Build Status](https://travis-ci.org/solson/miri.svg?branch=master)](https://travis-ci.org/solson/miri)
  11
  12 ## Installing Rust
  13
  14 I recommend that you install [rustup][rustup] and then use it to install the
  15 current Rust nightly version:
  16
  17 ```sh
  18 rustup update nightly
  19 ```
  20
  21 You should also make `nightly` the default version for your Miri directory by
  22 running the following command while you're in it. If you don't do this, you can
  23 run the later `cargo` commands by prefixing them with `rustup run nightly`.
  24
  25 ```sh
  26 rustup override add nightly
  27 ```
  28
  29 ## Building Miri
  30
  31 ```sh
  32 cargo build
  33 ```
  34
  35 If Miri fails to build, it's likely because a change in the latest nightly
  36 compiler broke it. You could try an older nightly with `rustup update
  37 nightly-<date>` where `<date>` is a few days or weeks ago, e.g. `2016-05-20` for
  38 May 20th. Otherwise, you could notify me in an issue or on IRC. Or, if you know
  39 how to fix it, you could send a PR. :smile:
  40
  41 ## Running tests
  42
  43 ```sh
  44 cargo run tests/run-pass/vecs.rs # Or whatever test you like.
  45 ```
  46
  47 ## Debugging
  48
  49 You can get detailed, statement-by-statement traces by setting the `MIRI_RUN`
  50 environment variable to `trace`. These traces are indented based on call stack
  51 depth. You can get a much less verbose set of information with other logging
  52 levels such as `warn`.
  53
  54 ## Contributing and getting help
  55
  56 Check out the issues on this GitHub repository for some ideas. There's lots that
  57 needs to be done that I haven't documented in the issues yet, however. For more
  58 ideas or help with running or hacking on Miri, you can contact me (`scott`) on
  59 Mozilla IRC in any of the Rust IRC channels (`#rust`, `#rust-offtopic`, etc).`
  60
  61 ## License
  62
  63 Licensed under either of
  64   * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
  65     http://www.apache.org/licenses/LICENSE-2.0)
  66   * MIT license ([LICENSE-MIT](LICENSE-MIT) or
  67     http://opensource.org/licenses/MIT) at your option.
  68
  69 ### Contribution
  70
  71 Unless you explicitly state otherwise, any contribution intentionally submitted
  72 for inclusion in the work by you shall be dual licensed as above, without any
  73 additional terms or conditions.
  74
  75 [rust]: https://www.rust-lang.org/
  76 [mir]: https://github.com/rust-lang/rfcs/blob/master/text/1211-mir.md
  77 [usask]: https://www.usask.ca/
  78 [rustup]: https://www.rustup.rs