Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 15 additions & 14 deletions src/fuzzing.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@
For the purposes of this guide, *fuzzing* is any testing methodology that
involves compiling a wide variety of programs in an attempt to uncover bugs in rustc.
Fuzzing is often used to find internal compiler errors (ICEs).
Fuzzing can be beneficial, because it can find bugs before users run into them and
provide small, self-contained programs that make the bug easier to track down.
Fuzzing can be beneficial, because it can find bugs before users run into them.
It also provides small, self-contained programs that make the bug easier to track down.
However, some common mistakes can reduce the helpfulness of fuzzing and end up
making contributors' lives harder.
To maximize your positive impact on the Rust
Expand All @@ -22,7 +22,7 @@ project, please read this guide before reporting fuzzer-generated bugs!
- Include a reasonably minimal, standalone example along with any bug report
- Include all of the information requested in the bug report template
- Search for existing reports with the same message and query stack
- Format the test case with `rustfmt`, if it maintains the bug
- Format the test case with `rustfmt`
- Indicate that the bug was found by fuzzing

*Please don't:*
Expand All @@ -36,15 +36,17 @@ project, please read this guide before reporting fuzzer-generated bugs!
If you're not sure whether or not an ICE is a duplicate of one that's already
been reported, please go ahead and report it and link to issues you think might be related.
In general, ICEs on the same line but with different *query stacks* are usually distinct bugs.
For example, [#109020][#109020] and [#109129][#109129] had similar error messages:
For example, [#109020] and [#109129] had similar error messages:

```
error: internal compiler error: compiler/rustc_middle/src/ty/normalize_erasing_regions.rs:195:90: Failed to normalize <[closure@src/main.rs:36:25: 36:28] as std::ops::FnOnce<(Emplacable<()>,)>>::Output, maybe try to call `try_normalize_erasing_regions` instead
```

```
error: internal compiler error: compiler/rustc_middle/src/ty/normalize_erasing_regions.rs:195:90: Failed to normalize <() as Project>::Assoc, maybe try to call `try_normalize_erasing_regions` instead
```
but different query stacks:

However, they have different query stacks:
```
query stack during panic:
#0 [fn_abi_of_instance] computing call ABI of `<[closure@src/main.rs:36:25: 36:28] as core::ops::function::FnOnce<(Emplacable<()>,)>>::call_once - shim(vtable)`
Expand All @@ -64,7 +66,7 @@ end of query stack

When building a corpus, be sure to avoid collecting tests that are already known to crash rustc.
A fuzzer that is seeded with such tests is more likely to
generate bugs with the same root cause, wasting everyone's time.
generate bugs with the same root cause.
The simplest way to avoid this is to loop over each file in the corpus, see if it causes an
ICE, and remove it if so.

Expand All @@ -73,14 +75,14 @@ To build a corpus, you may want to use:
- The rustc/rust-analyzer/clippy test suites (or even source code) --- though avoid
tests that are already known to cause failures, which often begin with comments
like `//@ failure-status: 101` or `//@ known-bug: #NNN`.
- The already-fixed ICEs in the archived [Glacier][glacier] repository --- though
- The already-fixed ICEs in the archived [Glacier] repository --- though
avoid the unfixed ones in `ices/`!

[glacier]: https://github.com/rust-lang/glacier

## Extra credit

Here are a few things you can do to help the Rust project after filing an ICE.
Here are a few things you can do to help the Rust project after filing an ICE:

- [Bisect][bisect] the bug to figure out when it was introduced.
If you find the regressing PR / commit, you can mark the issue with the label `S-has-bisection`.
Expand Down Expand Up @@ -135,19 +137,18 @@ Of course, it's best to try multiple build configurations and see
what actually results in superior throughput.

You may want to build rustc from source with debug assertions to find
additional bugs, though this is a trade-off: it can slow down fuzzing by
additional bugs, though this can slow down fuzzing by
requiring extra work for every execution.
To enable debug assertions, add this to `bootstrap.toml` when compiling rustc:

```toml
[rust]
debug-assertions = true
rust.debug-assertions = true
```

ICEs that require debug assertions to reproduce should be tagged
[`requires-debug-assertions`][requires-debug-assertions].
ICEs that require debug assertions to reproduce should be tagged
[`requires-debug-assertions`].

[requires-debug-assertions]: https://github.com/rust-lang/rust/labels/requires-debug-assertions
[`requires-debug-assertions`]: https://github.com/rust-lang/rust/labels/requires-debug-assertions

## Existing projects

Expand Down
Loading