From 6cc6ef0a738c1b6d2af9558f324fd65bd6ced001 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Le=C3=B3n=20Orell=20Valerian=20Liehr?= Date: Thu, 22 Aug 2024 17:56:19 +0200 Subject: [PATCH 1/3] Restructure chapter on compiler debugging 1. Make sections about specific `-Z` flags subsections of the `-Z` flag overview section 2. Introduce overview section for internal `rustc_*` attributes 3. Make sections about specific `rustc_*` attributes subsections of this new section --- src/compiler-debugging.md | 74 +++++++++++++++++++++++---------------- 1 file changed, 44 insertions(+), 30 deletions(-) diff --git a/src/compiler-debugging.md b/src/compiler-debugging.md index 5a897a0bb..105074f4d 100644 --- a/src/compiler-debugging.md +++ b/src/compiler-debugging.md @@ -52,15 +52,6 @@ By default, if rustc encounters an Internal Compiler Error (ICE) it will dump th ICE file within the current working directory named `rustc-ice--.txt`. If this is not desirable, you can prevent the ICE file from being created with `RUSTC_ICE=0`. -## `-Z` flags - -The compiler has a bunch of `-Z` flags. These are unstable flags that are only -enabled on nightly. Many of them are useful for debugging. To get a full listing -of `-Z` flags, use `-Z help`. - -One useful flag is `-Z verbose-internals`, which generally enables printing more -info that could be useful for debugging. - ## Getting a backtrace [getting-a-backtrace]: #getting-a-backtrace @@ -109,7 +100,18 @@ stack backtrace: at /home/user/rust/compiler/rustc_driver/src/lib.rs:253 ``` -## Getting a backtrace for errors +## `-Z` flags + +The compiler has a bunch of `-Z *` flags. These are unstable flags that are only +enabled on nightly. Many of them are useful for debugging. To get a full listing +of `-Z` flags, use `-Z help`. + +One useful flag is `-Z verbose-internals`, which generally enables printing more +info that could be useful for debugging. + +Right below you can find elaborate explainers on a selected few. + +### Getting a backtrace for errors [getting-a-backtrace-for-errors]: #getting-a-backtrace-for-errors If you want to get a backtrace to the point where the compiler emits an @@ -186,14 +188,14 @@ stack backtrace: Cool, now I have a backtrace for the error! -## Debugging delayed bugs +### Debugging delayed bugs The `-Z eagerly-emit-delayed-bugs` 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 `-Z treat-err-as-bug` to stop at a particular delayed bug and get a backtrace. -## Getting the error creation location +### Getting the error creation location `-Z track-diagnostics` can help figure out where errors are emitted. It uses `#[track_caller]` for this and prints its location alongside the error: @@ -235,21 +237,6 @@ The compiler uses the [`tracing`] crate for logging. For details see [the guide section on tracing](./tracing.md) -## Formatting Graphviz output (.dot files) -[formatting-graphviz-output]: #formatting-graphviz-output - -Some compiler options for debugging specific features yield graphviz graphs - -e.g. the `#[rustc_mir(borrowck_graphviz_postflow="suffix.dot")]` attribute -dumps various borrow-checker dataflow graphs. - -These all produce `.dot` files. To view these files, install graphviz (e.g. -`apt-get install graphviz`) and then run the following commands: - -```bash -$ dot -T pdf maybe_init_suffix.dot > maybe_init_suffix.pdf -$ firefox maybe_init_suffix.pdf # Or your favorite pdf viewer -``` - ## Narrowing (Bisecting) Regressions The [cargo-bisect-rustc][bisect] tool can be used as a quick and easy way to @@ -273,10 +260,37 @@ without doing the build yourself. [rtim]: https://github.com/kennytm/rustup-toolchain-install-master -## Debugging type layouts +## `#[rustc_*]` TEST attributes + +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 `rustc_` and +are gated behind the internal feature `rustc_attrs` (enabled via e.g. `#![feature(rustc_attrs)]`). + +For a complete and up to date list, see [`builtin_attrs`]. More specifically, the ones marked `TEST`. + +Right below you can find elaborate explainers on a selected few. + +[`builtin_attrs`]: https://github.com/rust-lang/rust/blob/master/compiler/rustc_feature/src/builtin_attrs.rs + +### Formatting Graphviz output (.dot files) +[formatting-graphviz-output]: #formatting-graphviz-output + +Some compiler options for debugging specific features yield graphviz graphs - +e.g. the `#[rustc_mir(borrowck_graphviz_postflow="suffix.dot")]` attribute +dumps various borrow-checker dataflow graphs. + +These all produce `.dot` files. To view these files, install graphviz (e.g. +`apt-get install graphviz`) and then run the following commands: + +```bash +$ dot -T pdf maybe_init_suffix.dot > maybe_init_suffix.pdf +$ firefox maybe_init_suffix.pdf # Or your favorite pdf viewer +``` + +### Debugging type layouts -The (permanently) unstable `#[rustc_layout]` attribute can be used to dump -the [`Layout`] of the type it is attached to. For example: +The internal attribute `#[rustc_layout]` can be used to dump the [`Layout`] of +the type it is attached to. For example: ```rust #![feature(rustc_attrs)] From fa362ade53cac6094df242396c9df3f5899d0c4a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Le=C3=B3n=20Orell=20Valerian=20Liehr?= Date: Thu, 22 Aug 2024 19:04:24 +0200 Subject: [PATCH 2/3] List several TEST rustc_* attrs --- src/compiler-debugging.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/src/compiler-debugging.md b/src/compiler-debugging.md index 105074f4d..162ea525f 100644 --- a/src/compiler-debugging.md +++ b/src/compiler-debugging.md @@ -267,10 +267,34 @@ for debugging by dumping extra compiler-internal information. These are prefixed are gated behind the internal feature `rustc_attrs` (enabled via e.g. `#![feature(rustc_attrs)]`). For a complete and up to date list, see [`builtin_attrs`]. More specifically, the ones marked `TEST`. +Here are some notable ones: + +| Attribute | Description | +|----------------|-------------| +| `rustc_def_path` | Dumps the [`def_path_str`] of an item. | +| `rustc_dump_def_parents` | Dumps the chain of `DefId` parents of certain definitions. | +| `rustc_dump_item_bounds` | Dumps the [`item_bounds`] of an item. | +| `rustc_dump_predicates` | Dumps the [`predicates_of`] an item. | +| `rustc_dump_vtable` | | +| `rustc_hidden_type_of_opaques` | Dumps the [hidden type of all opaque types][opaq] in the crate. | +| `rustc_layout` | [See this section](#debugging-type-layouts). | +| `rustc_object_lifetime_default` | Dumps the [object lifetime defaults] of an item. | +| `rustc_outlives` | Dumps implied bounds of an item. More precisely, the [`inferred_outlives_of`] an item. | +| `rustc_regions` | Dumps NLL closure region requirements. | +| `rustc_symbol_name` | Dumps the mangled & demangled [`symbol_name`] of an item. | +| `rustc_variances` | Dumps the [variances] of an item. | Right below you can find elaborate explainers on a selected few. [`builtin_attrs`]: https://github.com/rust-lang/rust/blob/master/compiler/rustc_feature/src/builtin_attrs.rs +[`def_path_str`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.def_path_str +[`inferred_outlives_of`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.inferred_outlives_of +[`item_bounds`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.item_bounds +[`predicates_of`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.predicates_of +[`symbol_name`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.symbol_name +[object lifetime defaults]: https://doc.rust-lang.org/reference/lifetime-elision.html#default-trait-object-lifetimes +[opaq]: ./opaque-types-impl-trait-inference.md +[variances]: ./variance.md ### Formatting Graphviz output (.dot files) [formatting-graphviz-output]: #formatting-graphviz-output From e7396aa3b1b4cafb2695c4ae93a8695da1c45d72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Le=C3=B3n=20Orell=20Valerian=20Liehr?= Date: Thu, 22 Aug 2024 19:50:52 +0200 Subject: [PATCH 3/3] Add section about `rustc_*` TEST attrs to UI test chapter --- src/tests/ui.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/src/tests/ui.md b/src/tests/ui.md index 32854e5e7..018b176db 100644 --- a/src/tests/ui.md +++ b/src/tests/ui.md @@ -530,3 +530,16 @@ run something like the following to generate the alternate stderr file: ``` Currently none of the compare modes are checked in CI for UI tests. + +## `rustc_*` TEST attributes + +The compiler defines several perma-unstable `#[rustc_*]` attributes gated behind the internal feature +`rustc_attrs` that dump extra compiler-internal information. See the analogous subsection in +[compiler debugging] for more details. + +They can be used in tests to more precisely, legibly and easily test internal compiler state in cases +where it would otherwise be very hard to do the same with "user-facing" Rust alone. Indeed, one could +say that this slightly abuses the term "UI" (*user* interfacing) and turns such UI tests from black-box +tests into white-box ones. Use them carefully and sparingly. + +[compiler debugging]: ../compiler-debugging.md#rustc_-attributes