Empowering everyone to build reliable and efficient software

# Miri An experimental interpreter for [Rust][rust]'s [mid-level intermediate representation][mir] (MIR). It can run binaries and test suites of cargo projects and detect certain classes of [undefined behavior](https://doc.rust-lang.org/reference/behavior-considered-undefined.html), for example: * Out-of-bounds memory accesses and use-after-free * Invalid use of uninitialized data * Violation of intrinsic preconditions (an [`unreachable_unchecked`] being reached, calling [`copy_nonoverlapping`] with overlapping ranges, ...) * Not sufficiently aligned memory accesses and references * Violation of *some* basic type invariants (a `bool` that is not 0 or 1, for example, or an invalid enum discriminant) * **Experimental**: Violations of the [Stacked Borrows] rules governing aliasing for reference types * **Experimental**: Violations of the [Tree Borrows] aliasing rules, as an optional alternative to [Stacked Borrows] * **Experimental**: Data races On top of that, Miri will also tell you about memory leaks: when there is memory still allocated at the end of the execution, and that memory is not reachable from a global `static`, Miri will raise an error. Miri supports almost all Rust language features; in particular, unwinding and concurrency are properly supported (including some experimental emulation of weak memory effects, i.e., reads can return outdated values). You can use Miri to emulate programs on other targets, e.g. to ensure that byte-level data manipulation works correctly both on little-endian and big-endian systems. See [cross-interpretation](#cross-interpretation-running-for-different-targets) below. Miri has already discovered some [real-world bugs](#bugs-found-by-miri). If you found a bug with Miri, we'd appreciate if you tell us and we'll add it to the list! By default, Miri ensures a fully deterministic execution and isolates the program from the host system. Some APIs that would usually access the host, such as gathering entropy for random number generators, environment variables, and clocks, are replaced by deterministic "fake" implementations. Set `MIRIFLAGS="-Zmiri-disable-isolation"` to access the real system APIs instead. (In particular, the "fake" system RNG APIs make Miri **not suited for cryptographic use**! Do not generate keys using Miri.) All that said, be aware that Miri will **not catch all cases of undefined behavior** in your program, and cannot run all programs: * There are still plenty of open questions around the basic invariants for some types and when these invariants even have to hold. Miri tries to avoid false positives here, so if your program runs fine in Miri right now that is by no means a guarantee that it is UB-free when these questions get answered. In particular, Miri does not check that references point to valid data. * If the program relies on unspecified details of how data is laid out, it will still run fine in Miri -- but might break (including causing UB) on different compiler versions or different platforms. * Program execution is non-deterministic when it depends, for example, on where exactly in memory allocations end up, or on the exact interleaving of concurrent threads. Miri tests one of many possible executions of your program. You can alleviate this to some extent by running Miri with different values for `-Zmiri-seed`, but that will still by far not explore all possible executions. * Miri runs the program as a platform-independent interpreter, so the program has no access to most platform-specific APIs or FFI. A few APIs have been implemented (such as printing to stdout, accessing environment variables, and basic file system access) but most have not: for example, Miri currently does not support networking. System API support varies between targets; if you run on Windows it is a good idea to use `--target x86_64-unknown-linux-gnu` to get better support. * Weak memory emulation may [produce weak behaviours](https://github.com/rust-lang/miri/issues/2301) unobservable by compiled programs running on real hardware when `SeqCst` fences are used, and it cannot produce all behaviors possibly observable on real hardware. Moreover, Miri fundamentally cannot tell you whether your code is *sound*. [Soundness] is the property of never causing undefined behavior when invoked from arbitrary safe code, even in combination with other sound code. In contrast, Miri can just tell you if *a particular way of interacting with your code* (e.g., a test suite) causes any undefined behavior. It is up to you to ensure sufficient coverage. [rust]: https://www.rust-lang.org/ [mir]: https://github.com/rust-lang/rfcs/blob/master/text/1211-mir.md [`unreachable_unchecked`]: https://doc.rust-lang.org/stable/std/hint/fn.unreachable_unchecked.html [`copy_nonoverlapping`]: https://doc.rust-lang.org/stable/std/ptr/fn.copy_nonoverlapping.html [Stacked Borrows]: https://github.com/rust-lang/unsafe-code-guidelines/blob/master/wip/stacked-borrows.md [Tree Borrows]: https://perso.crans.org/vanille/treebor/ [Soundness]: https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#soundness-of-code--of-a-library ## Using Miri Install Miri on Rust nightly via `rustup`: ```sh rustup +nightly component add miri ``` If `rustup` says the `miri` component is unavailable, that's because not all nightly releases come with all tools. Check out [this website](https://rust-lang.github.io/rustup-components-history) to determine a nightly version that comes with Miri and install that using `rustup toolchain install nightly-YYYY-MM-DD`. Either way, all of the following commands assume the right toolchain is pinned via `rustup override set nightly` or `rustup override set nightly-YYYY-MM-DD`. (Alternatively, use `cargo +nightly`/`cargo +nightly-YYYY-MM-DD` for each of the following commands.) Now you can run your project in Miri: 1. Run `cargo clean` to eliminate any cached dependencies. Miri needs your dependencies to be compiled the right way, that would not happen if they have previously already been compiled. 2. To run all tests in your project through Miri, use `cargo miri test`. 3. If you have a binary project, you can run it through Miri using `cargo miri run`. The first time you run Miri, it will perform some extra setup and install some dependencies. It will ask you for confirmation before installing anything. `cargo miri run/test` supports the exact same flags as `cargo run/test`. For example, `cargo miri test filter` only runs the tests containing `filter` in their name. You can pass arguments to Miri via `MIRIFLAGS`. For example, `MIRIFLAGS="-Zmiri-disable-stacked-borrows" cargo miri run` runs the program without checking the aliasing of references. When compiling code via `cargo miri`, the `cfg(miri)` config flag is set for code that will be interpret under Miri. You can use this to ignore test cases that fail under Miri because they do things Miri does not support: ```rust #[test] #[cfg_attr(miri, ignore)] fn does_not_work_on_miri() { tokio::run(futures::future::ok::<_, ()>(())); } ``` There is no way to list all the infinite things Miri cannot do, but the interpreter will explicitly tell you when it finds something unsupported: ``` error: unsupported operation: can't call foreign function: bind ... = help: this is likely not a bug in the program; it indicates that the program \ performed an operation that the interpreter does not support ``` ### Cross-interpretation: running for different targets Miri can not only run a binary or test suite for your host target, it can also perform cross-interpretation for arbitrary foreign targets: `cargo miri run --target x86_64-unknown-linux-gnu` will run your program as if it was a Linux program, no matter your host OS. This is particularly useful if you are using Windows, as the Linux target is much better supported than Windows targets. You can also use this to test platforms with differ