X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=README.md;h=c7a3200dbd90439c7fa7534941b415fd79f941df;hb=15a4f0a9e094f09b658dbb3a176d62c8661dec3b;hp=bfc32d04a9d14fe8d8da36c556436c59625ed6fd;hpb=5974e7d4a973983f449702538468ef1a3e3d9407;p=rust.git diff --git a/README.md b/README.md index bfc32d04a9d..c7a3200dbd9 100644 --- a/README.md +++ b/README.md @@ -65,9 +65,9 @@ in your program, and cannot run all programs: 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 behaivours unobservable by compiled - programs running on real hardware when `SeqCst` fences are used, and it cannot - produce all behaviors possibly observable on real hardware. +* 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. [rust]: https://www.rust-lang.org/ [mir]: https://github.com/rust-lang/rfcs/blob/master/text/1211-mir.md @@ -192,8 +192,9 @@ randomness that is used to determine allocation base addresses. The following snippet calls Miri in a loop with different values for the seed: ``` -for seed in $({ echo obase=16; seq 0 255; } | bc); do - MIRIFLAGS=-Zmiri-seed=$seed cargo miri test || { echo "Last seed: $seed"; break; }; +for SEED in $({ echo obase=16; seq 0 255; } | bc); do + echo "Trying seed: $SEED" + MIRIFLAGS=-Zmiri-seed=$SEED cargo miri test || { echo "Failing seed: $SEED"; break; }; done ``` @@ -281,12 +282,12 @@ environment variable. We first document the most relevant and most commonly used verbose. `hide` hides the warning entirely. * `-Zmiri-env-exclude=` 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 to [speed up the test - harness](https://github.com/rust-lang/miri/issues/1702). This has no effect unless - `-Zmiri-disable-isolation` is also set. + `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=` forwards the `var` environment variable to the interpreted program. Can - be used multiple times to forward several variables. This has no effect if - `-Zmiri-disable-isolation` is set. + 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 @@ -327,17 +328,6 @@ The remaining flags are for advanced use only, and more likely to change or be r Some of these are **unsound**, which means they can lead to Miri failing to detect cases of undefined behavior in a program. -* `-Zmiri-allow-uninit-numbers` disables the check to ensure that number types (integer and float - types) always hold initialized data. (They must still be initialized when any actual operation, - such as arithmetic, is performed.) Using this flag is **unsound** and - [deprecated](https://github.com/rust-lang/miri/issues/2187). This has no effect when - `-Zmiri-disable-validation` is present. -* `-Zmiri-allow-ptr-int-transmute` makes Miri more accepting of transmutation between pointers and - integers via `mem::transmute` or union/pointer type punning. This has two effects: it disables the - check against integers storing a pointer (i.e., data with provenance), thus allowing - pointer-to-integer transmutation, and it treats integer-to-pointer transmutation as equivalent to - a cast. Implies `-Zmiri-permissive-provenance`. Using this flag is **unsound** and - [deprecated](https://github.com/rust-lang/miri/issues/2188). * `-Zmiri-disable-abi-check` disables checking [function ABI]. Using this flag is **unsound**. * `-Zmiri-disable-alignment-check` disables checking pointer alignment, so you @@ -381,11 +371,14 @@ to Miri failing to detect cases of undefined behavior in a program. 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=,,...` shows a backtrace when a given pointer tag - 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 + 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 @@ -402,6 +395,9 @@ Some native rustc `-Z` flags are also very relevant for Miri: 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 @@ -412,13 +408,14 @@ Moreover, Miri recognizes some environment variables: 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 test suite) indicates the - sysroot to use. Only set this if you do not want to use the automatically - created sysroot. (The `miri` driver sysroot is controlled via the `--sysroot` - flag instead.) -* `MIRI_TEST_TARGET` (recognized by the test suite) indicates which target - architecture to test against. `miri` and `cargo miri` accept the `--target` - flag for the same purpose. +* `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 @@ -449,6 +446,8 @@ binaries, and as such worth documenting: 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 @@ -577,6 +576,8 @@ Definite bugs found: * [`integer-encoding` dereferencing a misaligned pointer](https://github.com/dermesser/integer-encoding-rs/pull/23) * [`rkyv` constructing a `Box<[u8]>` from an overaligned allocation](https://github.com/rkyv/rkyv/commit/a9417193a34757e12e24263178be8b2eebb72456) * [Data race in `thread::scope`](https://github.com/rust-lang/rust/issues/98498) +* [`regex` incorrectly handling unaligned `Vec` buffers](https://www.reddit.com/r/rust/comments/vq3mmu/comment/ienc7t0?context=3) +* [Incorrect use of `compare_exchange_weak` in `once_cell`](https://github.com/matklad/once_cell/issues/186) Violations of [Stacked Borrows] found that are likely bugs (but Stacked Borrows is currently just an experiment):