-#### "found possibly newer version of crate `std` which `<dependency>` depends on"
-
-Your build directory may contain artifacts from an earlier build that have/have
-not been built for Miri. Run `cargo clean` before switching from non-Miri to
-Miri builds and vice-versa.
-
-#### "found crate `std` compiled by an incompatible version of rustc"
-
-You may be running `cargo miri` with a different compiler version than the one
-used to build the custom libstd that Miri uses, and Miri failed to detect that.
-Try deleting `~/.cache/miri`.
-
-#### "no mir for `std::rt::lang_start_internal`"
-
-This means the sysroot you are using was not compiled with Miri in mind. This
-should never happen when you use `cargo miri` because that takes care of setting
-up the sysroot. If you are using `miri` (the Miri driver) directly, see the
-[contributors' guide](CONTRIBUTING.md) for how to use `./miri` to best do that.
-
-
-## Miri `-Z` flags and environment variables
-[miri-flags]: #miri--z-flags-and-environment-variables
-
-Miri adds its own set of `-Z` flags, which are usually set via the `MIRIFLAGS`
-environment variable. We first document the most relevant and most commonly used flags:
-
-* `-Zmiri-compare-exchange-weak-failure-rate=<rate>` changes the failure rate of
- `compare_exchange_weak` operations. The default is `0.8` (so 4 out of 5 weak ops will fail).
- You can change it to any value between `0.0` and `1.0`, where `1.0` means it
- will always fail and `0.0` means it will never fail. Note than setting it to
- `1.0` will likely cause hangs, since it means programs using
- `compare_exchange_weak` cannot make progress.
-* `-Zmiri-disable-isolation` disables host isolation. As a consequence,
- the program has access to host resources such as environment variables, file
- systems, and randomness.
-* `-Zmiri-isolation-error=<action>` configures Miri's response to operations
- requiring host access while isolation is enabled. `abort`, `hide`, `warn`,
- and `warn-nobacktrace` are the supported actions. The default is to `abort`,
- which halts the machine. Some (but not all) operations also support continuing
- execution with a "permission denied" error being returned to the program.
- `warn` prints a full backtrace when that happens; `warn-nobacktrace` is less
- verbose. `hide` hides the warning entirely.
-* `-Zmiri-env-exclude=<var>` keeps the `var` environment variable isolated from the host so that it
- cannot be accessed by the program. Can be used multiple times to exclude several variables. The
- `TERM` environment variable is excluded by default in Windows to prevent the libtest harness from
- accessing the file system. This has no effect unless `-Zmiri-disable-isolation` is also set.
-* `-Zmiri-env-forward=<var>` forwards the `var` environment variable to the interpreted program. Can
- be used multiple times to forward several variables. This takes precedence over
- `-Zmiri-env-exclude`: if a variable is both forwarded and exluced, it *will* get forwarded. This
- means in particular `-Zmiri-env-forward=TERM` overwrites the default exclusion of `TERM`.
-* `-Zmiri-ignore-leaks` disables the memory leak checker, and also allows some
- remaining threads to exist when the main thread exits.
-* `-Zmiri-permissive-provenance` disables the warning for integer-to-pointer casts and
- [`ptr::from_exposed_addr`](https://doc.rust-lang.org/nightly/std/ptr/fn.from_exposed_addr.html).
- This will necessarily miss some bugs as those operations are not efficiently and accurately
- implementable in a sanitizer, but it will only miss bugs that concern memory/pointers which is
- subject to these operations.
-* `-Zmiri-preemption-rate` configures the probability that at the end of a basic block, the active
- thread will be preempted. The default is `0.01` (i.e., 1%). Setting this to `0` disables
- preemption.
-* `-Zmiri-report-progress` makes Miri print the current stacktrace every now and then, so you can
- tell what it is doing when a program just keeps running. You can customize how frequently the
- report is printed via `-Zmiri-report-progress=<blocks>`, which prints the report every N basic
- blocks.
-* `-Zmiri-seed=<hex>` configures the seed of the RNG that Miri uses to resolve non-determinism. This
- RNG is used to pick base addresses for allocations, to determine preemption and failure of
- `compare_exchange_weak`, and to control store buffering for weak memory emulation. When isolation
- is enabled (the default), this is also used to emulate system entropy. The default seed is 0. You
- can increase test coverage by running Miri multiple times with different seeds.
-* `-Zmiri-strict-provenance` enables [strict
- provenance](https://github.com/rust-lang/rust/issues/95228) checking in Miri. This means that
- casting an integer to a pointer yields a result with 'invalid' provenance, i.e., with provenance
- that cannot be used for any memory access.
-* `-Zmiri-symbolic-alignment-check` makes the alignment check more strict. By default, alignment is
- checked by casting the pointer to an integer, and making sure that is a multiple of the alignment.
- This can lead to cases where a program passes the alignment check by pure chance, because things
- "happened to be" sufficiently aligned -- there is no UB in this execution but there would be UB in
- others. To avoid such cases, the symbolic alignment check only takes into account the requested
- alignment of the relevant allocation, and the offset into that allocation. This avoids missing
- such bugs, but it also incurs some false positives when the code does manual integer arithmetic to
- ensure alignment. (The standard library `align_to` method works fine in both modes; under
- symbolic alignment it only fills the middle slice when the allocation guarantees sufficient
- alignment.)
-* `-Zmiri-tag-gc=<blocks>` configures how often the pointer tag garbage collector runs. The default
- is to search for and remove unreachable tags once every `10,000` basic blocks. Setting this to
- `0` disables the garbage collector, which causes some programs to have explosive memory usage
- and/or super-linear runtime.
-
-The remaining flags are for advanced use only, and more likely to change or be removed.
-Some of these are **unsound**, which means they can lead
-to Miri failing to detect cases of undefined behavior in a program.
-
-* `-Zmiri-disable-abi-check` disables checking [function ABI]. Using this flag
- is **unsound**.
-* `-Zmiri-disable-alignment-check` disables checking pointer alignment, so you
- can focus on other failures, but it means Miri can miss bugs in your program.
- Using this flag is **unsound**.
-* `-Zmiri-disable-data-race-detector` disables checking for data races. Using
- this flag is **unsound**. This implies `-Zmiri-disable-weak-memory-emulation`.
-* `-Zmiri-disable-stacked-borrows` disables checking the experimental
- [Stacked Borrows] aliasing rules. This can make Miri run faster, but it also
- means no aliasing violations will be detected. Using this flag is **unsound**
- (but the affected soundness rules are experimental).
-* `-Zmiri-disable-validation` disables enforcing validity invariants, which are
- enforced by default. This is mostly useful to focus on other failures (such
- as out-of-bounds accesses) first. Setting this flag means Miri can miss bugs
- in your program. However, this can also help to make Miri run faster. Using
- this flag is **unsound**.
-* `-Zmiri-disable-weak-memory-emulation` disables the emulation of some C++11 weak
- memory effects.
-* `-Zmiri-extern-so-file=<path to a shared object file>` is an experimental flag for providing support
- for FFI calls. Functions not provided by that file are still executed via the usual Miri shims.
- **WARNING**: If an invalid/incorrect `.so` file is specified, this can cause undefined behaviour in Miri itself!
- And of course, Miri cannot do any checks on the actions taken by the external code.
- Note that Miri has its own handling of file descriptors, so if you want to replace *some* functions
- working on file descriptors, you will have to replace *all* of them, or the two kinds of
- file descriptors will be mixed up.
- This is **work in progress**; currently, only integer arguments and return values are
- supported (and no, pointer/integer casts to work around this limitation will not work;
- they will fail horribly).
- Follow [the discussion on supporting other types](https://github.com/rust-lang/miri/issues/2365).
-* `-Zmiri-measureme=<name>` enables `measureme` profiling for the interpreted program.
- This can be used to find which parts of your program are executing slowly under Miri.
- The profile is written out to a file with the prefix `<name>`, and can be processed
- using the tools in the repository https://github.com/rust-lang/measureme.
-* `-Zmiri-mute-stdout-stderr` silently ignores all writes to stdout and stderr,
- but reports to the program that it did actually write. This is useful when you
- are not interested in the actual program's output, but only want to see Miri's
- errors and warnings.
-* `-Zmiri-panic-on-unsupported` will makes some forms of unsupported functionality,
- such as FFI and unsupported syscalls, panic within the context of the emulated
- application instead of raising an error within the context of Miri (and halting
- execution). Note that code might not expect these operations to ever panic, so
- this flag can lead to strange (mis)behavior.
-* `-Zmiri-retag-fields` changes Stacked Borrows retagging to recurse into fields.
- This means that references in fields of structs/enums/tuples/arrays/... are retagged,
- and in particular, they are protected when passed as function arguments.
-* `-Zmiri-track-alloc-id=<id1>,<id2>,...` shows a backtrace when the given allocations are
- being allocated or freed. This helps in debugging memory leaks and
- use after free bugs. Specifying this argument multiple times does not overwrite the previous
- values, instead it appends its values to the list. Listing an id multiple times has no effect.
-* `-Zmiri-track-call-id=<id1>,<id2>,...` shows a backtrace when the given call ids are
- assigned to a stack frame. This helps in debugging UB related to Stacked
- Borrows "protectors". Specifying this argument multiple times does not overwrite the previous
- values, instead it appends its values to the list. Listing an id multiple times has no effect.
-* `-Zmiri-track-pointer-tag=<tag1>,<tag2>,...` shows a backtrace when a given pointer tag
- is created and when (if ever) it is popped from a borrow stack (which is where the tag becomes invalid
- and any future use of it will error). This helps you in finding out why UB is
- happening and where in your code would be a good place to look for it.
- Specifying this argument multiple times does not overwrite the previous
- values, instead it appends its values to the list. Listing a tag multiple times has no effect.
-* `-Zmiri-track-weak-memory-loads` shows a backtrace when weak memory emulation returns an outdated
- value from a load. This can help diagnose problems that disappear under
- `-Zmiri-disable-weak-memory-emulation`.
-
-[function ABI]: https://doc.rust-lang.org/reference/items/functions.html#extern-function-qualifier
-
-Some native rustc `-Z` flags are also very relevant for Miri:
-
-* `-Zmir-opt-level` controls how many MIR optimizations are performed. Miri
- overrides the default to be `0`; be advised that using any higher level can
- make Miri miss bugs in your program because they got optimized away.
-* `-Zalways-encode-mir` makes rustc dump MIR even for completely monomorphic
- functions. This is needed so that Miri can execute such functions, so Miri
- sets this flag per default.
-* `-Zmir-emit-retag` controls whether `Retag` statements are emitted. Miri
- enables this per default because it is needed for [Stacked Borrows].
-
-Moreover, Miri recognizes some environment variables:
-
-* `MIRI_AUTO_OPS` indicates whether the automatic execution of rustfmt, clippy and rustup-toolchain
- should be skipped. If it is set to any value, they are skipped. This is used for avoiding
- infinite recursion in `./miri` and to allow automated IDE actions to avoid the auto ops.
-* `MIRI_LOG`, `MIRI_BACKTRACE` control logging and backtrace printing during
- Miri executions, also [see "Testing the Miri driver" in `CONTRIBUTING.md`][testing-miri].
-* `MIRIFLAGS` (recognized by `cargo miri` and the test suite) defines extra
- flags to be passed to Miri.
-* `MIRI_LIB_SRC` defines the directory where Miri expects the sources of the
- standard library that it will build and use for interpretation. This directory
- must point to the `library` subdirectory of a `rust-lang/rust` repository
- checkout. Note that changing files in that directory does not automatically
- trigger a re-build of the standard library; you have to clear the Miri build
- cache manually (on Linux, `rm -rf ~/.cache/miri`).
-* `MIRI_SYSROOT` (recognized by `cargo miri` and the Miri driver) indicates the sysroot to use. When
- using `cargo miri`, only set this if you do not want to use the automatically created sysroot. For
- directly invoking the Miri driver, this variable (or a `--sysroot` flag) is mandatory.
-* `MIRI_TEST_TARGET` (recognized by the test suite and the `./miri` script) indicates which target
- architecture to test against. `miri` and `cargo miri` accept the `--target` flag for the same
- purpose.
-* `MIRI_NO_STD` (recognized by `cargo miri` and the test suite) makes sure that the target's
- sysroot is built without libstd. This allows testing and running no_std programs.
-* `MIRI_BLESS` (recognized by the test suite) overwrite all `stderr` and `stdout` files
- instead of checking whether the output matches.
-* `MIRI_SKIP_UI_CHECKS` (recognized by the test suite) don't check whether the
- `stderr` or `stdout` files match the actual output. Useful for the rustc test suite
- which has subtle differences that we don't care about.
-
-The following environment variables are *internal* and must not be used by
-anyone but Miri itself. They are used to communicate between different Miri
-binaries, and as such worth documenting:
-
-* `MIRI_BE_RUSTC` can be set to `host` or `target`. It tells the Miri driver to
- actually not interpret the code but compile it like rustc would. With `target`, Miri sets
- some compiler flags to prepare the code for interpretation; with `host`, this is not done.
- This environment variable is useful to be sure that the compiled `rlib`s are compatible
- with Miri.
-* `MIRI_CALLED_FROM_XARGO` is set during the Miri-induced `xargo` sysroot build,
- which will re-invoke `cargo-miri` as the `rustc` to use for this build.
-* `MIRI_CALLED_FROM_RUSTDOC` when set to any value tells `cargo-miri` that it is
- running as a child process of `rustdoc`, which invokes it twice for each doc-test
- and requires special treatment, most notably a check-only build before interpretation.
- This is set by `cargo-miri` itself when running as a `rustdoc`-wrapper.
-* `MIRI_CWD` when set to any value tells the Miri driver to change to the given
- directory after loading all the source files, but before commencing
- interpretation. This is useful if the interpreted program wants a different
- working directory at run-time than at build-time.
-* `MIRI_LOCAL_CRATES` is set by `cargo-miri` to tell the Miri driver which
- crates should be given special treatment in diagnostics, in addition to the
- crate currently being compiled.
-* `MIRI_VERBOSE` when set to any value tells the various `cargo-miri` phases to
- perform verbose logging.
-* `MIRI_HOST_SYSROOT` is set by bootstrap to tell `cargo-miri` which sysroot to use for *host*
- operations.
-
-[testing-miri]: CONTRIBUTING.md#testing-the-miri-driver
-
-## Miri `extern` functions
-
-Miri provides some `extern` functions that programs can import to access
-Miri-specific functionality:
-
-```rust
-#[cfg(miri)]
-extern "Rust" {
- /// Miri-provided extern function to mark the block `ptr` points to as a "root"
- /// for some static memory. This memory and everything reachable by it is not
- /// considered leaking even if it still exists when the program terminates.
- ///
- /// `ptr` has to point to the beginning of an allocated block.
- fn miri_static_root(ptr: *const u8);
-
- // Miri-provided extern function to get the amount of frames in the current backtrace.
- // The `flags` argument must be `0`.
- fn miri_backtrace_size(flags: u64) -> usize;
-
- /// Miri-provided extern function to obtain a backtrace of the current call stack.
- /// This writes a slice of pointers into `buf` - each pointer is an opaque value
- /// that is only useful when passed to `miri_resolve_frame`.
- /// `buf` must have `miri_backtrace_size(0) * pointer_size` bytes of space.
- /// The `flags` argument must be `1`.
- fn miri_get_backtrace(flags: u64, buf: *mut *mut ());
-
- /// Miri-provided extern function to resolve a frame pointer obtained
- /// from `miri_get_backtrace`. The `flags` argument must be `1`,
- /// and `MiriFrame` should be declared as follows:
- ///
- /// ```rust
- /// #[repr(C)]
- /// struct MiriFrame {
- /// // The size of the name of the function being executed, encoded in UTF-8
- /// name_len: usize,
- /// // The size of filename of the function being executed, encoded in UTF-8
- /// filename_len: usize,
- /// // The line number currently being executed in `filename`, starting from '1'.
- /// lineno: u32,
- /// // The column number currently being executed in `filename`, starting from '1'.
- /// colno: u32,
- /// // The function pointer to the function currently being executed.
- /// // This can be compared against function pointers obtained by
- /// // casting a function (e.g. `my_fn as *mut ()`)
- /// fn_ptr: *mut ()
- /// }
- /// ```
- ///
- /// The fields must be declared in exactly the same order as they appear in `MiriFrame` above.
- /// This function can be called on any thread (not just the one which obtained `frame`).
- fn miri_resolve_frame(frame: *mut (), flags: u64) -> MiriFrame;
-
- /// Miri-provided extern function to get the name and filename of the frame provided by `miri_resolve_frame`.
- /// `name_buf` and `filename_buf` should be allocated with the `name_len` and `filename_len` fields of `MiriFrame`.
- /// The flags argument must be `0`.
- fn miri_resolve_frame_names(ptr: *mut (), flags: u64, name_buf: *mut u8, filename_buf: *mut u8);
-
- /// Miri-provided extern function to begin unwinding with the given payload.
- ///
- /// This is internal and unstable and should not be used; we give it here
- /// just to be complete.
- fn miri_start_panic(payload: *mut u8) -> !;
-}
-```