| <!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> |
