From d96b2d4398f01dc2cfeb6cd7e2931157fb784a71 Mon Sep 17 00:00:00 2001 From: Boxy Date: Fri, 6 Jun 2025 20:20:06 +0100 Subject: Stub chapter and consolidate under `/hir/` --- src/doc/rustc-dev-guide/src/SUMMARY.md | 5 ++- src/doc/rustc-dev-guide/src/ast-lowering.md | 48 ---------------------- src/doc/rustc-dev-guide/src/diagnostics.md | 2 +- src/doc/rustc-dev-guide/src/hir-debugging.md | 15 ------- src/doc/rustc-dev-guide/src/hir.md | 2 +- .../src/hir/ambig-unambig-ty-and-consts.md | 1 + src/doc/rustc-dev-guide/src/hir/debugging.md | 15 +++++++ src/doc/rustc-dev-guide/src/hir/lowering.md | 48 ++++++++++++++++++++++ src/doc/rustc-dev-guide/src/overview.md | 2 +- 9 files changed, 70 insertions(+), 68 deletions(-) delete mode 100644 src/doc/rustc-dev-guide/src/ast-lowering.md delete mode 100644 src/doc/rustc-dev-guide/src/hir-debugging.md create mode 100644 src/doc/rustc-dev-guide/src/hir/ambig-unambig-ty-and-consts.md create mode 100644 src/doc/rustc-dev-guide/src/hir/debugging.md create mode 100644 src/doc/rustc-dev-guide/src/hir/lowering.md (limited to 'src/doc/rustc-dev-guide') diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md index 2acc3c2199b..50a3f44add3 100644 --- a/src/doc/rustc-dev-guide/src/SUMMARY.md +++ b/src/doc/rustc-dev-guide/src/SUMMARY.md @@ -121,8 +121,9 @@ - [Feature gate checking](./feature-gate-ck.md) - [Lang Items](./lang-items.md) - [The HIR (High-level IR)](./hir.md) - - [Lowering AST to HIR](./ast-lowering.md) - - [Debugging](./hir-debugging.md) + - [Lowering AST to HIR](./hir/lowering.md) + - [Ambig/Unambig Types and Consts](./hir/ambig-unambig-ty-and-consts.md) + - [Debugging](./hir/debugging.md) - [The THIR (Typed High-level IR)](./thir.md) - [The MIR (Mid-level IR)](./mir/index.md) - [MIR construction](./mir/construction.md) diff --git a/src/doc/rustc-dev-guide/src/ast-lowering.md b/src/doc/rustc-dev-guide/src/ast-lowering.md deleted file mode 100644 index 033fd4b76f2..00000000000 --- a/src/doc/rustc-dev-guide/src/ast-lowering.md +++ /dev/null @@ -1,48 +0,0 @@ -# AST lowering - -The AST lowering step converts AST to [HIR](hir.html). -This means many structures are removed if they are irrelevant -for type analysis or similar syntax agnostic analyses. Examples -of such structures include but are not limited to - -* Parenthesis - * Removed without replacement, the tree structure makes order explicit -* `for` loops and `while (let)` loops - * Converted to `loop` + `match` and some `let` bindings -* `if let` - * Converted to `match` -* Universal `impl Trait` - * Converted to generic arguments - (but with some flags, to know that the user didn't write them) -* Existential `impl Trait` - * Converted to a virtual `existential type` declaration - -Lowering needs to uphold several invariants in order to not trigger the -sanity checks in `compiler/rustc_passes/src/hir_id_validator.rs`: - -1. A `HirId` must be used if created. So if you use the `lower_node_id`, - you *must* use the resulting `NodeId` or `HirId` (either is fine, since - any `NodeId`s in the `HIR` are checked for existing `HirId`s) -2. Lowering a `HirId` must be done in the scope of the *owning* item. - This means you need to use `with_hir_id_owner` if you are creating parts - of an item other than the one being currently lowered. This happens for - example during the lowering of existential `impl Trait` -3. A `NodeId` that will be placed into a HIR structure must be lowered, - even if its `HirId` is unused. Calling - `let _ = self.lower_node_id(node_id);` is perfectly legitimate. -4. If you are creating new nodes that didn't exist in the `AST`, you *must* - create new ids for them. This is done by calling the `next_id` method, - which produces both a new `NodeId` as well as automatically lowering it - for you so you also get the `HirId`. - -If you are creating new `DefId`s, since each `DefId` needs to have a -corresponding `NodeId`, it is advisable to add these `NodeId`s to the -`AST` so you don't have to generate new ones during lowering. This has -the advantage of creating a way to find the `DefId` of something via its -`NodeId`. If lowering needs this `DefId` in multiple places, you can't -generate a new `NodeId` in all those places because you'd also get a new -`DefId` then. With a `NodeId` from the `AST` this is not an issue. - -Having the `NodeId` also allows the `DefCollector` to generate the `DefId`s -instead of lowering having to do it on the fly. Centralizing the `DefId` -generation in one place makes it easier to refactor and reason about. diff --git a/src/doc/rustc-dev-guide/src/diagnostics.md b/src/doc/rustc-dev-guide/src/diagnostics.md index 01e59c91904..33f5441d36e 100644 --- a/src/doc/rustc-dev-guide/src/diagnostics.md +++ b/src/doc/rustc-dev-guide/src/diagnostics.md @@ -553,7 +553,7 @@ compiler](#linting-early-in-the-compiler). [AST nodes]: the-parser.md -[AST lowering]: ast-lowering.md +[AST lowering]: ./hir/lowering.md [HIR nodes]: hir.md [MIR nodes]: mir/index.md [macro expansion]: macro-expansion.md diff --git a/src/doc/rustc-dev-guide/src/hir-debugging.md b/src/doc/rustc-dev-guide/src/hir-debugging.md deleted file mode 100644 index 5a0bda20842..00000000000 --- a/src/doc/rustc-dev-guide/src/hir-debugging.md +++ /dev/null @@ -1,15 +0,0 @@ -# HIR Debugging - -Use the `-Z unpretty=hir` flag to produce a human-readable representation of the HIR. -For cargo projects this can be done with `cargo rustc -- -Z unpretty=hir`. -This output is useful when you need to see at a glance how your code was desugared and transformed -during AST lowering. - -For a full `Debug` dump of the data in the HIR, use the `-Z unpretty=hir-tree` flag. -This may be useful when you need to see the full structure of the HIR from the perspective of the -compiler. - -If you are trying to correlate `NodeId`s or `DefId`s with source code, the -`-Z unpretty=expanded,identified` flag may be useful. - -TODO: anything else? [#1159](https://github.com/rust-lang/rustc-dev-guide/issues/1159) diff --git a/src/doc/rustc-dev-guide/src/hir.md b/src/doc/rustc-dev-guide/src/hir.md index 0c1c9941572..72fb1070157 100644 --- a/src/doc/rustc-dev-guide/src/hir.md +++ b/src/doc/rustc-dev-guide/src/hir.md @@ -5,7 +5,7 @@ The HIR – "High-Level Intermediate Representation" – is the primary IR used in most of rustc. It is a compiler-friendly representation of the abstract syntax tree (AST) that is generated after parsing, macro expansion, and name -resolution (see [Lowering](./ast-lowering.html) for how the HIR is created). +resolution (see [Lowering](./hir/lowering.md) for how the HIR is created). Many parts of HIR resemble Rust surface syntax quite closely, with the exception that some of Rust's expression forms have been desugared away. For example, `for` loops are converted into a `loop` and do not appear in diff --git a/src/doc/rustc-dev-guide/src/hir/ambig-unambig-ty-and-consts.md b/src/doc/rustc-dev-guide/src/hir/ambig-unambig-ty-and-consts.md new file mode 100644 index 00000000000..b5458d71bf8 --- /dev/null +++ b/src/doc/rustc-dev-guide/src/hir/ambig-unambig-ty-and-consts.md @@ -0,0 +1 @@ +# Ambig/Unambig Types and Consts \ No newline at end of file diff --git a/src/doc/rustc-dev-guide/src/hir/debugging.md b/src/doc/rustc-dev-guide/src/hir/debugging.md new file mode 100644 index 00000000000..5a0bda20842 --- /dev/null +++ b/src/doc/rustc-dev-guide/src/hir/debugging.md @@ -0,0 +1,15 @@ +# HIR Debugging + +Use the `-Z unpretty=hir` flag to produce a human-readable representation of the HIR. +For cargo projects this can be done with `cargo rustc -- -Z unpretty=hir`. +This output is useful when you need to see at a glance how your code was desugared and transformed +during AST lowering. + +For a full `Debug` dump of the data in the HIR, use the `-Z unpretty=hir-tree` flag. +This may be useful when you need to see the full structure of the HIR from the perspective of the +compiler. + +If you are trying to correlate `NodeId`s or `DefId`s with source code, the +`-Z unpretty=expanded,identified` flag may be useful. + +TODO: anything else? [#1159](https://github.com/rust-lang/rustc-dev-guide/issues/1159) diff --git a/src/doc/rustc-dev-guide/src/hir/lowering.md b/src/doc/rustc-dev-guide/src/hir/lowering.md new file mode 100644 index 00000000000..02c69b8609f --- /dev/null +++ b/src/doc/rustc-dev-guide/src/hir/lowering.md @@ -0,0 +1,48 @@ +# AST lowering + +The AST lowering step converts AST to [HIR](../hir.md). +This means many structures are removed if they are irrelevant +for type analysis or similar syntax agnostic analyses. Examples +of such structures include but are not limited to + +* Parenthesis + * Removed without replacement, the tree structure makes order explicit +* `for` loops and `while (let)` loops + * Converted to `loop` + `match` and some `let` bindings +* `if let` + * Converted to `match` +* Universal `impl Trait` + * Converted to generic arguments + (but with some flags, to know that the user didn't write them) +* Existential `impl Trait` + * Converted to a virtual `existential type` declaration + +Lowering needs to uphold several invariants in order to not trigger the +sanity checks in `compiler/rustc_passes/src/hir_id_validator.rs`: + +1. A `HirId` must be used if created. So if you use the `lower_node_id`, + you *must* use the resulting `NodeId` or `HirId` (either is fine, since + any `NodeId`s in the `HIR` are checked for existing `HirId`s) +2. Lowering a `HirId` must be done in the scope of the *owning* item. + This means you need to use `with_hir_id_owner` if you are creating parts + of an item other than the one being currently lowered. This happens for + example during the lowering of existential `impl Trait` +3. A `NodeId` that will be placed into a HIR structure must be lowered, + even if its `HirId` is unused. Calling + `let _ = self.lower_node_id(node_id);` is perfectly legitimate. +4. If you are creating new nodes that didn't exist in the `AST`, you *must* + create new ids for them. This is done by calling the `next_id` method, + which produces both a new `NodeId` as well as automatically lowering it + for you so you also get the `HirId`. + +If you are creating new `DefId`s, since each `DefId` needs to have a +corresponding `NodeId`, it is advisable to add these `NodeId`s to the +`AST` so you don't have to generate new ones during lowering. This has +the advantage of creating a way to find the `DefId` of something via its +`NodeId`. If lowering needs this `DefId` in multiple places, you can't +generate a new `NodeId` in all those places because you'd also get a new +`DefId` then. With a `NodeId` from the `AST` this is not an issue. + +Having the `NodeId` also allows the `DefCollector` to generate the `DefId`s +instead of lowering having to do it on the fly. Centralizing the `DefId` +generation in one place makes it easier to refactor and reason about. diff --git a/src/doc/rustc-dev-guide/src/overview.md b/src/doc/rustc-dev-guide/src/overview.md index 92d0c7b0c38..8a1a22fad66 100644 --- a/src/doc/rustc-dev-guide/src/overview.md +++ b/src/doc/rustc-dev-guide/src/overview.md @@ -410,7 +410,7 @@ For more details on bootstrapping, see - Guide: [The HIR](hir.md) - Guide: [Identifiers in the HIR](hir.md#identifiers-in-the-hir) - Guide: [The `HIR` Map](hir.md#the-hir-map) - - Guide: [Lowering `AST` to `HIR`](ast-lowering.md) + - Guide: [Lowering `AST` to `HIR`](./hir/lowering.md) - How to view `HIR` representation for your code `cargo rustc -- -Z unpretty=hir-tree` - Rustc `HIR` definition: [`rustc_hir`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/index.html) - Main entry point: **TODO** -- cgit 1.4.1-3-g733a5