550 lines
29 KiB
HTML
550 lines
29 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="light sidebar-visible" dir="ltr">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title>Debugging the compiler - 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/compiler-debugging.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="debugging-the-compiler"><a class="header" href="#debugging-the-compiler">Debugging the compiler</a></h1>
|
|
<ul>
|
|
<li><a href="#configuring-the-compiler">Configuring the compiler</a></li>
|
|
<li><a href="#suppressing-the-ice-file">Suppressing the ICE file</a></li>
|
|
<li><a href="#getting-a-backtrace">Getting a backtrace</a></li>
|
|
<li><a href="#-z-flags"><code>-Z</code> flags</a>
|
|
<ul>
|
|
<li><a href="#getting-a-backtrace-for-errors">Getting a backtrace for errors</a></li>
|
|
<li><a href="#debugging-delayed-bugs">Debugging delayed bugs</a></li>
|
|
<li><a href="#getting-the-error-creation-location">Getting the error creation location</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#getting-logging-output">Getting logging output</a></li>
|
|
<li><a href="#narrowing-bisecting-regressions">Narrowing (Bisecting) Regressions</a></li>
|
|
<li><a href="#downloading-artifacts-from-rusts-ci">Downloading Artifacts from Rust's CI</a></li>
|
|
<li><a href="#rustc_-test-attributes"><code>#[rustc_*]</code> TEST attributes</a>
|
|
<ul>
|
|
<li><a href="#formatting-graphviz-output-dot-files">Formatting Graphviz output (.dot files)</a></li>
|
|
<li><a href="#debugging-type-layouts">Debugging type layouts</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#configuring-codelldb-for-debugging-rustc">Configuring CodeLLDB for debugging <code>rustc</code></a></li>
|
|
</ul>
|
|
<p>This chapter contains a few tips to debug the compiler. These tips aim to be
|
|
useful no matter what you are working on. Some of the other chapters have
|
|
advice about specific parts of the compiler (e.g. the <a href="./incrcomp-debugging.html">Queries Debugging and
|
|
Testing chapter</a> or the <a href="./backend/debugging.html">LLVM Debugging
|
|
chapter</a>).</p>
|
|
<h2 id="configuring-the-compiler"><a class="header" href="#configuring-the-compiler">Configuring the compiler</a></h2>
|
|
<p>By default, rustc is built without most debug information. To enable debug info,
|
|
set <code>debug = true</code> in your bootstrap.toml.</p>
|
|
<p>Setting <code>debug = true</code> turns on many different debug options (e.g., <code>debug-assertions</code>,
|
|
<code>debug-logging</code>, etc.) which can be individually tweaked if you want to, but many people
|
|
simply set <code>debug = true</code>.</p>
|
|
<p>If you want to use GDB to debug rustc, please set <code>bootstrap.toml</code> with options:</p>
|
|
<pre><code class="language-toml">[rust]
|
|
debug = true
|
|
debuginfo-level = 2
|
|
</code></pre>
|
|
<blockquote>
|
|
<p>NOTE:
|
|
This will use a lot of disk space
|
|
(upwards of <!-- date-check Aug 2022 --> 35GB),
|
|
and will take a lot more compile time.
|
|
With <code>debuginfo-level = 1</code> (the default when <code>debug = true</code>),
|
|
you will be able to track the execution path,
|
|
but will lose the symbol information for debugging.</p>
|
|
</blockquote>
|
|
<p>The default configuration will enable <code>symbol-mangling-version</code> v0.
|
|
This requires at least GDB v10.2,
|
|
otherwise you need to disable new symbol-mangling-version in <code>bootstrap.toml</code>.</p>
|
|
<pre><code class="language-toml">[rust]
|
|
new-symbol-mangling = false
|
|
</code></pre>
|
|
<blockquote>
|
|
<p>See the comments in <code>bootstrap.example.toml</code> for more info.</p>
|
|
</blockquote>
|
|
<p>You will need to rebuild the compiler after changing any configuration option.</p>
|
|
<h2 id="suppressing-the-ice-file"><a class="header" href="#suppressing-the-ice-file">Suppressing the ICE file</a></h2>
|
|
<p>By default, if rustc encounters an Internal Compiler Error (ICE) it will dump the ICE contents to an
|
|
ICE file within the current working directory named <code>rustc-ice-<timestamp>-<pid>.txt</code>. If this is
|
|
not desirable, you can prevent the ICE file from being created with <code>RUSTC_ICE=0</code>.</p>
|
|
<h2 id="getting-a-backtrace"><a class="header" href="#getting-a-backtrace">Getting a backtrace</a></h2>
|
|
<p>When you have an ICE (panic in the compiler), you can set
|
|
<code>RUST_BACKTRACE=1</code> to get the stack trace of the <code>panic!</code> like in
|
|
normal Rust programs. IIRC backtraces <strong>don't work</strong> on MinGW,
|
|
sorry. If you have trouble or the backtraces are full of <code>unknown</code>,
|
|
you might want to find some way to use Linux, Mac, or MSVC on Windows.</p>
|
|
<p>In the default configuration (without <code>debug</code> set to <code>true</code>), you don't have line numbers
|
|
enabled, so the backtrace looks like this:</p>
|
|
<pre><code class="language-text">stack backtrace:
|
|
0: std::sys::imp::backtrace::tracing::imp::unwind_backtrace
|
|
1: std::sys_common::backtrace::_print
|
|
2: std::panicking::default_hook::{{closure}}
|
|
3: std::panicking::default_hook
|
|
4: std::panicking::rust_panic_with_hook
|
|
5: std::panicking::begin_panic
|
|
(~~~~ LINES REMOVED BY ME FOR BREVITY ~~~~)
|
|
32: rustc_typeck::check_crate
|
|
33: <std::thread::local::LocalKey<T>>::with
|
|
34: <std::thread::local::LocalKey<T>>::with
|
|
35: rustc::ty::context::TyCtxt::create_and_enter
|
|
36: rustc_driver::driver::compile_input
|
|
37: rustc_driver::run_compiler
|
|
</code></pre>
|
|
<p>If you set <code>debug = true</code>, you will get line numbers for the stack trace.
|
|
Then the backtrace will look like this:</p>
|
|
<pre><code class="language-text">stack backtrace:
|
|
(~~~~ LINES REMOVED BY ME FOR BREVITY ~~~~)
|
|
at /home/user/rust/compiler/rustc_typeck/src/check/cast.rs:110
|
|
7: rustc_typeck::check::cast::CastCheck::check
|
|
at /home/user/rust/compiler/rustc_typeck/src/check/cast.rs:572
|
|
at /home/user/rust/compiler/rustc_typeck/src/check/cast.rs:460
|
|
at /home/user/rust/compiler/rustc_typeck/src/check/cast.rs:370
|
|
(~~~~ LINES REMOVED BY ME FOR BREVITY ~~~~)
|
|
33: rustc_driver::driver::compile_input
|
|
at /home/user/rust/compiler/rustc_driver/src/driver.rs:1010
|
|
at /home/user/rust/compiler/rustc_driver/src/driver.rs:212
|
|
34: rustc_driver::run_compiler
|
|
at /home/user/rust/compiler/rustc_driver/src/lib.rs:253
|
|
</code></pre>
|
|
<h2 id="-z-flags"><a class="header" href="#-z-flags"><code>-Z</code> flags</a></h2>
|
|
<p>The compiler has a bunch of <code>-Z *</code> flags. These are unstable flags that are only
|
|
enabled on nightly. Many of them are useful for debugging. To get a full listing
|
|
of <code>-Z</code> flags, use <code>-Z help</code>.</p>
|
|
<p>One useful flag is <code>-Z verbose-internals</code>, which generally enables printing more
|
|
info that could be useful for debugging.</p>
|
|
<p>Right below you can find elaborate explainers on a selected few.</p>
|
|
<h3 id="getting-a-backtrace-for-errors"><a class="header" href="#getting-a-backtrace-for-errors">Getting a backtrace for errors</a></h3>
|
|
<p>If you want to get a backtrace to the point where the compiler emits an
|
|
error message, you can pass the <code>-Z treat-err-as-bug=n</code>, which will make
|
|
the compiler panic on the <code>nth</code> error. If you leave off <code>=n</code>, the compiler will
|
|
assume <code>1</code> for <code>n</code> and thus panic on the first error it encounters.</p>
|
|
<p>For example:</p>
|
|
<pre><code class="language-bash">$ cat error.rs
|
|
</code></pre>
|
|
<pre><pre class="playground"><code class="language-rust">fn main() {
|
|
1 + ();
|
|
}</code></pre></pre>
|
|
<pre><code>$ rustc +stage1 error.rs
|
|
error[E0277]: cannot add `()` to `{integer}`
|
|
--> error.rs:2:7
|
|
|
|
|
2 | 1 + ();
|
|
| ^ no implementation for `{integer} + ()`
|
|
|
|
|
= help: the trait `Add<()>` is not implemented for `{integer}`
|
|
|
|
error: aborting due to previous error
|
|
</code></pre>
|
|
<p>Now, where does the error above come from?</p>
|
|
<pre><code>$ RUST_BACKTRACE=1 rustc +stage1 error.rs -Z treat-err-as-bug
|
|
error[E0277]: the trait bound `{integer}: std::ops::Add<()>` is not satisfied
|
|
--> error.rs:2:7
|
|
|
|
|
2 | 1 + ();
|
|
| ^ no implementation for `{integer} + ()`
|
|
|
|
|
= help: the trait `std::ops::Add<()>` is not implemented for `{integer}`
|
|
|
|
error: internal compiler error: unexpected panic
|
|
|
|
note: the compiler unexpectedly panicked. this is a bug.
|
|
|
|
note: we would appreciate a bug report: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#bug-reports
|
|
|
|
note: rustc 1.24.0-dev running on x86_64-unknown-linux-gnu
|
|
|
|
note: run with `RUST_BACKTRACE=1` for a backtrace
|
|
|
|
thread 'rustc' panicked at 'encountered error with `-Z treat_err_as_bug',
|
|
/home/user/rust/compiler/rustc_errors/src/lib.rs:411:12
|
|
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose
|
|
backtrace.
|
|
stack backtrace:
|
|
(~~~ IRRELEVANT PART OF BACKTRACE REMOVED BY ME ~~~)
|
|
7: rustc::traits::error_reporting::<impl rustc::infer::InferCtxt<'a, 'tcx>>
|
|
::report_selection_error
|
|
at /home/user/rust/compiler/rustc_middle/src/traits/error_reporting.rs:823
|
|
8: rustc::traits::error_reporting::<impl rustc::infer::InferCtxt<'a, 'tcx>>
|
|
::report_fulfillment_errors
|
|
at /home/user/rust/compiler/rustc_middle/src/traits/error_reporting.rs:160
|
|
at /home/user/rust/compiler/rustc_middle/src/traits/error_reporting.rs:112
|
|
9: rustc_typeck::check::FnCtxt::select_obligations_where_possible
|
|
at /home/user/rust/compiler/rustc_typeck/src/check/mod.rs:2192
|
|
(~~~ IRRELEVANT PART OF BACKTRACE REMOVED BY ME ~~~)
|
|
36: rustc_driver::run_compiler
|
|
at /home/user/rust/compiler/rustc_driver/src/lib.rs:253
|
|
</code></pre>
|
|
<p>Cool, now I have a backtrace for the error!</p>
|
|
<h3 id="debugging-delayed-bugs"><a class="header" href="#debugging-delayed-bugs">Debugging delayed bugs</a></h3>
|
|
<p>The <code>-Z eagerly-emit-delayed-bugs</code> option makes it easy to debug delayed bugs.
|
|
It turns them into normal errors, i.e. makes them visible. This can be used in
|
|
combination with <code>-Z treat-err-as-bug</code> to stop at a particular delayed bug and
|
|
get a backtrace.</p>
|
|
<h3 id="getting-the-error-creation-location"><a class="header" href="#getting-the-error-creation-location">Getting the error creation location</a></h3>
|
|
<p><code>-Z track-diagnostics</code> can help figure out where errors are emitted. It uses <code>#[track_caller]</code>
|
|
for this and prints its location alongside the error:</p>
|
|
<pre><code>$ RUST_BACKTRACE=1 rustc +stage1 error.rs -Z track-diagnostics
|
|
error[E0277]: cannot add `()` to `{integer}`
|
|
--> src\error.rs:2:7
|
|
|
|
|
2 | 1 + ();
|
|
| ^ no implementation for `{integer} + ()`
|
|
-Ztrack-diagnostics: created at compiler/rustc_trait_selection/src/traits/error_reporting/mod.rs:638:39
|
|
|
|
|
= help: the trait `Add<()>` is not implemented for `{integer}`
|
|
= help: the following other types implement trait `Add<Rhs>`:
|
|
<&'a f32 as Add<f32>>
|
|
<&'a f64 as Add<f64>>
|
|
<&'a i128 as Add<i128>>
|
|
<&'a i16 as Add<i16>>
|
|
<&'a i32 as Add<i32>>
|
|
<&'a i64 as Add<i64>>
|
|
<&'a i8 as Add<i8>>
|
|
<&'a isize as Add<isize>>
|
|
and 48 others
|
|
|
|
For more information about this error, try `rustc --explain E0277`.
|
|
</code></pre>
|
|
<p>This is similar but different to <code>-Z treat-err-as-bug</code>:</p>
|
|
<ul>
|
|
<li>it will print the locations for all errors emitted</li>
|
|
<li>it does not require a compiler built with debug symbols</li>
|
|
<li>you don't have to read through a big stack trace.</li>
|
|
</ul>
|
|
<h2 id="getting-logging-output"><a class="header" href="#getting-logging-output">Getting logging output</a></h2>
|
|
<p>The compiler uses the <a href="https://docs.rs/tracing"><code>tracing</code></a> crate for logging.</p>
|
|
<p>For details see <a href="./tracing.html">the guide section on tracing</a></p>
|
|
<h2 id="narrowing-bisecting-regressions"><a class="header" href="#narrowing-bisecting-regressions">Narrowing (Bisecting) Regressions</a></h2>
|
|
<p>The <a href="https://github.com/rust-lang/cargo-bisect-rustc">cargo-bisect-rustc</a> tool can be used as a quick and easy way to
|
|
find exactly which PR caused a change in <code>rustc</code> behavior. It automatically
|
|
downloads <code>rustc</code> PR artifacts and tests them against a project you provide
|
|
until it finds the regression. You can then look at the PR to get more context
|
|
on <em>why</em> it was changed. See <a href="https://rust-lang.github.io/cargo-bisect-rustc/tutorial.html">this tutorial</a> on how to use
|
|
it.</p>
|
|
<h2 id="downloading-artifacts-from-rusts-ci"><a class="header" href="#downloading-artifacts-from-rusts-ci">Downloading Artifacts from Rust's CI</a></h2>
|
|
<p>The <a href="https://github.com/kennytm/rustup-toolchain-install-master">rustup-toolchain-install-master</a> tool by kennytm can be used to
|
|
download the artifacts produced by Rust's CI for a specific SHA1 -- this
|
|
basically corresponds to the successful landing of some PR -- and then sets
|
|
them up for your local use. This also works for artifacts produced by <code>@bors try</code>. This is helpful when you want to examine the resulting build of a PR
|
|
without doing the build yourself.</p>
|
|
<h2 id="rustc_-test-attributes"><a class="header" href="#rustc_-test-attributes"><code>#[rustc_*]</code> TEST attributes</a></h2>
|
|
<p>The compiler defines a whole lot of internal (perma-unstable) attributes some of which are useful
|
|
for debugging by dumping extra compiler-internal information. These are prefixed with <code>rustc_</code> and
|
|
are gated behind the internal feature <code>rustc_attrs</code> (enabled via e.g. <code>#![feature(rustc_attrs)]</code>).</p>
|
|
<p>For a complete and up to date list, see <a href="https://github.com/rust-lang/rust/blob/master/compiler/rustc_feature/src/builtin_attrs.rs"><code>builtin_attrs</code></a>. More specifically, the ones marked <code>TEST</code>.
|
|
Here are some notable ones:</p>
|
|
<div class="table-wrapper"><table><thead><tr><th>Attribute</th><th>Description</th></tr></thead><tbody>
|
|
<tr><td><code>rustc_def_path</code></td><td>Dumps the <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.def_path_str"><code>def_path_str</code></a> of an item.</td></tr>
|
|
<tr><td><code>rustc_dump_def_parents</code></td><td>Dumps the chain of <code>DefId</code> parents of certain definitions.</td></tr>
|
|
<tr><td><code>rustc_dump_item_bounds</code></td><td>Dumps the <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.item_bounds"><code>item_bounds</code></a> of an item.</td></tr>
|
|
<tr><td><code>rustc_dump_predicates</code></td><td>Dumps the <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.predicates_of"><code>predicates_of</code></a> an item.</td></tr>
|
|
<tr><td><code>rustc_dump_vtable</code></td><td>Dumps the vtable layout of an impl, or a type alias of a dyn type.</td></tr>
|
|
<tr><td><code>rustc_hidden_type_of_opaques</code></td><td>Dumps the <a href="./opaque-types-impl-trait-inference.html">hidden type of each opaque types</a> in the crate.</td></tr>
|
|
<tr><td><code>rustc_layout</code></td><td><a href="#debugging-type-layouts">See this section</a>.</td></tr>
|
|
<tr><td><code>rustc_object_lifetime_default</code></td><td>Dumps the <a href="https://doc.rust-lang.org/reference/lifetime-elision.html#default-trait-object-lifetimes">object lifetime defaults</a> of an item.</td></tr>
|
|
<tr><td><code>rustc_outlives</code></td><td>Dumps implied bounds of an item. More precisely, the <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.inferred_outlives_of"><code>inferred_outlives_of</code></a> an item.</td></tr>
|
|
<tr><td><code>rustc_regions</code></td><td>Dumps NLL closure region requirements.</td></tr>
|
|
<tr><td><code>rustc_symbol_name</code></td><td>Dumps the mangled & demangled <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.symbol_name"><code>symbol_name</code></a> of an item.</td></tr>
|
|
<tr><td><code>rustc_variances</code></td><td>Dumps the <a href="./variance.html">variances</a> of an item.</td></tr>
|
|
</tbody></table>
|
|
</div>
|
|
<p>Right below you can find elaborate explainers on a selected few.</p>
|
|
<h3 id="formatting-graphviz-output-dot-files"><a class="header" href="#formatting-graphviz-output-dot-files">Formatting Graphviz output (.dot files)</a></h3>
|
|
<p>Some compiler options for debugging specific features yield graphviz graphs -
|
|
e.g. the <code>#[rustc_mir(borrowck_graphviz_postflow="suffix.dot")]</code> attribute
|
|
on a function dumps various borrow-checker dataflow graphs in conjunction with
|
|
<code>-Zdump-mir-dataflow</code>.</p>
|
|
<p>These all produce <code>.dot</code> files. To view these files, install graphviz (e.g.
|
|
<code>apt-get install graphviz</code>) and then run the following commands:</p>
|
|
<pre><code class="language-bash">$ dot -T pdf maybe_init_suffix.dot > maybe_init_suffix.pdf
|
|
$ firefox maybe_init_suffix.pdf # Or your favorite pdf viewer
|
|
</code></pre>
|
|
<h3 id="debugging-type-layouts"><a class="header" href="#debugging-type-layouts">Debugging type layouts</a></h3>
|
|
<p>The internal attribute <code>#[rustc_layout]</code> can be used to dump the <a href="https://doc.rust-lang.org/nightly/nightly-rustc/stable_mir/abi/struct.Layout.html"><code>Layout</code></a> of
|
|
the type it is attached to. For example:</p>
|
|
<pre><pre class="playground"><code class="language-rust"><span class="boring">#![allow(unused)]
|
|
</span>#![feature(rustc_attrs)]
|
|
|
|
<span class="boring">fn main() {
|
|
</span>#[rustc_layout(debug)]
|
|
type T<'a> = &'a u32;
|
|
<span class="boring">}</span></code></pre></pre>
|
|
<p>Will emit the following:</p>
|
|
<pre><code class="language-text">error: layout_of(&'a u32) = Layout {
|
|
fields: Primitive,
|
|
variants: Single {
|
|
index: 0,
|
|
},
|
|
abi: Scalar(
|
|
Scalar {
|
|
value: Pointer,
|
|
valid_range: 1..=18446744073709551615,
|
|
},
|
|
),
|
|
largest_niche: Some(
|
|
Niche {
|
|
offset: Size {
|
|
raw: 0,
|
|
},
|
|
scalar: Scalar {
|
|
value: Pointer,
|
|
valid_range: 1..=18446744073709551615,
|
|
},
|
|
},
|
|
),
|
|
align: AbiAndPrefAlign {
|
|
abi: Align {
|
|
pow2: 3,
|
|
},
|
|
pref: Align {
|
|
pow2: 3,
|
|
},
|
|
},
|
|
size: Size {
|
|
raw: 8,
|
|
},
|
|
}
|
|
--> src/lib.rs:4:1
|
|
|
|
|
4 | type T<'a> = &'a u32;
|
|
| ^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
error: aborting due to previous error
|
|
</code></pre>
|
|
<h2 id="configuring-codelldb-for-debugging-rustc"><a class="header" href="#configuring-codelldb-for-debugging-rustc">Configuring CodeLLDB for debugging <code>rustc</code></a></h2>
|
|
<p>If you are using VSCode, and have edited your <code>bootstrap.toml</code> to request debugging
|
|
level 1 or 2 for the parts of the code you're interested in, then you should be
|
|
able to use the <a href="https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb">CodeLLDB</a> extension in VSCode to debug it.</p>
|
|
<p>Here is a sample <code>launch.json</code> file, being used to run a stage 1 compiler direct
|
|
from the directory where it is built (does not have to be "installed"):</p>
|
|
<pre><code class="language-javascript">// .vscode/launch.json
|
|
{
|
|
"version": "0.2.0",
|
|
"configurations": [
|
|
{
|
|
"type": "lldb",
|
|
"request": "launch",
|
|
"name": "Launch",
|
|
"args": [], // array of string command-line arguments to pass to compiler
|
|
"program": "${workspaceFolder}/build/host/stage1/bin/rustc",
|
|
"windows": { // applicable if using windows
|
|
"program": "${workspaceFolder}/build/host/stage1/bin/rustc.exe"
|
|
},
|
|
"cwd": "${workspaceFolder}", // current working directory at program start
|
|
"stopOnEntry": false,
|
|
"sourceLanguages": ["rust"]
|
|
}
|
|
]
|
|
}
|
|
</code></pre>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
<a rel="prev" href="tests/misc.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="tracing.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="tests/misc.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="tracing.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>
|