fuzzing.html - rust-lang/rustc-dev-guide - Git at Google

 <!DOCTYPE HTML>
 <html lang="en" class="light sidebar-visible" dir="ltr">
     <head>
         <!-- Book generated using mdBook -->
         <meta charset="UTF-8">
         <title>Fuzzing - Rust Compiler Development Guide</title>


         <!-- Custom HTML head -->

         <meta name="description" content="A guide to developing the Rust compiler (rustc)">
         <meta name="viewport" content="width=device-width, initial-scale=1">
         <meta name="theme-color" content="#ffffff">

         <link rel="icon" href="favicon.svg">
         <link rel="shortcut icon" href="favicon.png">
         <link rel="stylesheet" href="css/variables.css">
         <link rel="stylesheet" href="css/general.css">
         <link rel="stylesheet" href="css/chrome.css">
         <link rel="stylesheet" href="css/print.css" media="print">

         <!-- Fonts -->
         <link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
         <link rel="stylesheet" href="fonts/fonts.css">

         <!-- Highlight.js Stylesheets -->
         <link rel="stylesheet" id="highlight-css" href="highlight.css">
         <link rel="stylesheet" id="tomorrow-night-css" href="tomorrow-night.css">
         <link rel="stylesheet" id="ayu-highlight-css" href="ayu-highlight.css">

         <!-- Custom theme stylesheets -->


         <!-- Provide site root and default themes to javascript -->
         <script>
             const path_to_root = "";
             const default_light_theme = "light";
             const default_dark_theme = "navy";
         </script>
         <!-- Start loading toc.js asap -->
         <script src="toc.js"></script>
     </head>
     <body>
     <div id="body-container">
         <!-- Work around some values being stored in localStorage wrapped in quotes -->
         <script>
             try {
                 let theme = localStorage.getItem('mdbook-theme');
                 let sidebar = localStorage.getItem('mdbook-sidebar');

                 if (theme.startsWith('"') && theme.endsWith('"')) {
                     localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
                 }

                 if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
                     localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
                 }
             } catch (e) { }
         </script>

         <!-- Set the theme before any content is loaded, prevents flash -->
         <script>
             const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
             let theme;
             try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
             if (theme === null || theme === undefined) { theme = default_theme; }
             const html = document.documentElement;
             html.classList.remove('light')
             html.classList.add(theme);
             html.classList.add("js");
         </script>

         <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">

         <!-- Hide / unhide sidebar before it is displayed -->
         <script>
             let sidebar = null;
             const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
             if (document.body.clientWidth >= 1080) {
                 try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
                 sidebar = sidebar || 'visible';
             } else {
                 sidebar = 'hidden';
             }
             sidebar_toggle.checked = sidebar === 'visible';
             html.classList.remove('sidebar-visible');
             html.classList.add("sidebar-" + sidebar);
         </script>

         <nav id="sidebar" class="sidebar" aria-label="Table of contents">
             <!-- populated by js -->
             <mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
             <noscript>
                 <iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
             </noscript>
             <div id="sidebar-resize-handle" class="sidebar-resize-handle">
                 <div class="sidebar-resize-indicator"></div>
             </div>
         </nav>

         <div id="page-wrapper" class="page-wrapper">

             <div class="page">
                 <div id="menu-bar-hover-placeholder"></div>
                 <div id="menu-bar" class="menu-bar sticky">
                     <div class="left-buttons">
                         <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
                             <i class="fa fa-bars"></i>
                         </label>
                         <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
                             <i class="fa fa-paint-brush"></i>
                         </button>
                         <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
                             <li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
                         </ul>
                         <button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
                             <i class="fa fa-search"></i>
                         </button>
                     </div>

                     <h1 class="menu-title">Rust Compiler Development Guide</h1>

                     <div class="right-buttons">
                         <a href="print.html" title="Print this book" aria-label="Print this book">
                             <i id="print-button" class="fa fa-print"></i>
                         </a>
                         <a href="https://github.com/rust-lang/rustc-dev-guide" title="Git repository" aria-label="Git repository">
                             <i id="git-repository-button" class="fa fa-github"></i>
                         </a>
                         <a href="https://github.com/rust-lang/rustc-dev-guide/edit/master/src/fuzzing.md" title="Suggest an edit" aria-label="Suggest an edit">
                             <i id="git-edit-button" class="fa fa-edit"></i>
                         </a>

                     </div>
                 </div>

                 <div id="search-wrapper" class="hidden">
                     <form id="searchbar-outer" class="searchbar-outer">
                         <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
                     </form>
                     <div id="searchresults-outer" class="searchresults-outer hidden">
                         <div id="searchresults-header" class="searchresults-header"></div>
                         <ul id="searchresults">
                         </ul>
                     </div>
                 </div>

                 <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
                 <script>
                     document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
                     document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
                     Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
                         link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
                     });
                 </script>

                 <div id="content" class="content">
                     <main>
                         <h1 id="fuzzing"><a class="header" href="#fuzzing">Fuzzing</a></h1>
 <!-- date-check: Mar 2023 -->
 <p>For the purposes of this guide, <em>fuzzing</em> 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.
 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
 project, please read this guide before reporting fuzzer-generated bugs!</p>
 <h2 id="guidelines"><a class="header" href="#guidelines">Guidelines</a></h2>
 <h3 id="in-a-nutshell"><a class="header" href="#in-a-nutshell">In a nutshell</a></h3>
 <p><em>Please do:</em></p>
 <ul>
 <li>Ensure the bug is still present on the latest nightly rustc</li>
 <li>Include a reasonably minimal, standalone example along with any bug report</li>
 <li>Include all of the information requested in the bug report template</li>
 <li>Search for existing reports with the same message and query stack</li>
 <li>Format the test case with <code>rustfmt</code>, if it maintains the bug</li>
 <li>Indicate that the bug was found by fuzzing</li>
 </ul>
 <p><em>Please don't:</em></p>
 <ul>
 <li>Don't report lots of bugs that use internal features, including but not
 limited to <code>custom_mir</code>, <code>lang_items</code>, <code>no_core</code>, and <code>rustc_attrs</code>.</li>
 <li>Don't seed your fuzzer with inputs that are known to crash rustc (details
 below).</li>
 </ul>
 <h3 id="discussion"><a class="header" href="#discussion">Discussion</a></h3>
 <p>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 <em>query stacks</em>
 are usually distinct bugs. For example, <a href="https://github.com/rust-lang/rust/issues/109020">#109020</a> and <a href="https://github.com/rust-lang/rust/issues/109129">#109129</a>
 had similar error messages:</p>
 <pre><code>error: internal compiler error: compiler/rustc_middle/src/ty/normalize_erasing_regions.rs:195:90: Failed to normalize &lt;[closure@src/main.rs:36:25: 36:28] as std::ops::FnOnce&lt;(Emplacable&lt;()&gt;,)&gt;&gt;::Output, maybe try to call `try_normalize_erasing_regions` instead
 </code></pre>
 <pre><code>error: internal compiler error: compiler/rustc_middle/src/ty/normalize_erasing_regions.rs:195:90: Failed to normalize &lt;() as Project&gt;::Assoc, maybe try to call `try_normalize_erasing_regions` instead
 </code></pre>
 <p>but different query stacks:</p>
 <pre><code>query stack during panic:
 #0 [fn_abi_of_instance] computing call ABI of `&lt;[closure@src/main.rs:36:25: 36:28] as core::ops::function::FnOnce&lt;(Emplacable&lt;()&gt;,)&gt;&gt;::call_once - shim(vtable)`
 end of query stack
 </code></pre>
 <pre><code>query stack during panic:
 #0 [check_mod_attrs] checking attributes in top-level module
 #1 [analysis] running analysis passes on this crate
 end of query stack
 </code></pre>
 <h2 id="building-a-corpus"><a class="header" href="#building-a-corpus">Building a corpus</a></h2>
 <p>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. 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.</p>
 <p>To build a corpus, you may want to use:</p>
 <ul>
 <li>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 <code>//@ failure-status: 101</code> or <code>//@ known-bug: #NNN</code>.</li>
 <li>The already-fixed ICEs in the archived <a href="https://github.com/rust-lang/glacier">Glacier</a> repository --- though
 avoid the unfixed ones in <code>ices/</code>!</li>
 </ul>
 <h2 id="extra-credit"><a class="header" href="#extra-credit">Extra credit</a></h2>
 <p>Here are a few things you can do to help the Rust project after filing an ICE.</p>
 <ul>
 <li><a href="https://rust-lang.github.io/cargo-bisect-rustc/">Bisect</a> the bug to figure out when it was introduced.
 If you find the regressing PR / commit, you can mark the issue with the label
 <code>S-has-bisection</code>. If not, consider applying <code>E-needs-bisection</code> instead.</li>
 <li>Fix "distractions": problems with the test case that don't contribute to
 triggering the ICE, such as syntax errors or borrow-checking errors</li>
 <li>Minimize the test case (see below). If successful, you can label the
 issue with <code>S-has-mcve</code>. Otherwise, you can apply <code>E-needs-mcve</code>.</li>
 <li>Add the minimal test case to the rust-lang/rust repo as a <a href="tests/compiletest.html#crashes-tests">crashes test</a>.
 While you're at it, consider including other "untracked" crashes in your PR.
 Please don't forget to mark your issue with <code>S-bug-has-test</code> afterwards.</li>
 </ul>
 <p>See also <a href="https://forge.rust-lang.org/release/issue-triaging.html#applying-and-removing-labels">applying and removing labels</a>.</p>
 <h2 id="minimization"><a class="header" href="#minimization">Minimization</a></h2>
 <p>It is helpful to carefully <em>minimize</em> the fuzzer-generated input. When
 minimizing, be careful to preserve the original error, and avoid introducing
 distracting problems such as syntax, type-checking, or borrow-checking errors.</p>
 <p>There are some tools that can help with minimization. If you're not sure how
 to avoid introducing syntax, type-, and borrow-checking errors while using
 these tools, post both the complete and minimized test cases. Generally,
 <em>syntax-aware</em> tools give the best results in the least amount of time.
 <a href="https://github.com/langston-barrett/treereduce"><code>treereduce-rust</code></a> and <a href="https://github.com/renatahodovan/picireny">picireny</a> are syntax-aware.
 <a href="https://github.com/googleprojectzero/halfempty"><code>halfempty</code></a> is not, but is generally a high-quality tool.</p>
 <h2 id="effective-fuzzing"><a class="header" href="#effective-fuzzing">Effective fuzzing</a></h2>
 <p>When fuzzing rustc, you may want to avoid generating machine code, since this
 is mostly done by LLVM. Try <code>--emit=mir</code> instead.</p>
 <p>A variety of compiler flags can uncover different issues. <code>-Zmir-opt-level=4</code>
 will turn on MIR optimization passes that are not run by default, potentially
 uncovering interesting bugs. <code>-Zvalidate-mir</code> can help uncover such bugs.</p>
 <p>If you're fuzzing a compiler you built, you may want to build it with <code>-C target-cpu=native</code> or even PGO/BOLT to squeeze out a few more executions per
 second. Of course, it's best to try multiple build configurations and see
 what actually results in superior throughput.</p>
 <p>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
 requiring extra work for every execution. To enable debug assertions, add this
 to <code>bootstrap.toml</code> when compiling rustc:</p>
 <pre><code class="language-toml">[rust]
 debug-assertions = true
 </code></pre>
 <p>ICEs that require debug assertions to reproduce should be tagged
 <a href="https://github.com/rust-lang/rust/labels/requires-debug-assertions"><code>requires-debug-assertions</code></a>.</p>
 <h2 id="existing-projects"><a class="header" href="#existing-projects">Existing projects</a></h2>
 <ul>
 <li><a href="https://github.com/dwrensha/fuzz-rustc">fuzz-rustc</a> demonstrates how to fuzz rustc with libfuzzer</li>
 <li><a href="https://github.com/matthiaskrgr/icemaker/">icemaker</a> runs rustc and other tools on a large number of source
 files with a variety of flags to catch ICEs</li>
 <li><a href="https://github.com/langston-barrett/tree-splicer/">tree-splicer</a> generates new source files by combining existing
 ones while maintaining correct syntax</li>
 </ul>

                     </main>

                     <nav class="nav-wrapper" aria-label="Page navigation">
                         <!-- Mobile navigation buttons -->
                             <a rel="prev" href="external-repos.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                                 <i class="fa fa-angle-left"></i>
                             </a>

                             <a rel="next prefetch" href="notification-groups/about.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                 <i class="fa fa-angle-right"></i>
                             </a>

                         <div style="clear: both"></div>
                     </nav>
                 </div>
             </div>

             <nav class="nav-wide-wrapper" aria-label="Page navigation">
                     <a rel="prev" href="external-repos.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                         <i class="fa fa-angle-left"></i>
                     </a>

                     <a rel="next prefetch" href="notification-groups/about.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                         <i class="fa fa-angle-right"></i>
                     </a>
             </nav>

         </div>


         <script>
             window.playground_copyable = true;
         </script>


         <script src="elasticlunr.min.js"></script>
         <script src="mark.min.js"></script>
         <script src="searcher.js"></script>

         <script src="clipboard.min.js"></script>
         <script src="highlight.js"></script>
         <script src="book.js"></script>

         <!-- Custom JS scripts -->
         <script src="mermaid.min.js"></script>
         <script src="mermaid-init.js"></script>


     </div>
     </body>
 </html>
	<!DOCTYPE HTML>
	<html lang="en" class="light sidebar-visible" dir="ltr">
	<head>
	<!-- Book generated using mdBook -->
	<meta charset="UTF-8">
	<title>Fuzzing - Rust Compiler Development Guide</title>


	<!-- Custom HTML head -->

	<meta name="description" content="A guide to developing the Rust compiler (rustc)">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<meta name="theme-color" content="#ffffff">

	<link rel="icon" href="favicon.svg">
	<link rel="shortcut icon" href="favicon.png">
	<link rel="stylesheet" href="css/variables.css">
	<link rel="stylesheet" href="css/general.css">
	<link rel="stylesheet" href="css/chrome.css">
	<link rel="stylesheet" href="css/print.css" media="print">

	<!-- Fonts -->
	<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
	<link rel="stylesheet" href="fonts/fonts.css">

	<!-- Highlight.js Stylesheets -->
	<link rel="stylesheet" id="highlight-css" href="highlight.css">
	<link rel="stylesheet" id="tomorrow-night-css" href="tomorrow-night.css">
	<link rel="stylesheet" id="ayu-highlight-css" href="ayu-highlight.css">

	<!-- Custom theme stylesheets -->


	<!-- Provide site root and default themes to javascript -->
	<script>
	const path_to_root = "";
	const default_light_theme = "light";
	const default_dark_theme = "navy";
	</script>
	<!-- Start loading toc.js asap -->
	<script src="toc.js"></script>
	</head>
	<body>
	<div id="body-container">
	<!-- Work around some values being stored in localStorage wrapped in quotes -->
	<script>
	try {
	let theme = localStorage.getItem('mdbook-theme');
	let sidebar = localStorage.getItem('mdbook-sidebar');

	if (theme.startsWith('"') && theme.endsWith('"')) {
	localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
	}

	if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
	localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
	}
	} catch (e) { }
	</script>

	<!-- Set the theme before any content is loaded, prevents flash -->
	<script>
	const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
	let theme;
	try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
	if (theme === null \|\| theme === undefined) { theme = default_theme; }
	const html = document.documentElement;
	html.classList.remove('light')
	html.classList.add(theme);
	html.classList.add("js");
	</script>

	<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">

	<!-- Hide / unhide sidebar before it is displayed -->
	<script>
	let sidebar = null;
	const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
	if (document.body.clientWidth >= 1080) {
	try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
	sidebar = sidebar \|\| 'visible';
	} else {
	sidebar = 'hidden';
	}
	sidebar_toggle.checked = sidebar === 'visible';
	html.classList.remove('sidebar-visible');
	html.classList.add("sidebar-" + sidebar);
	</script>

	<nav id="sidebar" class="sidebar" aria-label="Table of contents">
	<!-- populated by js -->
	<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
	<noscript>
	<iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
	</noscript>
	<div id="sidebar-resize-handle" class="sidebar-resize-handle">
	<div class="sidebar-resize-indicator"></div>
	</div>
	</nav>

	<div id="page-wrapper" class="page-wrapper">

	<div class="page">
	<div id="menu-bar-hover-placeholder"></div>
	<div id="menu-bar" class="menu-bar sticky">
	<div class="left-buttons">
	<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
	<i class="fa fa-bars"></i>
	</label>
	<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
	<i class="fa fa-paint-brush"></i>
	</button>
	<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
	<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
	<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
	<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
	<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
	<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
	<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
	</ul>
	<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
	<i class="fa fa-search"></i>
	</button>
	</div>

	<h1 class="menu-title">Rust Compiler Development Guide</h1>

	<div class="right-buttons">
	<a href="print.html" title="Print this book" aria-label="Print this book">
	<i id="print-button" class="fa fa-print"></i>
	</a>
	<a href="https://github.com/rust-lang/rustc-dev-guide" title="Git repository" aria-label="Git repository">
	<i id="git-repository-button" class="fa fa-github"></i>
	</a>
	<a href="https://github.com/rust-lang/rustc-dev-guide/edit/master/src/fuzzing.md" title="Suggest an edit" aria-label="Suggest an edit">
	<i id="git-edit-button" class="fa fa-edit"></i>
	</a>

	</div>
	</div>

	<div id="search-wrapper" class="hidden">
	<form id="searchbar-outer" class="searchbar-outer">
	<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
	</form>
	<div id="searchresults-outer" class="searchresults-outer hidden">
	<div id="searchresults-header" class="searchresults-header"></div>
	<ul id="searchresults">
	</ul>
	</div>
	</div>

	<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
	<script>
	document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
	document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
	Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
	link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
	});
	</script>

	<div id="content" class="content">
	<main>
	<h1 id="fuzzing"><a class="header" href="#fuzzing">Fuzzing</a></h1>
	<!-- date-check: Mar 2023 -->
	<p>For the purposes of this guide, <em>fuzzing</em> 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.
	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
	project, please read this guide before reporting fuzzer-generated bugs!</p>
	<h2 id="guidelines"><a class="header" href="#guidelines">Guidelines</a></h2>
	<h3 id="in-a-nutshell"><a class="header" href="#in-a-nutshell">In a nutshell</a></h3>
	<p><em>Please do:</em></p>
	<ul>
	<li>Ensure the bug is still present on the latest nightly rustc</li>
	<li>Include a reasonably minimal, standalone example along with any bug report</li>
	<li>Include all of the information requested in the bug report template</li>
	<li>Search for existing reports with the same message and query stack</li>
	<li>Format the test case with <code>rustfmt</code>, if it maintains the bug</li>
	<li>Indicate that the bug was found by fuzzing</li>
	</ul>
	<p><em>Please don't:</em></p>
	<ul>
	<li>Don't report lots of bugs that use internal features, including but not
	limited to <code>custom_mir</code>, <code>lang_items</code>, <code>no_core</code>, and <code>rustc_attrs</code>.</li>
	<li>Don't seed your fuzzer with inputs that are known to crash rustc (details
	below).</li>
	</ul>
	<h3 id="discussion"><a class="header" href="#discussion">Discussion</a></h3>
	<p>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 <em>query stacks</em>
	are usually distinct bugs. For example, <a href="https://github.com/rust-lang/rust/issues/109020">#109020</a> and <a href="https://github.com/rust-lang/rust/issues/109129">#109129</a>
	had similar error messages:</p>
	<pre><code>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
	</code></pre>
	<pre><code>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
	</code></pre>
	<p>but different query stacks:</p>
	<pre><code>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)`
	end of query stack
	</code></pre>
	<pre><code>query stack during panic:
	#0 [check_mod_attrs] checking attributes in top-level module
	#1 [analysis] running analysis passes on this crate
	end of query stack
	</code></pre>
	<h2 id="building-a-corpus"><a class="header" href="#building-a-corpus">Building a corpus</a></h2>
	<p>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. 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.</p>
	<p>To build a corpus, you may want to use:</p>
	<ul>
	<li>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 <code>//@ failure-status: 101</code> or <code>//@ known-bug: #NNN</code>.</li>
	<li>The already-fixed ICEs in the archived <a href="https://github.com/rust-lang/glacier">Glacier</a> repository --- though
	avoid the unfixed ones in <code>ices/</code>!</li>
	</ul>
	<h2 id="extra-credit"><a class="header" href="#extra-credit">Extra credit</a></h2>
	<p>Here are a few things you can do to help the Rust project after filing an ICE.</p>
	<ul>
	<li><a href="https://rust-lang.github.io/cargo-bisect-rustc/">Bisect</a> the bug to figure out when it was introduced.
	If you find the regressing PR / commit, you can mark the issue with the label
	<code>S-has-bisection</code>. If not, consider applying <code>E-needs-bisection</code> instead.</li>
	<li>Fix "distractions": problems with the test case that don't contribute to
	triggering the ICE, such as syntax errors or borrow-checking errors</li>
	<li>Minimize the test case (see below). If successful, you can label the
	issue with <code>S-has-mcve</code>. Otherwise, you can apply <code>E-needs-mcve</code>.</li>
	<li>Add the minimal test case to the rust-lang/rust repo as a <a href="tests/compiletest.html#crashes-tests">crashes test</a>.
	While you're at it, consider including other "untracked" crashes in your PR.
	Please don't forget to mark your issue with <code>S-bug-has-test</code> afterwards.</li>
	</ul>
	<p>See also <a href="https://forge.rust-lang.org/release/issue-triaging.html#applying-and-removing-labels">applying and removing labels</a>.</p>
	<h2 id="minimization"><a class="header" href="#minimization">Minimization</a></h2>
	<p>It is helpful to carefully <em>minimize</em> the fuzzer-generated input. When
	minimizing, be careful to preserve the original error, and avoid introducing
	distracting problems such as syntax, type-checking, or borrow-checking errors.</p>
	<p>There are some tools that can help with minimization. If you're not sure how
	to avoid introducing syntax, type-, and borrow-checking errors while using
	these tools, post both the complete and minimized test cases. Generally,
	<em>syntax-aware</em> tools give the best results in the least amount of time.
	<a href="https://github.com/langston-barrett/treereduce"><code>treereduce-rust</code></a> and <a href="https://github.com/renatahodovan/picireny">picireny</a> are syntax-aware.
	<a href="https://github.com/googleprojectzero/halfempty"><code>halfempty</code></a> is not, but is generally a high-quality tool.</p>
	<h2 id="effective-fuzzing"><a class="header" href="#effective-fuzzing">Effective fuzzing</a></h2>
	<p>When fuzzing rustc, you may want to avoid generating machine code, since this
	is mostly done by LLVM. Try <code>--emit=mir</code> instead.</p>
	<p>A variety of compiler flags can uncover different issues. <code>-Zmir-opt-level=4</code>
	will turn on MIR optimization passes that are not run by default, potentially
	uncovering interesting bugs. <code>-Zvalidate-mir</code> can help uncover such bugs.</p>
	<p>If you're fuzzing a compiler you built, you may want to build it with <code>-C target-cpu=native</code> or even PGO/BOLT to squeeze out a few more executions per
	second. Of course, it's best to try multiple build configurations and see
	what actually results in superior throughput.</p>
	<p>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
	requiring extra work for every execution. To enable debug assertions, add this
	to <code>bootstrap.toml</code> when compiling rustc:</p>
	<pre><code class="language-toml">[rust]
	debug-assertions = true
	</code></pre>
	<p>ICEs that require debug assertions to reproduce should be tagged
	<a href="https://github.com/rust-lang/rust/labels/requires-debug-assertions"><code>requires-debug-assertions</code></a>.</p>
	<h2 id="existing-projects"><a class="header" href="#existing-projects">Existing projects</a></h2>
	<ul>
	<li><a href="https://github.com/dwrensha/fuzz-rustc">fuzz-rustc</a> demonstrates how to fuzz rustc with libfuzzer</li>
	<li><a href="https://github.com/matthiaskrgr/icemaker/">icemaker</a> runs rustc and other tools on a large number of source
	files with a variety of flags to catch ICEs</li>
	<li><a href="https://github.com/langston-barrett/tree-splicer/">tree-splicer</a> generates new source files by combining existing
	ones while maintaining correct syntax</li>
	</ul>

	</main>

	<nav class="nav-wrapper" aria-label="Page navigation">
	<!-- Mobile navigation buttons -->
	<a rel="prev" href="external-repos.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
	<i class="fa fa-angle-left"></i>
	</a>

	<a rel="next prefetch" href="notification-groups/about.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
	<i class="fa fa-angle-right"></i>
	</a>

	<div style="clear: both"></div>
	</nav>
	</div>
	</div>

	<nav class="nav-wide-wrapper" aria-label="Page navigation">
	<a rel="prev" href="external-repos.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
	<i class="fa fa-angle-left"></i>
	</a>

	<a rel="next prefetch" href="notification-groups/about.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
	<i class="fa fa-angle-right"></i>
	</a>
	</nav>

	</div>




	<script>
	window.playground_copyable = true;
	</script>


	<script src="elasticlunr.min.js"></script>
	<script src="mark.min.js"></script>
	<script src="searcher.js"></script>

	<script src="clipboard.min.js"></script>
	<script src="highlight.js"></script>
	<script src="book.js"></script>

	<!-- Custom JS scripts -->
	<script src="mermaid.min.js"></script>
	<script src="mermaid-init.js"></script>


	</div>
	</body>
	</html>