, span: Span },
}
```
- The list of operands to the `asm!` (`in`, `[late]out`, `in[late]out`, `sym`, `const`).
These are represented differently at each stage of lowering,
but follow a common pattern:
- `in`, `out`, and `inout` all have an associated register class (`reg`)
or explicit register (`"eax"`).
- `inout` has 2 forms:
one with a single expression that is both read from and written to,
and one with two separate expressions for the input and output parts.
- `out` and `inout` have a `late` flag (`lateout` / `inlateout`) to indicate that the register
allocator is allowed to reuse an input register for this output.
- `out` and the split variant of `inout` allow `_` to be specified for an output,
which means that the output is discarded.
This is used to allocate scratch registers for assembly code.
- `const` refers to an anonymous constants,
and generally works like an inline const.
- `sym` is a bit special since it only accepts a path expression,
which must point to a `static` or a `fn`.
- The options set at the end of the `asm!` macro.
The only ones that are of particular interest to
rustc are `NORETURN` which makes `asm!` return `!` instead of `()`,
and `RAW` which disables format string parsing.
The remaining options are mostly passed through to LLVM with little processing.
```rust
bitflags::bitflags! {
pub struct InlineAsmOptions: u16 {
const PURE = 1 << 0;
const NOMEM = 1 << 1;
const READONLY = 1 << 2;
const PRESERVES_FLAGS = 1 << 3;
const NORETURN = 1 << 4;
const NOSTACK = 1 << 5;
const ATT_SYNTAX = 1 << 6;
const RAW = 1 << 7;
const MAY_UNWIND = 1 << 8;
}
}
```
## AST
`InlineAsm` is represented as an expression in the AST with the [`ast::InlineAsm` type][inline_asm_ast].
The `asm!` macro is implemented in `rustc_builtin_macros` and outputs an `InlineAsm` AST node.
The template string is parsed using `fmt_macros`,
positional and named operands are resolved to explicit operand indices.
Since target information is not available to macro invocations,
validation of the registers and register classes is deferred to AST lowering.
[inline_asm_ast]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/ast/struct.InlineAsm.html
## HIR
`InlineAsm` is represented as an expression in the HIR with the [`hir::InlineAsm` type][inline_asm_hir].
AST lowering is where `InlineAsmRegOrRegClass` is converted from `Symbol`s to an actual register or
register class.
If any modifiers are specified for a template string placeholder, these are
validated against the set allowed for that operand type.
Finally, explicit registers for inputs and
outputs are checked for conflicts (same register used for different operands).
[inline_asm_hir]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/hir/struct.InlineAsm.html
## Type checking
Each register class has an allowlist of types that it may be used with.
After the types of all operands have been determined,
the `intrinsicck` pass will check that these types are in the allowlist.
It also checks that split `inout` operands have compatible types and that `const`
operands are integers or floats.
Suggestions are emitted where needed if a template modifier should
be used for an operand based on the type that was passed into it.
## THIR
`InlineAsm` is represented as an expression in the THIR with the [`InlineAsmExpr` type][inline_asm_thir].
The only significant change compared to HIR is that `Sym` has been lowered to either a `SymFn`
whose `expr` is a `Literal` ZST of the `fn`,
or a `SymStatic` which points to the `DefId` of a `static`.
[inline_asm_thir]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/thir/struct.InlineAsmExpr.html
## MIR
`InlineAsm` is represented as a `Terminator` in the MIR with the [`TerminatorKind::InlineAsm` variant][inline_asm_mir]
As part of THIR lowering, `InOut` and `SplitInOut` operands are lowered to a split form with a
separate `in_value` and `out_place`.
Semantically, the `InlineAsm` terminator is similar to the `Call` terminator except that it has
multiple output places where a `Call` only has a single return place output.
[inline_asm_mir]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/enum.TerminatorKind.html#variant.InlineAsm
## Codegen
Operands are lowered one more time before being passed to LLVM codegen.
This is represented by the [`InlineAsmOperandRef` type][inline_asm_codegen] from `rustc_codegen_ssa`.
The operands are lowered to LLVM operands and constraint codes as follows:
- `out` and the output part of `inout` operands are added first, as required by LLVM.
Late output operands have a `=` prefix added to their constraint code,
and non-late output operands have a `=&` prefix added to their constraint code.
- `in` operands are added normally.
- `inout` operands are tied to the matching output operand.
- `sym` operands are passed as function pointers or pointers,
using the `"s"` constraint.
- `const` operands are formatted to a string and directly inserted in the template string.
The template string is converted to LLVM form:
- `$` characters are escaped as `$$`.
- `const` operands are converted to strings and inserted directly.
- Placeholders are formatted as `${X:M}`,
where `X` is the operand index and `M` is the modifier character.
Modifiers are converted from the Rust form to the LLVM form.
The various options are converted to clobber constraints or LLVM attributes;
refer to the [RFC] for more details.
Note that LLVM is sometimes rather picky about what types it accepts for certain constraint codes
so we sometimes need to insert conversions to/from a supported type.
See the target-specific ISelLowering.cpp files in LLVM
for details of what types are supported for each register class.
[inline_asm_codegen]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/traits/enum.InlineAsmOperandRef.html
[RFC]: https://github.com/Amanieu/rfcs/blob/inline-asm/text/0000-inline-asm.md#mapping-to-llvm-ir
## Adding support for new architectures
Adding inline assembly support to an architecture is mostly a matter of defining the registers and
register classes for that architecture.
All the definitions for register classes are located in
`compiler/rustc_target/asm/`.
Additionally you will need to implement lowering of these register classes to LLVM constraint codes
in `compiler/rustc_codegen_llvm/asm.rs`.
When adding a new architecture, make sure to cross-reference with the LLVM source code:
- LLVM has restrictions on which types can be used with a particular constraint code.
Refer to the `getRegForInlineAsmConstraint` function
in `lib/Target/${ARCH}/${ARCH}ISelLowering.cpp`.
- LLVM reserves certain registers for its internal use,
which causes them to not be saved/restored properly around inline assembly blocks.
These registers are listed in the `getReservedRegs`
function in `lib/Target/${ARCH}/${ARCH}RegisterInfo.cpp`.
Any "conditionally" reserved register,
such as the frame/base pointer,
must always be treated as reserved for Rust purposes because we
can't know ahead of time whether a function will require a frame/base pointer.
## Tests
Various tests for inline assembly are available:
- `tests/assembly-llvm/asm`
- `tests/ui/asm`
- `tests/codegen-llvm/asm-*`
Every architecture supported by inline assembly must have exhaustive tests in
`tests/assembly-llvm/asm` which test all combinations of register classes and types.
---
### Src Doc Rustc Dev Guide Src Ast Validation (`src/doc/rustc-dev-guide/src/ast-validation.md`)
# AST validation
_AST validation_ is a separate AST pass that visits each
item in the tree and performs simple checks.
This pass doesn't perform any complex analysis, type checking or
name resolution.
Before performing any validation, the compiler first expands the macros.
Then this pass performs validations to check that each AST item is in the correct state.
And when this pass is done, the compiler runs the crate resolution pass.
## Validations
Validations are defined in `AstValidator` type, which
itself is located in `rustc_ast_passes` crate.
This type implements various simple checks which emit errors
when certain language rules are broken.
In addition, `AstValidator` implements `Visitor` trait
that defines how to visit AST items (which can be functions,
traits, enums, etc).
For each item, visitor performs specific checks.
For example, when visiting a function declaration,
`AstValidator` checks that the function has:
* no more than `u16::MAX` parameters;
* c-variadic argument goes the last in the declaration;
* documentation comments aren't applied to function parameters;
* and other validations.
---
### Src Doc Rustc Dev Guide Src Attributes (`src/doc/rustc-dev-guide/src/attributes.md`)
# Attributes
Attributes come in two types: *inert* (or *built-in*) and *active* (*non-builtin*).
## Builtin/inert attributes
These attributes are defined in the compiler itself, in
[`compiler/rustc_feature/src/builtin_attrs.rs`][builtin_attrs] and in the [attribute parsers][attr_parsing].
Examples include `#[allow]` and `#[macro_use]`.
[builtin_attrs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_feature/builtin_attrs/index.html
[attr_parsing]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_attr_parsing/index.html
These attributes have several important characteristics:
* They are always in scope, and do not participate in typical path-based resolution.
* They cannot be renamed.
For example, `use allow as foo` will compile, but writing `#[foo]` will produce an error.
* They are 'inert', meaning they are left as-is by the macro expansion code.
As a result, any behavior comes as a result of the compiler explicitly checking for their presence.
For example, lint-related code explicitly checks for `#[allow]`, `#[warn]`, `#[deny]`, and
`#[forbid]`, rather than the behavior coming from the expansion of the attributes themselves.
For more information on these attributes, see the chapter about [attribute parsing][attr-parsing-chapter].
[attr-parsing-chapter]: ./hir/attribute-parsing.md
### Note on adding new builtin attributes
**Warning: Name resolution ambiguity potential when adding new builtin attributes**
Please note that adding **new builtin attributes** (whose name is not reserved, i.e. a new builtin
attribute whose name does not start with `rustc`), even if *unstable*-gated, can introduce breakage
from name resolution ambiguity in stable code if (1) the stable code has a macro of the same name
which gets re-exported, or (2) or a proc-macro derive helper attribute of the same name.
Typically, the builtin attributes probably has to start out as `#[rustc_foo]` instead of `#[foo]` to
avoid colliding with user-defined macros and proc-macro helper attributes.
Then, prior to stabilization,
a rename to `#[foo]` should be done separately with a crater run to assess fallout,
with a deliberate breakage FCP proposal for T-lang to consider.
Remember also that crater is *not* exhaustive and does not contain all existing stable code.
See:
- [Built-in attributes are treated differently vs prelude attributes, unstable built-in attributes
can name-collide with stable macro, and built-in attributes can break back-compat
#134963](https://github.com/rust-lang/rust/issues/134963) and backlinks within this issue,
including design discussions on how to fix this kind of breakage hazard.
- [Broken build after updating: coverage is ambiguous; ambiguous because of a name conflict with a
builtin attribute #121157](https://github.com/rust-lang/rust/issues/121157).
- [Regression: align is ambiguous #143834](https://github.com/rust-lang/rust/issues/143834).
## 'Non-builtin'/'active' attributes
These attributes are defined by a crate - either the standard library, or a proc-macro crate.
**Important**: Many non-builtin attributes, such as `#[derive]`, are still considered part of the
core Rust language.
However, they are **not** called 'builtin attributes', since they have a
corresponding definition in the standard library.
Definitions of non-builtin attributes take two forms:
1. Proc-macro attributes, defined via a function annotated with `#[proc_macro_attribute]` in a
proc-macro crate.
2. AST-based attributes, defined in the standard library.
These attributes have special 'stub'
macros defined in places like [`library/core/src/macros/mod.rs`][core_macros].
[core_macros]: https://github.com/rust-lang/rust/blob/HEAD/library/core/src/macros/mod.rs
These definitions exist to allow the macros to participate in typical path-based resolution - they
can be imported, re-exported, and renamed just like any other item definition.
However, the body of the definition is empty.
Instead, the macro is annotated with the `#[rustc_builtin_macro]`
attribute, which tells the compiler to run a corresponding function in `rustc_builtin_macros`.
All non-builtin attributes have the following characteristics:
* Like all other definitions (e.g. structs), they must be brought into scope via an import.
Many standard library attributes are included in the prelude - this is why writing `#[derive]`
works without an import.
* They participate in macro expansion.
The implementation of the macro may leave the attribute
target unchanged, modify the target, produce new AST nodes, or remove the target entirely.
---
### Src Doc Rustc Dev Guide Src Borrow Check (`src/doc/rustc-dev-guide/src/borrow-check.md`)
# MIR borrow check
The borrow check is Rust's "secret sauce" – it is tasked with enforcing a number of properties:
- That all variables are initialized before they are used.
- That you can't move the same value twice.
- That you can't move a value while it is borrowed.
- That you can't access a place while it is mutably borrowed (except through the reference).
- That you can't mutate a place while it is immutably borrowed.
- etc
The borrow checker operates on the MIR.
An older implementation operated on the HIR.
Doing borrow checking on MIR has several advantages:
- The MIR is *far* less complex than the HIR; the radical desugaring
helps prevent bugs in the borrow checker.
(If you're curious, you can see
[a list of bugs that the MIR-based borrow checker fixes here][47366].)
- Even more importantly, using the MIR enables ["non-lexical lifetimes"][nll],
which are regions derived from the control-flow graph.
[47366]: https://github.com/rust-lang/rust/issues/47366
[nll]: https://rust-lang.github.io/rfcs/2094-nll.html
## Major phases of the borrow checker
The borrow checker source is found in [the `rustc_borrowck` crate][b_c].
The main entry point is the [`mir_borrowck`] query.
[b_c]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_borrowck/index.html
[`mir_borrowck`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_borrowck/fn.mir_borrowck.html
- We first create a **local copy** of the MIR.
In the coming steps,
we will modify this copy in place to modify the types and things to
include references to the new regions that we are computing.
- We then invoke [`replace_regions_in_mir`] to modify our local MIR.
Among other things, this function will replace all of the [regions](./appendix/glossary.md#region)
in the MIR with fresh [inference variables](./appendix/glossary.md#inf-var).
- Next, we perform a number of [dataflow analyses](./appendix/background.md#dataflow) that
compute what data is moved and when.
- We then do a [second type check](borrow-check/type-check.md) across the MIR:
the purpose of this type check is to determine all of the constraints between different regions.
- Next, we do [region inference](borrow-check/region-inference.md), which computes
the values of each region — basically, the points in the control-flow graph where
each lifetime must be valid according to the constraints we collected.
- At this point, we can compute the "borrows in scope" at each point.
- Finally, we do a second walk over the MIR, looking at the actions it does and reporting errors.
For example, if we see a statement like `*a + 1`,
we would check that the variable `a` is initialized and that it is not mutably borrowed,
as either of those would require an error to be reported.
Doing this check requires the results of all the previous analyses.
[`replace_regions_in_mir`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_borrowck/nll/fn.replace_regions_in_mir.html
## Debugging the borrow checker
See [Debugging the borrow checker](borrow-check/debugging.md) and [MIR Debugging](mir/debugging.md).
---
### Src Doc Rustc Dev Guide Src Bug Fix Procedure (`src/doc/rustc-dev-guide/src/bug-fix-procedure.md`)
# Procedures for breaking changes
This page defines the best practices procedure for making bug fixes or soundness
corrections in the compiler that can cause existing code to stop compiling.
This text is based on [RFC 1589].
# Motivation
[motivation]: #motivation
From time to time, we encounter the need to make a bug fix, soundness
correction, or other change in the compiler which will cause existing code to stop compiling.
When this happens, it is important that we handle the change in
a way that gives users of Rust a smooth transition.
What we want to avoid is that existing programs suddenly stop compiling with opaque error messages:
we would prefer to have a gradual period of warnings, with clear guidance as to
what the problem is, how to fix it, and why the change was made.
This RFC describes the procedure that we have been developing for handling breaking
changes that aims to achieve that kind of smooth transition.
One of the key points of this policy is that (a) warnings should be issued
initially rather than hard errors if at all possible and (b) every change that
causes existing code to stop compiling will have an associated tracking issue.
This issue provides a point to collect feedback on the results of that change.
Sometimes changes have unexpectedly large consequences or there may be a way to
avoid the change that was not considered.
In those cases,
we may decide to change course and roll back the change,
or find another solution (and if warnings are being used, this is particularly easy to do).
### What qualifies as a bug fix?
Note that this RFC does not try to define when a breaking change is permitted.
That is already covered under [RFC 1122].
This document assumes that the change being made is in accordance with those policies.
Here is a summary of the conditions from RFC 1122:
- **Soundness changes:** Fixes to holes uncovered in the type system.
- **Compiler bugs:** Places where the compiler is not implementing the specified
semantics found in an RFC or lang-team decision.
- **Underspecified language semantics:** Clarifications to grey areas where the
compiler behaves inconsistently and no formal behavior had been previously decided.
Please see [the RFC][rfc 1122] for full details!
# Detailed design
[design]: #detailed-design
The procedure for making a breaking change is as follows (each of these steps is
described in more detail below):
1. Do a **crater run** to assess the impact of the change.
2. Make a **special tracking issue** dedicated to the change.
3. Do not report an error right away.
Instead, **issue forwards-compatibility lint warnings**.
- Sometimes this is not straightforward.
See the text below for suggestions on different techniques we have employed in the past.
- For cases where warnings are infeasible:
- Report errors, but make every effort to give a targeted error message
that directs users to the tracking issue
- Submit PRs to all known affected crates that fix the issue
- or, at minimum, alert the owners of those crates to the problem and
direct them to the tracking issue
4. Once the change has been in the wild for at least one cycle, we can
**stabilize the change**, converting those warnings into errors.
Finally, for changes to `rustc_ast` that will affect plugins, the general policy
is to batch these changes.
That is discussed below in more detail.
### Tracking issue
Every breaking change should be accompanied by a **dedicated tracking issue** for that change.
The main text of this issue should describe the change being
made, with a focus on what users must do to fix their code.
The issue should be approachable and practical; it may make sense to direct users to an RFC or some
other issue for the full details.
The issue also serves as a place where users can comment with questions or other concerns.
A template for these breaking-change tracking issues can be found [here][template].
An example of how such an issue should look can be [found here][breaking-change-issue].
[template]: https://github.com/rust-lang/rust/issues/new?template=tracking_issue_future.md
### Issuing future compatibility warnings
The best way to handle a breaking change is to begin by issuing future-compatibility warnings.
These are a special category of lint warning.
Adding a new future-compatibility warning can be done as follows.
```rust
// 1. Define the lint in `compiler/rustc_lint/src/builtin.rs` and
// add the metadata for the future incompatibility:
declare_lint! {
pub YOUR_LINT_HERE,
Warn,
"illegal use of foo bar baz"
@future_incompatible = FutureIncompatibleInfo {
reason: fcw!(FutureReleaseError #1234) // your tracking issue here!
},
}
// 2. Add a dedicated lint pass for it.
// This step can be skipped if you emit the lint as part of an existing pass.
#[derive(Default)]
pub struct MyLintPass {
...
}
impl {Early,Late}LintPass for MyLintPass {
...
}
impl_lint_pass!(MyLintPass => [YOUR_LINT_HERE]);
// 3. emit the lint somewhere in your lint pass:
cx.emit_span_lint(
YOUR_LINT_HERE,
pat.span,
// some diagnostic struct
MyDiagnostic {
...
},
);
```
Finally, register the lint in `compiler/rustc_lint/src/lib.rs`.
There are many examples in that file that already show how to do so.
#### Helpful techniques
It can often be challenging to filter out new warnings from older, pre-existing errors.
One technique that has been used in the past is to run the older code
unchanged and collect the errors it would have reported.
You can then issue warnings for any errors you would give which do not appear in that original set.
Another option is to abort compilation after the original code completes if
errors are reported: then you know that your new code will only execute when
there were no errors before.
#### Crater and crates.io
[Crater] is a bot that will compile all crates.io crates and many
public github repos with the compiler with your changes.
A report will then be generated with crates that ceased to compile with,
or began to compile with your changes.
Crater runs can take a few days to complete.
[Crater]: ./tests/crater.md
We should always do a crater run to assess impact.
It is polite and considerate to notify the authors of crates affected by the breaking change.
It is even better to submit PRs fixing the breakage.
#### Is it ever acceptable to go directly to issuing errors?
Changes that are believed to have negligible impact can go directly to issuing an error.
One rule of thumb would be to check against `crates.io`: if fewer than
10 **total** affected projects are found (**not** root errors), we can move straight to an error.
In such cases, we should still make the "breaking change"
page as before, and we should ensure that the error directs users to this page.
In other words, everything should be the same except that users are getting an
error, and not a warning.
Moreover, we should submit PRs to the affected projects
(ideally before the PR implementing the change lands in rustc).
If the impact is not believed to be negligible (e.g., more than 10 crates are
affected), then warnings are required (unless the compiler team agrees to grant
a special exemption in some particular case).
If implementing warnings is not feasible,
then we should make an aggressive strategy of migrating crates before
we land the change so as to lower the number of affected crates.
Here are some techniques for approaching this scenario:
1. Issue warnings for subparts of the problem, and reserve the new errors for
the smallest set of cases you can.
2. Try to give a very precise error message that suggests how to fix the problem
and directs users to the tracking issue.
3. It may also make sense to layer the fix:
- First, add warnings where possible and let those land before proceeding to issue errors.
- Work with authors of affected crates to ensure that corrected versions are
available _before_ the fix lands, so that downstream users can use them.
### Stabilization
After a change is made, we will **stabilize** the change using the same process
that we use for unstable features:
- After a new release is made, we will go through the outstanding tracking
issues corresponding to breaking changes and nominate some of them for **final
comment period** (FCP).
- The FCP for such issues lasts for one cycle.
In the final week or two of the cycle, we will review comments and make a final determination:
- Convert to error: the change should be made into a hard error.
- Revert: we should remove the warning and continue to allow the older code to compile.
- Defer: can't decide yet, wait longer, or try other strategies.
Ideally, breaking changes should have landed on the **stable branch** of the
compiler before they are finalized.
### Removing a lint
Once we have decided to make a "future warning" into a hard error, we need a PR
that removes the custom lint.
As an example, here are the steps required to
remove the `overlapping_inherent_impls` compatibility lint.
First, convert the name of the lint to uppercase (`OVERLAPPING_INHERENT_IMPLS`);
search the source for that string.
We will basically by converting each place where this
lint name is mentioned (in the compiler, we use the upper-case name, and a macro
automatically generates the lower-case string; so searching for
`overlapping_inherent_impls` would not find much).
> NOTE: these exact files don't exist anymore, but the procedure is still the same.
#### Remove the lint.
The first reference you will likely find is the lint definition [in
`rustc_session/src/lint/builtin.rs` that resembles this][defsource]:
[defsource]: https://github.com/rust-lang/rust/blob/085d71c3efe453863739c1fb68fd9bd1beff214f/src/librustc/lint/builtin.rs#L171-L175
```rust
declare_lint! {
pub OVERLAPPING_INHERENT_IMPLS,
Deny, // this may also say Warning
"two overlapping inherent impls define an item with the same name were erroneously allowed",
@future_incompatible = FutureIncompatibleInfo {
reason: fcw!(FutureReleaseError #1234), // your tracking issue here!
},
}
```
This `declare_lint!` macro creates the relevant data structures.
Remove it.
You will also find that there is a mention of `OVERLAPPING_INHERENT_IMPLS` later in
the file as [part of a `lint_array!`][lintarraysource]; remove it too.
[lintarraysource]: https://github.com/rust-lang/rust/blob/085d71c3efe453863739c1fb68fd9bd1beff214f/src/librustc/lint/builtin.rs#L252-L290
#### Add the lint to the list of removed lints.
In `compiler/rustc_lint/src/lib.rs` there is a list of "renamed and removed lints".
You can add this lint to the list:
```rust
store.register_removed("overlapping_inherent_impls", "converted into hard error, see #36889");
```
where `#36889` is the tracking issue for your lint.
#### Update the places that issue the lint
Finally, the last class of references you will see are the places that actually
**trigger** the lint itself (i.e., what causes the warnings to appear). These
you do not want to delete.
Instead, you want to convert them into errors.
In this case, the [`add_lint` call][addlintsource] looks like this:
```rust
self.tcx.sess.add_lint(lint::builtin::OVERLAPPING_INHERENT_IMPLS,
node_id,
self.tcx.span_of_impl(item1).unwrap(),
msg);
```
You'll also often find `node_span_lint` used for this.
We want to convert this into an error.
In some cases, there may be an existing error for this scenario.
In others, we will need to allocate a fresh diagnostic code.
[Instructions for allocating a fresh diagnostic
code can be found here.](./diagnostics/error-codes.md) You may want
to mention in the extended description that the compiler behavior
changed on this point, and include a reference to the tracking issue for the change.
Let's say that we've adopted `E0592` as our code.
Then we can change the `add_lint()` call above to something like:
```rust
struct_span_code_err!(self.dcx(), self.tcx.span_of_impl(item1).unwrap(), E0592, msg)
.emit();
```
Or better: a structured diagnostic like this:
```rust
#[derive(Diagnostic)]
struct MyDiagnostic {
#[label]
span: Span,
...
}
```
#### Update tests
Finally, run the test suite.
These should be some tests that used to reference
the `overlapping_inherent_impls` lint; those will need to be updated.
In general, if the test used to have `#[deny(overlapping_inherent_impls)]`, that
can just be removed.
```
./x test
```
#### All done!
Open a PR.
[addlintsource]: https://github.com/rust-lang/rust/blob/085d71c3efe453863739c1fb68fd9bd1beff214f/src/librustc_typeck/coherence/inherent.rs#L300-L303
[futuresource]: https://github.com/rust-lang/rust/blob/085d71c3efe453863739c1fb68fd9bd1beff214f/src/librustc_lint/lib.rs#L202-L205
[rfc 1122]: https://github.com/rust-lang/rfcs/blob/master/text/1122-language-semver.md
[breaking-change-issue]: https://gist.github.com/nikomatsakis/631ec8b4af9a18b5d062d9d9b7d3d967
[RFC 1589]: https://github.com/rust-lang/rfcs/blob/master/text/1589-rustc-bug-fix-procedure.md
---
### Src Doc Rustc Dev Guide Src Cli (`src/doc/rustc-dev-guide/src/cli.md`)
# Command-line Arguments
Command-line flags are documented in the [rustc book][cli-docs].
All *stable* flags should be documented there.
Unstable flags should be documented in the [unstable book].
See the [forge guide for new options] for details on the *procedure* for
adding a new command-line argument.
## Guidelines
- Flags should be orthogonal to each other.
For example, if we'd have a json-emitting variant of multiple actions `foo` and `bar`,
an additional `--json` flag is better than adding `--foo-json` and `--bar-json`.
- Avoid flags with the `no-` prefix.
Instead, use the [`parse_bool`] function,
such as `-C embed-bitcode=no`.
- Consider the behavior if the flag is passed multiple times.
In some situations, the values should be accumulated (in order!).
In other situations, subsequent flags should override previous flags (for example,
the lint-level flags).
And some flags (like `-o`) should generate an error
if it is too ambiguous what multiple flags would mean.
- Always give options a long descriptive name, if only for more understandable compiler scripts.
- The `--verbose` flag is for adding verbose information to `rustc` output.
For example,
using it with the `--version` flag gives information about the hashes of the compiler code.
- Experimental flags and options must be guarded behind the `-Z unstable-options` flag.
[cli-docs]: https://doc.rust-lang.org/rustc/command-line-arguments.html
[forge guide for new options]: https://forge.rust-lang.org/compiler/proposals-and-stabilization.html#compiler-flags
[unstable book]: https://doc.rust-lang.org/nightly/unstable-book/
[`parse_bool`]: https://github.com/rust-lang/rust/blob/e5335592e78354e33d798d20c04bcd677c1df62d/src/librustc_session/options.rs#L307-L313
---
### Src Doc Rustc Dev Guide Src Closure (`src/doc/rustc-dev-guide/src/closure.md`)
# Closure Capture Inference
This section describes how rustc handles closures.
Closures in Rust are effectively "desugared" into structs that contain the values they use (or
references to the values they use) from their creator's stack frame.
rustc has the job of figuring out which values a closure uses and how, so it can decide
whether to capture a given variable by shared reference, mutable reference, or by move.
rustc also has to figure out which of the closure traits ([`Fn`][fn],
[`FnMut`][fn_mut], or [`FnOnce`][fn_once]) a closure is capable of implementing.
[fn]: https://doc.rust-lang.org/std/ops/trait.Fn.html
[fn_mut]:https://doc.rust-lang.org/std/ops/trait.FnMut.html
[fn_once]: https://doc.rust-lang.org/std/ops/trait.FnOnce.html
Let's start with a few examples:
### Example 1
To start, let's take a look at how the closure in the following example is desugared:
```rust
fn closure(f: impl Fn()) {
f();
}
fn main() {
let x: i32 = 10;
closure(|| println!("Hi {}", x)); // The closure just reads x.
println!("Value of x after return {}", x);
}
```
Let's say the above is the content of a file called `immut.rs`.
If we compile `immut.rs` using the following command,
the [`-Z dump-mir=all`][dump-mir] flag will cause
`rustc` to generate and dump the [MIR] to a directory called `mir_dump`.
```console
> rustc +stage1 immut.rs -Z dump-mir=all
```
[mir]: ./mir/index.md
[dump-mir]: ./mir/passes.md
After we run this command, we will see a newly generated directory in our
current working directory called `mir_dump`, which will contain several files.
If we look at file `rustc.main.-------.mir_map.0.mir`, we will find, among other things,
it also contains this line:
```rust,ignore
_4 = &_1;
_3 = [closure@immut.rs:7:13: 7:36] { x: move _4 };
```
Note that in the MIR examples in this chapter, `_1` is `x`.
Here in first line `_4 = &_1;`,
the `mir_dump` tells us that `x` was borrowed as an immutable reference.
This is what we would hope as our closure just reads `x`.
### Example 2
Here is another example:
```rust
fn closure(mut f: impl FnMut()) {
f();
}
fn main() {
let mut x: i32 = 10;
closure(|| {
x += 10; // The closure mutates the value of x
println!("Hi {}", x)
});
println!("Value of x after return {}", x);
}
```
```rust,ignore
_4 = &mut _1;
_3 = [closure@mut.rs:7:13: 10:6] { x: move _4 };
```
This time along, in the line `_4 = &mut _1;`, we see that the borrow is changed to mutable borrow.
Fair enough!
The closure increments `x` by 10.
### Example 3
One more example:
```rust
fn closure(f: impl FnOnce()) {
f();
}
fn main() {
let x = vec![21];
closure(|| {
drop(x); // Makes x unusable after the fact.
});
// println!("Value of x after return {:?}", x);
}
```
```rust,ignore
_6 = [closure@move.rs:7:13: 9:6] { x: move _1 }; // bb16[3]: scope 1 at move.rs:7:13: 9:6
```
Here, `x` is directly moved into the closure,
and the access to it will not be permitted after the closure.
## Inferences in the compiler
Now let's dive into rustc code and see how all these inferences are done by the compiler.
Let's start with defining a term that we will be using quite a bit in the rest of the discussion -
*upvar*.
An **upvar** is a variable that is local to the function where the closure is defined.
So, in the above examples, **x** will be an upvar to the closure.
They are also sometimes referred to as the *free variables*,
meaning they are not bound to the context of the closure.
[`compiler/rustc_passes/src/upvars.rs`][upvars] defines a query called *upvars_mentioned*
for this purpose.
[upvars]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_passes/upvars/index.html
Other than lazy invocation,
one other thing that distinguishes a closure from a normal function is that it can use the upvars.
It borrows these upvars from its surrounding
context; therefore the compiler has to determine the upvar's borrow type.
The compiler starts with assigning an immutable borrow type and lowers the restriction
(that is, changes it from **immutable** to **mutable** to **move**) as needed, based on the usage.
In the Example 1 above,
the closure only uses the variable for printing but does not modify it in any way and therefore,
in the `mir_dump`, we find the borrow type for the upvar `x` to be immutable.
In example 2, however, the closure modifies `x` and increments it by some value.
Because of this mutation, the compiler, which
started off assigning `x` as an immutable reference type, has to adjust it as a mutable reference.
Likewise in the third example, the closure drops the vector and therefore this requires the variable
`x` to be moved into the closure.
Depending on the borrow kind, the closure has to implement the
appropriate trait: `Fn` trait for immutable borrow, `FnMut` for mutable borrow,
and `FnOnce` for move semantics.
Most of the code related to the closure is in the
[`compiler/rustc_hir_typeck/src/upvar.rs`][upvar] file and the data structures are
declared in the file [`compiler/rustc_middle/src/ty/mod.rs`][ty].
[upvar]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/upvar/index.html
[ty]:https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/index.html
Before we go any further,
let's discuss how we can examine the flow of control through the rustc codebase.
For closures specifically,
set the `RUSTC_LOG` env variable as below and collect the output in a file:
```console
> RUSTC_LOG=rustc_hir_typeck::upvar rustc +stage1 -Z dump-mir=all \
<.rs file to compile> 2>
```
This uses the stage1 compiler and enables `debug!` logging for the `rustc_hir_typeck::upvar` module.
The other option is to step through the code using lldb or gdb.
1. `rust-lldb build/host/stage1/bin/rustc test.rs`
2. In lldb:
1. `b upvar.rs:134` // Setting the breakpoint on a certain line in the upvar.rs file
2. `r` // Run the program until it hits the breakpoint
Let's start with [`upvar.rs`][upvar].
This file has something called the [`euv::ExprUseVisitor`] which walks the source of the closure and
invokes a callback for each upvar that is borrowed, mutated, or moved.
[`euv::ExprUseVisitor`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/expr_use_visitor/struct.ExprUseVisitor.html
```rust
fn main() {
let mut x = vec![21];
let _cl = || {
let y = x[0]; // 1.
x[0] += 1; // 2.
};
}
```
In the above example, our visitor will be called twice, for the lines marked 1 and 2,
once for a shared borrow and another one for a mutable borrow.
It will also tell us what was borrowed.
The callbacks are defined by implementing the [`Delegate`] trait.
The [`InferBorrowKind`][ibk] type implements `Delegate` and keeps a map that
records for each upvar which mode of capture was required.
The modes of capture can be `ByValue` (moved) or `ByRef` (borrowed).
For `ByRef` borrows, the possible [`BorrowKind`]s are `ImmBorrow`,
`UniqueImmBorrow`, `MutBorrow` as defined in the
[`compiler/rustc_middle/src/ty/mod.rs`][middle_ty].
[`BorrowKind`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/enum.BorrowKind.html
[middle_ty]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/index.html
`Delegate` defines a few different methods (the different callbacks):
**consume** for *move* of a variable, **borrow** for a *borrow* of some kind (shared or mutable),
and **mutate** when we see an *assignment* of something.
All of these callbacks have a common argument *cmt* which stands for Category,
Mutability and Type and is defined in [`compiler/rustc_hir_typeck/src/expr_use_visitor.rs`][cmt].
Borrowing from the code comments, "`cmt` is a complete categorization of a value indicating where it
originated and how it is located, as well as the mutability of the memory in
which the value is stored". Based on the callback (consume, borrow etc.), we
will call the relevant `adjust_upvar_borrow_kind_for_` and pass the `cmt` along.
Once the borrow type is adjusted, we store it in the table,
which basically says what borrows were made for each closure.
```rust,ignore
self.tables
.borrow_mut()
.upvar_capture_map
.extend(delegate.adjust_upvar_captures);
```
[`Delegate`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/expr_use_visitor/trait.Delegate.html
[ibk]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/upvar/struct.InferBorrowKind.html
[cmt]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/expr_use_visitor/index.html
---
### Src Doc Rustc Dev Guide Src Coherence (`src/doc/rustc-dev-guide/src/coherence.md`)
# Coherence
> NOTE: this is based on [notes by @lcnr](https://github.com/rust-lang/rust/pull/121848)
Coherence checking is what detects both of trait impls and inherent impls overlapping with others.
(reminder: [inherent impls](https://doc.rust-lang.org/reference/items/implementations.html#inherent-implementations) are impls of concrete types like `impl MyStruct {}`)
Overlapping trait impls always produce an error,
while overlapping inherent impls result in an error only if they have methods with the same name.
Checking for overlaps is split in two parts.
First there's the [overlap check(s)](#overlap-checks),
which finds overlaps between traits and inherent implementations that the compiler currently knows about.
However, Coherence also results in an error if any other impls **could** exist,
even if they are currently unknown.
This affects impls which may get added to upstream crates in a backwards compatible way,
and impls from downstream crates.
This is called the Orphan check.
## Overlap checks
Overlap checks are performed for both inherent impls, and for trait impls.
This uses the same overlap checking code, really done as two separate analyses.
Overlap checks always consider pairs of implementations, comparing them to each other.
Overlap checking for inherent impl blocks is done through `fn check_item` (in coherence/inherent_impls_overlap.rs),
where you can very clearly see that (at least for small `n`), the check really performs `n^2`
comparisons between impls.
In the case of traits, this check is currently done as part of building the [specialization graph](traits/specialization.md),
to handle specializing impls overlapping with their parent, but this may change in the future.
In both cases, all pairs of impls are checked for overlap.
Overlapping is sometimes partially allowed:
1. for marker traits
2. under [specialization](traits/specialization.md)
It normally isn't.
The overlap check has various modes (see [`OverlapMode`]).
Importantly, there's the explicit negative impl check, and the implicit negative impl check.
Both try to prove that an overlap is definitely impossible.
[`OverlapMode`]: https://doc.rust-lang.org/beta/nightly-rustc/rustc_middle/traits/specialization_graph/enum.OverlapMode.html
### The explicit negative impl check
This check is done in [`impl_intersection_has_negative_obligation`].
This check tries to find a negative trait implementation.
For example:
```rust
struct MyCustomErrorType;
// both in your own crate
impl From<&str> for MyCustomErrorType {}
impl From for MyCustomErrorType where E: Error {}
```
In this example, we'd get:
`MyCustomErrorType: From<&str>` and `MyCustomErrorType: From`, giving `?E = &str`.
And thus, these two implementations would overlap.
However, libstd provides `&str: !Error`, and therefore guarantees that there
will never be a positive implementation of `&str: Error`, and thus there is no overlap.
Note that for this kind of negative impl check, we must have explicit negative implementations provided.
This is not currently stable.
[`impl_intersection_has_negative_obligation`]: https://doc.rust-lang.org/beta/nightly-rustc/rustc_trait_selection/traits/coherence/fn.impl_intersection_has_negative_obligation.html
### The implicit negative impl check
This check is done in [`impl_intersection_has_impossible_obligation`],
and does not rely on negative trait implementations and is stable.
Let's say there's a
```rust
impl From for Box {} // in your own crate
impl From for Box where E: Error {} // in std
```
This would give: `Box: From`, and `Box: From`,
giving `?E = MyLocalType`.
In your crate there's no `MyLocalType: Error`, downstream crates cannot implement `Error` (a remote trait) for `MyLocalType` (a remote type).
Therefore, these two impls do not overlap.
Importantly, this works even if there isn't a `impl !Error for MyLocalType`.
[`impl_intersection_has_impossible_obligation`]: https://doc.rust-lang.org/beta/nightly-rustc/rustc_trait_selection/traits/coherence/fn.impl_intersection_has_impossible_obligation.html
---
### Src Doc Rustc Dev Guide Src Compiler Debugging (`src/doc/rustc-dev-guide/src/compiler-debugging.md`)
# Debugging the compiler
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 [Queries Debugging and
Testing chapter](./incrcomp-debugging.md) or the [LLVM Debugging chapter](./backend/debugging.md)).
## Configuring the compiler
By default, rustc is built without most debug information.
To enable debug info,
set `rust.debug = true` in your bootstrap.toml.
Setting `rust.debug = true` turns on many different debug options (e.g., `debug-assertions`,
`debug-logging`, etc.) which can be individually tweaked if you want to, but many people
simply set `rust.debug = true`.
If you want to use GDB to debug rustc, please set `bootstrap.toml` with options:
```toml
rust.debug = true
rust.debuginfo-level = 2
```
> NOTE:
> This will use a lot of disk space
> (upwards of 35GB),
> and will take a lot more compile time.
> With `debuginfo-level = 1` (the default when `debug = true`),
> you will be able to track the execution path,
> but will lose the symbol information for debugging.
The default configuration will enable `symbol-mangling-version` v0.
This requires at least GDB v10.2,
otherwise you need to disable new symbol-mangling-version in `bootstrap.toml`.
```toml
rust.new-symbol-mangling = false
```
> See the comments in `bootstrap.example.toml` for more info.
You will need to rebuild the compiler after changing any configuration option.
## Suppressing the ICE file
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 `rustc-ice--.txt`.
If this is not desirable, you can prevent the ICE file from being created with `RUSTC_ICE=0`.
## Getting a backtrace
[getting-a-backtrace]: #getting-a-backtrace
When you have an ICE (panic in the compiler),
you can set `RUST_BACKTRACE=1` to get the stack trace of the `panic!` like in normal Rust programs.
IIRC backtraces **don't work** on MinGW, sorry.
If you have trouble or the backtraces are full of `unknown`,
you might want to find some way to use Linux, Mac, or MSVC on Windows.
In the default configuration (without `debug` set to `true`), you don't have line numbers enabled,
so the backtrace looks like this:
```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: >::with
34: >::with
35: rustc::ty::context::TyCtxt::create_and_enter
36: rustc_driver::driver::compile_input
37: rustc_driver::compiler_entrypoint
```
If you set `debug = true`, you will get line numbers for the stack trace.
Then the backtrace will look like this:
```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::compiler_entrypoint
at /home/user/rust/compiler/rustc_driver/src/lib.rs:253
```
## `-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 error message,
you can pass the `-Z treat-err-as-bug=n`, which will make the compiler panic on the `nth` error.
If you leave off `=n`,
the compiler will assume `1` for `n` and thus panic on the first error it encounters.
For example:
```bash
$ cat error.rs
```
```rust
fn main() {
1 + ();
}
```
```
$ 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
```
Now, where does the error above come from?
```
/* Detailed source-code truncated for AI context efficiency. */
```
Cool, now I have a backtrace for the error!
### 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
`-Z track-diagnostics` can help figure out where errors are emitted.
It uses `#[track_caller]` for this and prints its location alongside the error:
```
$ 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`:
<&'a f32 as Add>
<&'a f64 as Add>
<&'a i128 as Add>
<&'a i16 as Add>
<&'a i32 as Add>
<&'a i64 as Add>
<&'a i8 as Add>
<&'a isize as Add>
and 48 others
For more information about this error, try `rustc --explain E0277`.
```
This is similar but different to `-Z treat-err-as-bug`:
- it will print the locations for all errors emitted
- it does not require a compiler built with debug symbols
- you don't have to read through a big stack trace.
## Getting logging output
The compiler uses the [`tracing`] crate for logging.
[`tracing`]: https://docs.rs/tracing
For details, see [the chapter on tracing](./tracing.md).
## Narrowing (bisecting) regressions
The [cargo-bisect-rustc][bisect] tool can be used as a quick and easy way to
find exactly which PR caused a change in `rustc` behavior.
It automatically downloads `rustc` 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 *why* it was changed.
See [this tutorial][bisect-tutorial] on how to use it.
[bisect]: https://github.com/rust-lang/cargo-bisect-rustc
[bisect-tutorial]: https://rust-lang.github.io/cargo-bisect-rustc/tutorial.html
## Downloading artifacts from Rust's CI
The [rustup-toolchain-install-master][rtim] 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 `@bors try`.
This is helpful when you want to examine the resulting build of a PR
without doing the build yourself.
[rtim]: https://github.com/kennytm/rustup-toolchain-install-master
## `#[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`.
Here are some notable ones:
| Attribute | Description |
|----------------|-------------|
| `rustc_dump_def_parents` | Dumps the chain of `DefId` parents of certain definitions. |
| `rustc_dump_def_path` | Dumps the [`def_path_str`] of an item. |
| `rustc_dump_generics` | Dumps the generics of an item. |
| `rustc_dump_hidden_type_of_opaques` | Dumps the [hidden type of each opaque types][opaq] in the crate. |
| `rustc_dump_inferred_outlives` | Dumps implied bounds of an item. More precisely, the [`inferred_outlives_of`] an item. |
| `rustc_dump_item_bounds` | Dumps the [`item_bounds`] of an item. |
| `rustc_dump_layout` | [See this section](#debugging-type-layouts). |
| `rustc_dump_object_lifetime_defaults` | Dumps the [object lifetime defaults] of an item. |
| `rustc_dump_clauses` | Dumps the [`clauses_of`] an item. |
| `rustc_dump_symbol_name` | Dumps the mangled & demangled [`symbol_name`] of an item. |
| `rustc_dump_variances` | Dumps the [variances] of an item. |
| `rustc_dump_vtable` | Dumps the vtable layout of an impl, or a type alias of a dyn type. |
| `rustc_regions` | Dumps NLL closure region requirements. |
Right below you can find elaborate explainers on a selected few.
[`builtin_attrs`]: https://github.com/rust-lang/rust/blob/HEAD/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
[`clauses_of`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.clauses_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
Some compiler options for debugging specific features yield graphviz graphs -
e.g. the `#[rustc_mir(borrowck_graphviz_postflow="suffix.dot")]` attribute
on a function dumps various borrow-checker dataflow graphs in conjunction with
`-Zdump-mir-dataflow`.
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
```
Graphviz also comes with a preprocessor program,
[`unflatten`](https://graphviz.org/docs/cli/unflatten/),
that sometimes helps making the outputs look less oddly spread out.
It reads a dot file and outputs another dot file, so you can use it in a pipe,
e.g:
```
$ unflatten mir_dump/*.foo.-------.nll.0.regioncx.all.dot | dot -Tpdf -o foo-outlives.pdf
```
This is particularly useful for complicated region outlives graphs from
[the borrow checker](borrow-check/debugging.md).
[An online Graphviz editor and visualiser is
also available](https://dreampuf.github.io/GraphvizOnline).
## Narrowing (Bisecting) Regressions
The internal attribute `#[rustc_dump_layout(...)]` can be used to dump the
[`Layout`] of the type it is attached to.
For example:
```rust
#![feature(rustc_attrs)]
#[rustc_dump_layout(debug)]
type T<'a> = &'a u32;
```
Will emit the following:
```text
error: layout_of(&u32) = Layout {
size: Size(8 bytes),
align: AbiAlign {
abi: Align(8 bytes),
},
backend_repr: Scalar(
Initialized {
value: Pointer(
AddressSpace(
0,
),
),
valid_range: 1..=18446744073709551615,
},
),
fields: Primitive,
largest_niche: Some(
Niche {
offset: Size(0 bytes),
value: Pointer(
AddressSpace(
0,
),
),
valid_range: 1..=18446744073709551615,
},
),
uninhabited: false,
variants: Single {
index: 0,
},
max_repr_align: None,
unadjusted_abi_align: Align(8 bytes),
randomization_seed: 281492156579847,
}
--> src/lib.rs:4:1
|
4 | type T<'a> = &'a u32;
| ^^^^^^^^^^^^^^^^^^^^^
error: aborting due to previous error
```
[`Layout`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_public/abi/struct.Layout.html
## Debugging borrowcheck
Debugging the borrow checker has [its own chapter](borrow-check/debugging.md).
## Configuring CodeLLDB for debugging `rustc`
If you are using VSCode, and have edited your `bootstrap.toml` 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 [CodeLLDB] extension in VSCode to debug it.
Here is a sample `launch.json` file, being used to run a stage 1 compiler direct
from the directory where it is built (does not have to be "installed"):
```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"]
}
]
}
```
[CodeLLDB]: https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb
---
### Src Doc Rustc Dev Guide Src Compiler Src (`src/doc/rustc-dev-guide/src/compiler-src.md`)
# High-level overview of the compiler source
Now that we have [seen what the compiler does][orgch],
let's take a look at the structure of the [`rust-lang/rust`] repository,
where the rustc source code lives.
[`rust-lang/rust`]: https://github.com/rust-lang/rust
> You may find it helpful to read the ["Overview of the compiler"][orgch]
> chapter, which introduces how the compiler works, before this one.
[orgch]: ./overview.md
## Workspace structure
The [`rust-lang/rust`] repository consists of a single large cargo workspace
containing the compiler, the standard libraries ([`core`], [`alloc`], [`std`],
[`proc_macro`], [`etc`]), and [`rustdoc`], along with the build system and a
bunch of tools and submodules for building a full Rust distribution.
The repository consists of three main directories:
- [`compiler/`] contains the source code for `rustc`. It consists of many crates
that together make up the compiler.
- [`library/`] contains the standard libraries ([`core`], [`alloc`], [`std`],
[`proc_macro`], [`test`]), as well as the Rust runtime ([`backtrace`], [`rtstartup`],
[`lang_start`]).
- [`tests/`] contains the compiler tests.
- [`src/`] contains the source code for [`rustdoc`], [`clippy`], [`cargo`], the build system,
language docs, etc.
[`alloc`]: https://github.com/rust-lang/rust/tree/HEAD/library/alloc
[`backtrace`]: https://github.com/rust-lang/backtrace-rs/
[`cargo`]: https://github.com/rust-lang/cargo
[`clippy`]: https://github.com/rust-lang/rust/tree/HEAD/src/tools/clippy
[`compiler/`]: https://github.com/rust-lang/rust/tree/HEAD/compiler
[`core`]: https://github.com/rust-lang/rust/tree/HEAD/library/core
[`etc`]: https://github.com/rust-lang/rust/tree/HEAD/src/etc
[`lang_start`]: https://github.com/rust-lang/rust/blob/HEAD/library/std/src/rt.rs
[`library/`]: https://github.com/rust-lang/rust/tree/HEAD/library
[`proc_macro`]: https://github.com/rust-lang/rust/tree/HEAD/library/proc_macro
[`rtstartup`]: https://github.com/rust-lang/rust/tree/HEAD/library/rtstartup
[`rust-lang/rust`]: https://github.com/rust-lang/rust
[`rustdoc`]: https://github.com/rust-lang/rust/tree/HEAD/src/tools/rustdoc
[`src/`]: https://github.com/rust-lang/rust/tree/HEAD/src
[`std`]: https://github.com/rust-lang/rust/tree/HEAD/library/std
[`test`]: https://github.com/rust-lang/rust/tree/HEAD/library/test
[`tests/`]: https://github.com/rust-lang/rust/tree/HEAD/tests
## Compiler
The compiler is implemented in the various [`compiler/`] crates.
The [`compiler/`] crates all have names starting with `rustc_*`. These are a
collection of around 50 interdependent crates ranging in size from tiny to
huge. There is also the `rustc` crate which is the actual binary (i.e. the
`main` function); it doesn't actually do anything besides calling the
[`rustc_driver`] crate, which drives the various parts of compilation in other
crates.
The dependency order of these crates is complex, but roughly it is
something like this:
1. `rustc` (the binary) calls [`rustc_driver::main`][main].
1. [`rustc_driver`] depends on a lot of other crates, but the main one is
[`rustc_interface`].
1. [`rustc_interface`] depends on most of the other compiler crates. It is a
fairly generic interface for driving the whole compilation.
1. Most of the other `rustc_*` crates depend on [`rustc_middle`], which defines
a lot of central data structures in the compiler.
1. [`rustc_middle`] and most of the other crates depend on a handful of crates
representing the early parts of the compiler (e.g. the parser), fundamental
data structures (e.g. [`Span`]), or error reporting:
[`rustc_data_structures`], [`rustc_span`], [`rustc_errors`], etc.
[`rustc_data_structures`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_data_structures/index.html
[`rustc_driver`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/index.html
[`rustc_errors`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/index.html
[`rustc_interface`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/index.html
[`rustc_middle`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/index.html
[`rustc_span`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/index.html
[`Span`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/struct.Span.html
[main]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/fn.main.html
You can see the exact dependencies by running `cargo tree`,
just like you would for any other Rust package:
```console
cargo tree --package rustc_driver
```
One final thing: [`src/llvm-project`] is a submodule for our fork of LLVM.
During bootstrapping, LLVM is built and the [`compiler/rustc_llvm`] crate
contains Rust wrappers around LLVM (which is written in C++), so that the
compiler can interface with it.
Most of this book is about the compiler, so we won't have any further
explanation of these crates here.
[`compiler/rustc_llvm`]: https://github.com/rust-lang/rust/tree/HEAD/compiler/rustc_llvm
[`src/llvm-project`]: https://github.com/rust-lang/rust/tree/HEAD/src/
[`Cargo.toml`]: https://github.com/rust-lang/rust/blob/HEAD/Cargo.toml
### Big picture
The dependency structure of the compiler is influenced by two main factors:
1. Organization. The compiler is a _huge_ codebase; it would be an impossibly
large crate. In part, the dependency structure reflects the code structure
of the compiler.
2. Compile-time. By breaking the compiler into multiple crates, we can take
better advantage of incremental/parallel compilation using cargo. In
particular, we try to have as few dependencies between crates as possible so
that we don't have to rebuild as many crates if you change one.
At the very bottom of the dependency tree are a handful of crates that are used
by the whole compiler (e.g. [`rustc_span`]). The very early parts of the
compilation process (e.g. [parsing and the Abstract Syntax Tree (`AST`)][parser])
depend on only these.
After the [`AST`][parser] is constructed and other early analysis is done, the
compiler's [query system][query] gets set up. The query system is set up in a
clever way using function pointers. This allows us to break dependencies
between crates, allowing more parallel compilation. The query system is defined
in [`rustc_middle`], so nearly all subsequent parts of the compiler depend on
this crate. It is a really large crate, leading to long compile times. Some
efforts have been made to move stuff out of it with varying success. Another
side-effect is that sometimes related functionality gets scattered across
different crates. For example, linting functionality is found across earlier
parts of the crate, [`rustc_lint`], [`rustc_middle`], and other places.
Ideally there would be fewer, more cohesive crates, with incremental and
parallel compilation making sure compile times stay reasonable. However,
incremental and parallel compilation haven't gotten good enough for that yet,
so breaking things into separate crates has been our solution so far.
At the top of the dependency tree is [`rustc_driver`] and [`rustc_interface`]
which is an unstable wrapper around the query system helping drive various
stages of compilation. Other consumers of the compiler may use this interface
in different ways (e.g. [`rustdoc`] or maybe eventually `rust-analyzer`). The
[`rustc_driver`] crate first parses command line arguments and then uses
[`rustc_interface`] to drive the compilation to completion.
[parser]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/index.html
[`rustc_lint`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/index.html
[query]: ./query.md
## rustdoc
The bulk of [`rustdoc`] is in [`librustdoc`]. However, the [`rustdoc`] binary
itself is [`src/tools/rustdoc`], which does nothing except call [`rustdoc::main`].
There is also `JavaScript` and `CSS` for the docs in [`src/tools/rustdoc-js`]
and [`src/tools/rustdoc-themes`]. The type definitions for `--output-format=json`
are in a separate crate in [`src/rustdoc-json-types`].
You can read more about [`rustdoc`] in [this chapter][rustdoc-chapter].
[`librustdoc`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc/index.html
[`rustdoc::main`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc/fn.main.html
[`src/tools/rustdoc-js`]: https://github.com/rust-lang/rust/tree/HEAD/src/tools/rustdoc-js
[`src/tools/rustdoc-themes`]: https://github.com/rust-lang/rust/tree/HEAD/src/tools/rustdoc-themes
[`src/tools/rustdoc`]: https://github.com/rust-lang/rust/tree/HEAD/src/tools/rustdoc
[`src/rustdoc-json-types`]: https://github.com/rust-lang/rust/tree/HEAD/src/rustdoc-json-types
[rustdoc-chapter]: ./rustdoc.md
## Tests
The test suite for all of the above is in [`tests/`]. You can read more
about the test suite [in this chapter][testsch].
The test harness is in [`src/tools/compiletest/`][`compiletest/`].
[`tests/`]: https://github.com/rust-lang/rust/tree/HEAD/tests
[testsch]: ./tests/intro.md
## Build System
There are a number of tools in the repository just for building the compiler,
standard library, [`rustdoc`], etc, along with testing, building a full Rust
distribution, etc.
One of the primary tools is [`src/bootstrap/`]. You can read more about
bootstrapping [in this chapter][bootstch]. The process may also use other tools
from [`src/tools/`], such as [`tidy/`] or [`compiletest/`].
[`compiletest/`]: https://github.com/rust-lang/rust/tree/HEAD/src/tools/compiletest
[`src/bootstrap/`]: https://github.com/rust-lang/rust/tree/HEAD/src/bootstrap
[`src/tools/`]: https://github.com/rust-lang/rust/tree/HEAD/src/tools
[`tidy/`]: https://github.com/rust-lang/rust/tree/HEAD/src/tools/tidy
[bootstch]: ./building/bootstrapping/intro.md
## Standard library
This code is fairly similar to most other Rust crates except that it must be
built in a special way because it can use unstable ([`nightly`]) features.
The standard library is sometimes referred to as [`libstd or the "standard facade"`].
[`libstd or the "standard facade"`]: https://rust-lang.github.io/rfcs/0040-libstd-facade.html
[`nightly`]: https://doc.rust-lang.org/nightly/nightly-rustc/
## Other
There are a lot of other things in the `rust-lang/rust` repo that are related
to building a full Rust distribution. Most of the time you don't need to worry about them.
These include:
- [`src/ci`]: The CI configuration. This actually quite extensive because we
run a lot of tests on a lot of platforms.
- [`src/doc`]: Various documentation, including submodules for a few books.
- [`src/etc`]: Miscellaneous utilities.
- And more...
[`src/ci`]: https://github.com/rust-lang/rust/tree/HEAD/src/ci
[`src/doc`]: https://github.com/rust-lang/rust/tree/HEAD/src/doc
[`src/etc`]: https://github.com/rust-lang/rust/tree/HEAD/src/etc
---
### Src Doc Rustc Dev Guide Src Compiler Team (`src/doc/rustc-dev-guide/src/compiler-team.md`)
# About the compiler team
> NOTE:
> There exists much detail about the team [on Forge], making most of the following obsolete.
rustc is maintained by the [Rust compiler team][team].
The people who belong to
this team collectively work to track regressions and implement new features.
Members of the Rust compiler team are people who have made significant
contributions to rustc and its design.
[on Forge]: https://forge.rust-lang.org/compiler
[team]: https://www.rust-lang.org/governance/teams/compiler
## Discussion
Currently the compiler team chats in Zulip:
- Team chat occurs in the [`t-compiler`][zulip-t-compiler] stream on the Zulip instance
- There are also a number of other associated Zulip channels,
such as [`t-compiler/help`][zulip-help], where people can ask for help
with rustc development, or [`t-compiler/meetings`][zulip-meetings],
where the team holds their weekly triage and steering meetings.
## Reviewers
If you're interested in figuring out who can answer questions about a
particular part of the compiler, or you'd just like to know who works on what,
check out [triagebot.toml's assign section][map].
It contains a listing of the various parts of the compiler and a list of people
who are reviewers of each part.
[map]: https://github.com/rust-lang/rust/blob/HEAD/triagebot.toml
## Rust compiler meeting
The compiler team has a weekly meeting where we do triage and try to
generally stay on top of new bugs, regressions, and discuss important things in general.
They are held on [Zulip][zulip-meetings].
It works roughly as follows:
- **Announcements, MCPs/FCPs, and WG-check-ins:** We share some
announcements with the rest of the team about important things we want everyone to be aware of.
We also share the status of MCPs and FCPs and we
use the opportunity to have a couple of WGs giving us an update about their work.
- **Check for beta and stable nominations:** These are nominations of things to
backport to beta and stable respectively.
We then look for new cases where the compiler broke previously working code in the wild.
Regressions are important issues to fix, so it's
likely that they are tagged as P-critical or P-high; the major
exception would be bug fixes (though even there we often [aim to give
warnings first][procedure]).
- **Review P-critical and P-high bugs:** P-critical and P-high bugs are
those that are sufficiently important for us to actively track progress.
P-critical and P-high bugs should ideally always have an assignee.
- **Check `S-waiting-on-t-compiler` and `I-compiler-nominated` issues:** These are issues where
feedback from the team is desired.
- **Look over the performance triage report:** We check for PRs that made the
performance worse and try to decide if it's worth reverting the performance regression or if
the regression can be addressed in a future PR.
The meeting currently takes place on Thursdays at 10am Boston time
(UTC-4 typically, but daylight savings time sometimes makes things complicated).
[procedure]: ./bug-fix-procedure.md
[zulip-t-compiler]: https://rust-lang.zulipchat.com/#narrow/stream/131828-t-compiler
[zulip-help]: https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp
[zulip-meetings]: https://rust-lang.zulipchat.com/#narrow/stream/238009-t-compiler.2Fmeetings
## Team membership
Membership in the Rust team is typically offered when someone has been
making significant contributions to the compiler for some time.
Membership is both a recognition but also an obligation:
compiler team members are generally expected to help with upkeep as
well as doing reviews and other work.
If you are interested in becoming a compiler team member, the first
thing to do is to start fixing some bugs, or get involved in a working group.
One good way to find bugs is to look for
[open issues tagged with E-easy](https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy)
or [E-mentor](https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-mentor).
You can also dig through the graveyard of PRs that were
[closed due to inactivity](https://github.com/rust-lang/rust/pulls?q=is%3Apr+label%3AS-inactive),
some of them may contain work that is still useful - refer to the
associated issues, if any - and only needs some finishing touches
for which the original author didn't have time.
### r+ rights
Once you have made a number of individual PRs to rustc, we will often offer r+ privileges.
This means that you have the right to instruct
"bors" (the robot that manages which PRs get landed into rustc) to merge a PR
([here are some instructions for how to talk to bors][bors-guide]).
[bors-guide]: https://bors.rust-lang.org/
The guidelines for reviewers are as follows:
- You are always welcome to review any PR, regardless of who it is assigned to.
However, do not r+ PRs unless:
- You are confident in that part of the code.
- You are confident that nobody else wants to review it first.
- For example, sometimes people will express a desire to review a
PR before it lands, perhaps because it touches a particularly
sensitive part of the code.
- Always be polite when reviewing: you are a representative of the
Rust project, so it is expected that you will go above and beyond
when it comes to the [Code of Conduct].
[Code of Conduct]: https://www.rust-lang.org/policies/code-of-conduct
### Reviewer rotation
Once you have r+ rights, you can also be added to the [reviewer rotation].
[triagebot] is the bot that [automatically assigns] incoming PRs to reviewers.
If you are added, you will be randomly selected to review PRs.
If you find you are assigned a PR that you don't feel comfortable
reviewing, you can also leave a comment like `r? @so-and-so` to assign
to someone else — if you don't know who to request, just write `r?
@nikomatsakis for reassignment` and @nikomatsakis will pick someone for you.
[reviewer rotation]: https://github.com/rust-lang/rust/blob/36285c5de8915ecc00d91ae0baa79a87ed5858d5/triagebot.toml#L528-L577
[triagebot]: https://github.com/rust-lang/triagebot/
[automatically assigns]: https://forge.rust-lang.org/triagebot/pr-assignment.html
Getting on the reviewer rotation is much appreciated as it lowers the review burden for all of us!
However, if you don't have time to give
people timely feedback on their PRs, it may be better that you don't get on the list.
---
### Src Doc Rustc Dev Guide Src Const Eval (`src/doc/rustc-dev-guide/src/const-eval.md`)
# Constant Evaluation
Constant evaluation is the process of computing values at compile time.
For a specific item (constant/static/array length) this happens after the MIR for the
item is borrow-checked and optimized.
In many cases trying to const evaluate an
item will trigger the computation of its MIR for the first time.
Prominent examples are:
* The initializer of a `static`
* Array length
* needs to be known to reserve stack or heap space
* Enum variant discriminants
* needs to be known to prevent two variants from having the same discriminant
* Patterns
* need to be known to check for overlapping patterns
Additionally constant evaluation can be used to reduce the workload or binary
size at runtime by precomputing complex operations at compile time and only storing the result.
All uses of constant evaluation can either be categorized as "influencing the type system"
(array lengths, enum variant discriminants, const generic parameters), or as solely being
done to precompute expressions to be used at runtime.
Constant evaluation can be done by calling the `const_eval_*` functions of `TyCtxt`.
They're the wrappers of the `const_eval` query.
* `const_eval_global_id_for_typeck` evaluates a constant to a valtree,
so the result value can be further inspected by the compiler.
* `const_eval_global_id` evaluate a constant to an "opaque blob" containing its final value;
this is only useful for codegen backends and the CTFE evaluator engine itself.
* `eval_static_initializer` specifically computes the initial values of a static.
Statics are special; all other functions do not represent statics correctly
and have thus assertions preventing their use on statics.
The `const_eval_*` functions use a [`ParamEnv`](./typing-parameter-envs.md) of environment
in which the constant is evaluated (e.g. the function within which the constant is used)
and a [`GlobalId`].
The `GlobalId` is made up of an `Instance` referring to a constant
or static or of an `Instance` of a function and an index into the function's `Promoted` table.
Constant evaluation returns an [`EvalToValTreeResult`] for type system constants
or [`EvalToConstValueResult`] with either the error, or a representation of the
evaluated constant: a [valtree](mir/index.md#valtrees) or a [MIR constant
value](mir/index.md#mir-constant-values), respectively.
[`GlobalId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/interpret/struct.GlobalId.html
[`EvalToConstValueResult`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/interpret/error/type.EvalToConstValueResult.html
[`EvalToValTreeResult`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/interpret/error/type.EvalToValTreeResult.html
---
### Src Doc Rustc Dev Guide Src Const Generics (`src/doc/rustc-dev-guide/src/const-generics.md`)
# Const generics
## Kinds of const arguments
Most of the kinds of `ty::Const` that exist have direct parallels to kinds of types that exist, for example `ConstKind::Param` is equivalent to `TyKind::Param`.
The main interesting points here are:
- [`ConstKind::Alias`], which is equivalent to `TyKind::Alias`.
- [`ConstKind::Value`], which is the final value of a `ty::Const` after monomorphization.
This is somewhat similar to fully concrete things like `TyKind::Str` or `TyKind::ADT`.
For a complete list of *all* kinds of const arguments and how they are actually represented in the type system, see the [`ConstKind`] type.
Inference Variables are quite boring and treated equivalently to type inference variables almost everywhere.
Const Parameters are also similarly boring and equivalent to uses of type parameters almost everywhere.
However, there are some interesting subtleties with how they are handled during parsing, name resolution, and AST lowering: [ambig-unambig-ty-and-consts].
## Anon consts
Anon consts (short for anonymous const items) are how arbitrary expression are represented in const generics, for example an array length of `1 + 1` or `foo()` or even just `0`.
These are unique to const generics and have no real type equivalent.
### Desugaring
```rust
struct Foo;
type Alias = [u8; 1 + 1];
```
In this example we have a const argument of `1 + 1` (the array length) which is represented as an *anon const*.
The desugaring would look something like:
```rust
struct Foo;
const ANON: usize = 1 + 1;
type Alias = [u8; ANON];
```
Where the array length in `[u8; ANON]` isn't itself an anon const containing a usage of `ANON`, but a kind of "direct" usage of the `ANON` const item ([`ConstKind::Alias`]).
Anon consts do not inherit any generic parameters of the item they are inside of:
```rust
struct Foo;
type Alias = [T; 1 + 1];
// Desugars To;
struct Foo;
const ANON: usize = 1 + 1;
type Alias = [T; ANON];
```
Note how the `ANON` const has no generic parameters or where clauses, even though `Alias` has both a type parameter `T` and a where clauses `T: Sized`.
This desugaring is part of how we enforce that anon consts can't make use of generic parameters.
While it's useful to think of anon consts as being desugared to real const items, the compiler does not actually implement things this way.
At AST lowering time we do not yet know the *type* of the anon const, so we can't desugar to a real HIR item with an explicitly written type.
To work around this, we have [`DefKind::AnonConst`] and [`hir::Node::AnonConst`],
which are used to represent these anonymous const items that can't actually be desugared.
The types of these anon consts are obtainable from the [`type_of`] query.
However, the `type_of` query does not actually contain logic for computing the type (and, in fact, it just ICEs when called).
Instead, HIR Ty lowering is responsible for *feeding* the value of the `type_of` query for any anon consts that get lowered.
HIR Ty lowering can determine the type of the anon const by looking at the type of the Const Parameter that the anon const is an argument to.
TODO: write a chapter on query feeding and link it here
In some sense the desugarings from the previous examples are to:
```rust
struct Foo;
type Alias = [u8; 1 + 1];
// sort-of desugars to pseudo-rust:
struct Foo;
const ANON = 1 + 1;
type Alias = [u8; ANON];
```
When we go through HIR ty lowering for the array type in `Alias`, we will lower the array length too, and feed `type_of(ANON) -> usize`.
This will effectively set the type of the `ANON` const item during some later part of the compiler rather than when constructing the HIR.
After all of this desugaring has taken place the final representation in the type system (ie as a `ty::Const`) is a `ConstKind::Alias` with the `DefId` of the `AnonConst`.
This is equivalent to how we would represent a usage of an actual const item if we were to represent them without going through an anon const (e.g. when `gca_generic_const_args` is enabled).
This allows the representation for const "aliases" to be the same as the representation of `TyKind::Alias`.
Having a proper HIR body also allows for a *lot* of code re-use, e.g. we can reuse HIR typechecking and all of the lowering steps to MIR where we can then reuse const eval.
### Enforcing lack of generic parameters
There are three ways that we enforce anon consts can't use generic parameters:
1. Name Resolution will not resolve paths to generic parameters when inside of an anon const
2. HIR Ty lowering will error when a `Self` type alias to a type referencing generic parameters is encountered inside of an anon const
3. Anon Consts do not inherit where clauses or generics from their parent definition (ie [`generics_of`] does not contain a parent for anon consts)
```rust
// *1* Errors in name resolution
type Alias = [u8; N + 1];
//~^ ERROR: generic parameters may not be used in const operations
// *2* Errors in HIR Ty lowering:
struct Foo(T);
impl Foo {
fn assoc() -> [u8; { let a: Self; 0 }] {}
//~^ ERROR: generic `Self` types are currently not permitted in anonymous constants
}
// *3* Errors due to lack of where clauses on the desugared anon const
trait Trait {
const ASSOC: usize;
}
fn foo() -> [u8; <()>::ASSOC]
//~^ ERROR: no associated item named `ASSOC` found for unit type `()`
where
(): Trait {}
```
The second point is particularly subtle as it is very easy to get HIR Ty lowering wrong and not properly enforce that anon consts can't use generic parameters.
The existing check is too conservative and accidentally permits some generic parameters to wind up in the body of the anon const [#144547](https://github.com/rust-lang/rust/issues/144547).
Erroneously allowing generic parameters in anon consts can sometimes lead to ICEs but can also lead to accepting illformed programs.
The third point is also somewhat subtle, by not inheriting any of the where clauses of the parent item we can't wind up with the trait solving inferring inference variables to generic parameters based off where clauses in scope that mention generic parameters.
For example, inferring `?x=T` from the expression `<() as Trait>::ASSOC` and an in-scope where clause of `(): Trait`.
This also makes it much more likely that the compiler will ICE or atleast incidentally emit some kind of error if we *do* accidentally allow generic parameters in an anon const, as the anon const will have none of the necessary information in its environment to properly handle the generic parameters.
#### Array repeat expressions
The one exception to all of the above is repeat counts of array expressions.
As a *backwards compatibility hack*, we allow the repeat count const argument to use generic parameters.
```rust
fn foo() {
let a = [1_u8; size_of::()];
}
```
However, to avoid most of the problems involved in allowing generic parameters in anon const const arguments,
we require that the constant be evaluated before monomorphization (e.g. during type checking).
In some sense we only allow generic parameters here when they are semantically unused.
In the previous example the anon const can be evaluated for any type parameter `T` because raw pointers to sized types always have the same size (e.g. `8` on 64bit platforms).
When detecting that we evaluated an anon const that syntactically contained generic parameters, but did not actually depend on them for evaluation to succeed, we emit the [`const_evaluatable_unchecked` FCW][cec_fcw].
This is intended to become a hard error once we stabilize more ways of using generic parameters in const arguments, for example `gca_min_const_items` or (the now dead) `generic_const_exprs`.
The implementation for this FCW can be found here: [`const_eval_resolve_for_typeck`]
### Incompatibilities with `generic_const_parameter_types`
Supporting const parameters such as `const N: [u8; M]` or `const N: Foo` does not work very nicely with the current anon consts setup.
There are two reasons for this:
1. As anon consts cannot use generic parameters, their type *also* can't reference generic parameters.
This means it is fundamentally not possible to use an anon const as an argument to a const parameter whose type still references generic parameters.
```rust
#![feature(adt_const_params, generic_const_parameter_types)]
fn foo() {}
fn bar() {
// There is no way to specify the const argument to `M`
foo::();
}
```
2. We currently require knowing the type of anon consts when lowering them during HIR ty lowering.
With generic const parameter types it may be the case that the currently known type contains inference variables (ie may not be fully known yet).
```rust
#![feature(adt_const_params, generic_const_parameter_types)]
fn foo() {}
fn bar() {
// The const argument to `N` must be explicitly specified
// even though it is able to be inferred
foo::<_, { [1_u8; 3] }>();
}
```
It is currently unclear what the right way to make `generic_const_parameter_types` work nicely with the rest of const generics is.
`generic_const_exprs` would have allowed for anon consts with types referencing generic parameters, but that design wound up unworkable.
`gca_min_const_items` will allow for some expressions (for example array construction) to be representable without an anon const and therefore without running into these issues, though whether this is *enough* has yet to be determined.
## Checking types of const arguments
In order for a const argument to be well formed it must have the same type as the const parameter it is an argument to.
For example, a const argument of type `bool` for an array length is not well formed, as an array's length parameter has type `usize`.
```rust
type Alias = [u8; B];
//~^ ERROR:
```
To check this, we have [`ClauseKind::ConstArgHasType(ty::Const, Ty)`][const_arg_has_type], where,
for each Const Parameter defined on an item,
we also desugar an equivalent `ConstArgHasType` clause into its list of where cluases.
This ensures that whenever we check wellformedness of anything by proving all of its clauses,
we also check happen to check that all of the Const Arguments have the correct type.
```rust
fn foo() {}
// desugars to in pseudo-rust
fn foo()
where
// ConstArgHasType(N, usize)
N: usize, {}
```
Proving `ConstArgHasType` goals is implemented by first computing the type of the const argument, then equating it with the provided type.
A rough outline of how the type of a Const Argument may be computed:
- [`ConstKind::Param(N)`][`ConstKind::Param`] can be looked up in the [`ParamEnv`] to find a `ConstArgHasType(N, ty)` clause
- [`ConstKind::Value`] stores the type of the value inside itself so can trivially be accessed
- [`ConstKind::Alias`] can have its type computed by calling the `type_of` query
- See the implementation of proving `ConstArgHasType` goals for more detailed information
`ConstArgHasType` is *the* soundness critical way that we check Const Arguments have the correct type.
However, we do *indirectly* check the types of Const Arguments a different way in some cases.
```rust
type Alias = [u8; true];
// desugars to
const ANON: usize = true;
type Alias = [u8; ANON];
```
By feeding the type of an anon const with the type of the Const Parameter,
we guarantee that the `ConstArgHasType` goal involving the anon const will succeed.
In cases where the type of the anon const doesn't match the type of the Const Parameter,
what actually happens is a *type checking* error when type checking the anon const's body.
Looking at the above example, this corresponds to `[u8; ANON]` being a well formed type because `ANON` has type `usize`, but the *body* of `ANON` being illformed and resulting in a type checking error because `true` can't be returned from a const item of type `usize`.
[ambig-unambig-ty-and-consts]: ./ambig-unambig-ty-and-consts.md
[`ConstKind`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/consts/type.ConstKind.html
[`ConstKind::Infer`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/consts/type.ConstKind.html#variant.Infer
[`ConstKind::Param`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/consts/type.ConstKind.html#variant.Param
[`ConstKind::Alias`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/consts/type.ConstKind.html#variant.Alias
[`ConstKind::Value`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/consts/type.ConstKind.html#variant.Value
[const_arg_has_type]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/type.ClauseKind.html#variant.ConstArgHasType
[`ParamEnv`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.ParamEnv.html
[`generics_of`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyCtxt.html#impl-TyCtxt%3C'tcx%3E/method.generics_of
[`type_of`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyCtxt.html#method.type_of
[`DefKind::AnonConst`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def/enum.DefKind.html#variant.AnonConst
[`hir::Node::AnonConst`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/hir/enum.Node.html#variant.AnonConst#
[cec_fcw]: https://github.com/rust-lang/rust/issues/76200
[`const_eval_resolve_for_typeck`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyCtxt.html#method.const_eval_resolve_for_typeck
---
### Src Doc Rustc Dev Guide Src Contributing To Guide (`src/doc/rustc-dev-guide/src/contributing-to-guide.md`)
# Writing rustc-dev-guide documentation
Contributions to the [rustc-dev-guide] are always welcome, and can be made directly at
[the rust-lang/rustc-dev-guide repo][rdgrepo].
The issue tracker in that repo is also a great way to find things that need doing.
There are issues for beginners and advanced compiler devs alike!
Just a few things to keep in mind:
[rustc API docs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle
- When writing about a particular part of the compiler's code, we
recommend that you link to the relevant parts of the [rustc API docs].
- Use sentence case for chapter and section titles.
- Use dashes (`-`) to separate words in file names.
- Links within the guide should use `.md` relative links, not `.html` links.
CI will enforce this.
- Please try to avoid overly long lines and use semantic line breaks (where you break the line after each sentence).
This makes it easier to review diffs, since they avoid reflowing other unrelated prose.
There is no strict limit on line lengths;
let the sentence or part of the sentence flow to its proper end on the same line.
You can use a tool in ci/sembr to help with this.
Its help output can be seen with this command:
```console
cargo run --manifest-path ci/sembr/Cargo.toml -- --help
```
- When contributing text to the guide, please contextualize the information with some time period
and/or a reason so that the reader knows how much to trust the information.
Aim to provide a reasonable amount of context, and consider including:
- A reason for why the text may be out of date other than "change",
as change is a constant across the project.
- The date the comment was added, e.g. instead of writing _"Currently, ..."_
or _"As of now, ..."_, consider adding the date, in one of the following formats:
- Jan 2021
- January 2021
- jan 2021
- january 2021
There is a CI action (in `.github/workflows/date-check.yml`)
that generates a monthly report showing those that are over 6 months old
([example](https://github.com/rust-lang/rustc-dev-guide/issues/2052)).
For the action to pick the date, add a special annotation before specifying the date:
```md
Jul 2026
```
Example:
```md
As of Jul 2026, the foo did the bar.
```
For cases where the date should not be part of the visible rendered output,
use the following instead:
```md
```
- A link to a relevant WG, tracking issue, `rustc` rustdoc page, or similar, that may provide
further explanation for the change process or a way to verify that the information is not
outdated.
## ⚠️ Note: Where to contribute `rustc-dev-guide` changes
For detailed information about where to contribute rustc-dev-guide changes and the benefits of doing so,
see [the rustc-dev-guide team documentation].
[rustc-dev-guide]: https://rustc-dev-guide.rust-lang.org/
[rdgrepo]: https://github.com/rust-lang/rustc-dev-guide
[the rustc-dev-guide team documentation]: https://forge.rust-lang.org/rustc-dev-guide/index.html#where-to-contribute-rustc-dev-guide-changes
---
### Src Doc Rustc Dev Guide Src Contributing (`src/doc/rustc-dev-guide/src/contributing.md`)
# Contribution procedures
## Bug reports
While bugs are unfortunate, they're a reality in software.
We can't fix what we don't know about, so please report liberally.
If you're not sure if something is a bug, feel free to open an issue anyway.
**If you believe reporting your bug publicly represents a security risk to Rust users,
please follow our [instructions for reporting security vulnerabilities][vuln]**.
[vuln]: https://www.rust-lang.org/policies/security
If you're using the nightly channel, please check if the bug exists in the
latest toolchain before filing your bug.
It might be fixed already.
If you have the chance, before reporting a bug, please [search existing issues],
as it's possible that someone else has already reported your error.
This doesn't always work, and sometimes it's hard to know what to search for, so consider this
extra credit.
We won't mind if you accidentally file a duplicate report.
Similarly, to help others who encountered the bug find your issue, consider
filing an issue with a descriptive title, which contains information that might be unique to it.
This can be the language or compiler feature used, the
conditions that trigger the bug, or part of the error message if there is any.
An example could be: **"impossible case reached" on lifetime inference for impl
Trait in return position**.
Opening an issue is as easy as following [this link][create an issue] and filling out the fields
in the appropriate provided template.
[search existing issues]: https://github.com/rust-lang/rust/issues?q=is%3Aissue
[create an issue]: https://github.com/rust-lang/rust/issues/new/choose
## Other procedures
Other contribution procedures are documented with the parts of the guide that own them:
- For routine changes or large, cross-cutting pull requests, see [normal code changes](getting-started.md#bug-fixes-or-normal-code-changes), [PR lifecycle](./pr-lifecycle.md), and [pull request guidance](getting-started.md#pull-requests).
- For new features, major changes, and breaking changes, see [Implementing new language features](implementing-new-features.md) and [Procedures for breaking changes](bug-fix-procedure.md).
- For performance-sensitive changes, see [Performance testing](tests/perf.md#performance-considerations).
- For compiler documentation, see [Contributing documentation](building/compiler-documenting.md#contributing-documentation).
- For issue triage, see [Issue triage](getting-started.md#issue-triage).
- For guidance on LLM usage, see [Running LLMs](llm-guidance.md).
- For changes to this guide itself, see [Writing rustc-dev-guide documentation](contributing-to-guide.md).
- For external dependencies, see [Using external repositories](external-repos.md).
- For further resources, see [About this guide](about-this-guide.md#other-places-to-find-information).
---
### Src Doc Rustc Dev Guide Src Conventions (`src/doc/rustc-dev-guide/src/conventions.md`)
# Coding conventions
This chapter covers [formatting](#formatting), [coding for correctness](#cc),
[using crates from crates.io](#cio), and some tips on [structuring your PR for easy review](#er).
## Formatting and the tidy script
rustc is moving towards the [Rust standard coding style][fmt].
However, for now we don't use stable `rustfmt`; we use a pinned version with a
special config, so this may result in different style from normal [`rustfmt`].
Therefore, formatting this repository using `cargo fmt` is not recommended.
Instead, formatting should be done using `./x fmt`.
It's a good habit to run `./x fmt` before every commit, as this reduces conflicts later.
Formatting is checked by the `tidy` script.
It runs automatically when you do `./x test` and can be run in isolation with `./x fmt --check`.
> **Note: Formatting and test suites**
>
> Most Rust source files under `tests/` directory are not formatted for reasons
> such as whitespace sensitivity, nature of snapshot tests, location-sensitive
> comments and more.
>
> Consult the `ignore` entries in
> for which test
> files are not formatted.
If you want to use format-on-save in your editor, the pinned version of
`rustfmt` is built under `build//stage0/bin/rustfmt`.
[fmt]: https://github.com/rust-dev-tools/fmt-rfcs
[`rustfmt`]:https://github.com/rust-lang/rustfmt
### Formatting C++ code
The compiler contains some C++ code for interfacing with parts of LLVM that
don't have a stable C API.
When modifying that code, use this command to format it:
```console
./x test tidy --extra-checks cpp:fmt --bless
```
This uses a pinned version of `clang-format`, to avoid relying on the local environment.
### Formatting and linting Python code
The Rust repository contains quite a lot of Python code.
We try to keep it both linted and formatted by the [ruff] tool.
When modifying Python code, use this command to format it:
```console
./x test tidy --extra-checks py:fmt --bless
```
And, the following command to run lints:
```console
./x test tidy --extra-checks py:lint
```
These use a pinned version of `ruff`, to avoid relying on the local environment.
[ruff]: https://github.com/astral-sh/ruff
### Copyright notice
In the past, files began with a copyright and license notice.
Please **omit** this notice for new files licensed under the standard terms (MIT OR Apache-2.0).
All of the copyright notices should be gone by now, but if you come across one
in the rust-lang/rust repo, feel free to open a PR to remove it.
### Line length
Lines should be at most 100 characters.
It's even better if you can keep things to 80.
Sometimes, and particularly for tests, it can be necessary to exempt yourself from this limit.
In that case, you can add a comment towards the top of the file like so:
```rust
// ignore-tidy-linelength
```
### Tabs vs spaces
Prefer 4-space indents.
## Coding for correctness
Beyond formatting, there are a few other tips that are worth following.
### Prefer exhaustive matches
Using `_` in a match is convenient, but it means that when new
variants are added to the enum, they may not get handled correctly.
Ask yourself: if a new variant were added to this enum, what's the
chance that it would want to use the `_` code, versus having some other treatment?
Unless the answer is "low", then prefer an exhaustive match.
The same advice applies to `if let` and `while let`,
which are effectively tests for a single variant.
### Use "TODO" comments for things you don't want to forget
As a useful tool to yourself, you can insert a `// TODO` comment
for something that you want to get back to before you land your PR:
```rust,ignore
fn do_something() {
if something_else {
unimplemented!(); // TODO write this
}
}
```
The tidy script will report an error for a `// TODO` comment, so this
code would not be able to land until the TODO is fixed (or removed).
This can also be useful in a PR as a way to signal from one commit that you are
leaving a bug that a later commit will fix:
```rust,ignore
if foo {
return true; // TODO wrong, but will be fixed in a later commit
}
```
If you want to leave a note in the codebase, use `// FIXME` instead.
### Follow the style of surrounding code
Use existing helpers and avoid duplicating logic or validation.
### [Avoid duplicated sources of truth](https://react.dev/learn/choosing-the-state-structure)
Trying to keep data in sync between two different places is a code smell.
### Use types to enforce invariants
When practical, [make invalid states unrepresentable](https://kentcdodds.com/blog/make-impossible-states-impossible), [not just checked at construction time](https://lexi-lambda.github.io/blog/2020/11/01/names-are-not-type-safety/).
### Write useful comments
[Write comments that say *why*][mit-comment-style] you have done a thing, not *what* you have done.
It's ok to go into detail about non-obvious bugs.
[mit-comment-style]: https://mitcommlab.mit.edu/broad/commkit/coding-and-comment-style/
### Preserve existing behavior
Consider platform differences and error cases.
Look for relevant tests that exercise the edge cases.
### Work in small steps
Work in small, independently testable steps.
Run the relevant tests after every meaningful change, so you know where you first went wrong.
## Using crates from crates.io
See the [crates.io dependencies][crates] section.
## How to structure your PR
How you prepare the commits in your PR can make a big difference for the reviewer.
Here are some tips.
**Isolate "pure refactorings" into their own commit.** For example, if
you rename a method, then put that rename into its own commit, along
with the renames of all the uses.
**More commits is usually better.** If you are doing a large change,
it's almost always better to break it up into smaller steps that can be [independently understood][atomic commits].
The one thing to be aware of is that if
you introduce some code following one strategy, then change it
dramatically (versus adding to it) in a later commit, that 'back-and-forth' can be confusing.
[atomic commits]: https://github.blog/developer-skills/github/write-better-commits-build-better-projects/#%e2%9a%9b%ef%b8%8f-resize-and-stabilize-the-commits
**Format liberally.** While only the final commit of a PR must be correctly
formatted, it is both easier to review and less noisy to format each commit
individually using `./x fmt`.
**No merges.** We do not allow merge commits into our history, other than those by bors.
If you get a merge conflict, rebase instead via a
command like `git rebase --interactive rust-lang/main` (presuming you use the
name `rust-lang` for your remote).
**Individual commits do not have to build (but it's nice).** We do not
require that every intermediate commit successfully builds – we only
expect to be able to bisect at a PR level.
However, if you *can* make individual commits build, that is always helpful.
## Naming conventions
Apart from normal Rust style/naming conventions, there are also some specific to the compiler.
- `cx` tends to be short for "context" and is often used as a suffix.
For example, `tcx` is a common name for the [Typing Context][tcx].
- [`'tcx`][tcx] is used as the lifetime name for the Typing Context.
- Because `crate` is a keyword, if you need a variable to represent something
crate-related, often the spelling is changed to `krate`.
[tcx]: ./ty.md
[crates]: ./crates-io.md
---
### Src Doc Rustc Dev Guide Src Coroutine Closures (`src/doc/rustc-dev-guide/src/coroutine-closures.md`)
# Async closures/"coroutine-closures"
Please read [RFC 3668] to understand the general motivation of the feature.
This is a very technical and somewhat "vertical" chapter;
ideally, we'd split this and sprinkle it across all the relevant chapters,
but for the purposes of understanding async closures *holistically*,
I've put this together all here in one chapter.
## Coroutine-closures -- a technical deep dive
Coroutine-closures are a generalization of async closures, being special syntax for closure expressions which return a coroutine, notably one that is allowed to capture from the closure's upvars.
For now, the only usable kind of coroutine-closure is the async closure, and supporting async closures is the extent of this PR. We may eventually support `gen || {}`, etc., and most of the problems and curiosities described in this document apply to all coroutine-closures in general.
As a consequence of the code being somewhat general, this document may flip between calling them "async closures" and "coroutine-closures".
The future that is returned by the async closure will generally be called the "coroutine" or the "child coroutine".
### HIR
Async closures (and in the future, other coroutine flavors such as `gen`) are represented in HIR as a `hir::Closure`.
The closure-kind of the `hir::Closure` is `ClosureKind::CoroutineClosure(_)`[^k1], which wraps an async block, which is also represented in HIR as a `hir::Closure`.
The closure-kind of the async block is `ClosureKind::Closure(CoroutineKind::Desugared(_, CoroutineSource::Closure))`[^k2].
[^k1]:
[^k2]:
Like `async fn`, when lowering an async closure's body, we need to unconditionally move all of the closures arguments into the body so they are captured.
This is handled by `lower_coroutine_body_with_moved_arguments`[^l1].
The only notable quirk with this function is that the async block we end up generating as a capture kind of `CaptureBy::ByRef`[^l2].
We later force all of the *closure args* to be captured by-value[^l3], but we don't want the *whole* async block to act as if it were an `async move`, since that would defeat the purpose of the self-borrowing of an async closure.
[^l1]:
[^l2]:
[^l3]:
### `rustc_middle::ty` representation
For the purposes of keeping the implementation mostly future-compatible (i.e. with gen `|| {}` and `async gen || {}`), most of this section calls async closures "coroutine-closures".
The main thing that this PR introduces is a new `TyKind` called `CoroutineClosure`[^t1] and corresponding variants on other relevant enums in typeck and borrowck (`UpvarArgs`, `DefiningTy`, `AggregateKind`).
[^t1]:
We introduce a new `TyKind` instead of generalizing the existing `TyKind::Closure` due to major representational differences in the type.
The major differences between `CoroutineClosure`s can be explored by first inspecting the `CoroutineClosureArgsParts`, which is the "unpacked" representation of the coroutine-closure's generics.
#### Similarities to closures
Like a closure, we have `parent_args`, a `closure_kind_ty`, and a `tupled_upvars_ty`. These represent the same thing as their closure counterparts; namely: the generics inherited from the body that the closure is defined in, the maximum "calling capability" of the closure (i.e. must it be consumed to be called, like `FnOnce`, or can it be called by-ref), and the captured upvars of the closure itself.
#### The signature
A traditional closure has a `fn_sig_as_fn_ptr_ty` which it uses to represent the signature of the closure.
In contrast, we store the signature of a coroutine closure in a somewhat "exploded" way, since coroutine-closures have *two* signatures depending on what `AsyncFn*` trait you call it with (see below sections).
Conceptually, the coroutine-closure may be thought as containing several different signature types depending on whether it is being called by-ref or by-move.
To conveniently recreate both of these signatures, the `signature_parts_ty` stores all of the relevant parts of the coroutine returned by this coroutine-closure.
This signature parts type will have the general shape of `fn(tupled_inputs, resume_ty) -> (return_ty, yield_ty)`, where `resume_ty`, `return_ty`, and `yield_ty` are the respective types for the *coroutine* returned by the coroutine-closure[^c1].
[^c1]:
The compiler mainly deals with the `CoroutineClosureSignature` type[^c2], which is created by extracting the relevant types out of the `fn()` ptr type described above, and which exposes methods that can be used to construct the *coroutine* that the coroutine-closure ultimately returns.
[^c2]:
#### The data we need to carry along to construct a `Coroutine` return type
Along with the data stored in the signature, to construct a `TyKind::Coroutine` to return, we also need to store the "witness" of the coroutine.
So what about the upvars of the `Coroutine` that is returned? Well, for `AsyncFnOnce` (i.e. call-by-move), this is simply the same upvars that the coroutine returns. But for `AsyncFnMut`/`AsyncFn`, the coroutine that is returned from the coroutine-closure borrows data from the coroutine-closure with a given "environment" lifetime[^c3]. This corresponds to the `&self` lifetime[^c4] on the `AsyncFnMut`/`AsyncFn` call signature, and the GAT lifetime of the `ByRef`[^c5].
[^c3]:
[^c4]:
[^c5]:
#### Actually getting the coroutine return type(s)
To most easily construct the `Coroutine` that a coroutine-closure returns, you can use the `to_coroutine_given_kind_and_upvars`[^helper] helper on `CoroutineClosureSignature`, which can be acquired from the `CoroutineClosureArgs`.
[^helper]:
Most of the args to that function will be components that you can get out of the `CoroutineArgs`, except for the `goal_kind: ClosureKind` which controls which flavor of coroutine to return based off of the `ClosureKind` passed in -- i.e. it will prepare the by-ref coroutine if `ClosureKind::Fn | ClosureKind::FnMut`, and the by-move coroutine if `ClosureKind::FnOnce`.
### Trait hierarchy
We introduce a parallel hierarchy of `Fn*` traits that are implemented for .
The motivation for the introduction was covered in a blog post: [Async Closures](https://hackmd.io/@compiler-errors/async-closures).
All currently-stable callable types (i.e., closures, function items, function pointers, and `dyn Fn*` trait objects) automatically implement `AsyncFn*() -> T` if they implement `Fn*() -> Fut` for some output type `Fut`, and `Fut` implements `Future