| Miri Tips |
| ========= |
| |
| `libtock-rs` runs most of its unit tests under |
| [Miri](https://github.com/rust-lang/miri) to detect undefined behavior. However, |
| Miri does not detect all undefined behavior encountered. This document lists |
| techniques for maximizing the amount of undefined behavior identified by Miri. |
| |
| ## Miri flags |
| |
| Miri has [configuration |
| flags](https://github.com/rust-lang/miri#miri--z-flags-and-environment-variables), |
| which can be set using the `MIRIFLAGS` environment variable. We run the tests |
| both with and without `-Zmiri-track-raw-pointers`, as both versions of Stacked |
| Borrows has undefined behavior the other does not (see [this |
| discussion](https://github.com/rust-lang/miri/pull/1748) for more information). |
| On the run with `-Zmiri-track-raw-pointers`, we also set |
| `-Zmiri-symbolic-alignment-check` to make Miri's alignment check more pendantic. |
| |
| ## Detecting invalid values |
| |
| Miri does not always detect undefined behavior when an invalid value is created |
| but not used. Here are some cases that Miri currently accepts: |
| |
| 1. Unused reference to an invalid value |
| (https://github.com/rust-lang/miri/issues/1638) |
| 1. Unused uninitialized value (https://github.com/rust-lang/miri/issues/1340) |
| 1. Slices pointing to invalid values |
| (https://github.com/rust-lang/miri/issues/1240) |
| |
| Note that copying the value around (including passing it to functions) does |
| *not* count as a use for the purpose of this check. |
| |
| For types that implement `core::fmt::Debug` (i.e. most types), you can check a |
| value is valid by attempting to debug-print it: |
| |
| ```rust |
| format!("{:?}", value); |
| ``` |
| |
| If `value` is invalid, then Miri will identify undefined behavior in the above |
| code. |
