]> git.lizzy.rs Git - rust.git/blob - README.md
fix 'cargo run' in README
[rust.git] / 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)
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 prefixing them with `rustup run nightly`.
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/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 ## Contributing and getting help
58
59 Check out the issues on this GitHub repository for some ideas. There's lots that
60 needs to be done that I haven't documented in the issues yet, however. For more
61 ideas or help with running or hacking on Miri, you can contact me (`scott`) on
62 Mozilla IRC in any of the Rust IRC channels (`#rust`, `#rust-offtopic`, etc).
63
64 ## License
65
66 Licensed under either of
67   * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
68     http://www.apache.org/licenses/LICENSE-2.0)
69   * MIT license ([LICENSE-MIT](LICENSE-MIT) or
70     http://opensource.org/licenses/MIT) at your option.
71
72 ### Contribution
73
74 Unless you explicitly state otherwise, any contribution intentionally submitted
75 for inclusion in the work by you shall be dual licensed as above, without any
76 additional terms or conditions.
77
78 [rust]: https://www.rust-lang.org/
79 [mir]: https://github.com/rust-lang/rfcs/blob/master/text/1211-mir.md
80 [usask]: https://www.usask.ca/
81 [rustup]: https://www.rustup.rs