Merge pull request #2562 from ali90h/rustdoc-ci-frontends-note
Document rustdoc frontend CI checks
diff --git a/rust-version b/rust-version
index f412399..0dc9ce8 100644
--- a/rust-version
+++ b/rust-version
@@ -1 +1 @@
-a1dbb443527bd126452875eb5d5860c1d001d761
+9f32ccf35fb877270bc44a86a126440f04d676d0
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index a161273..2491409 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -108,6 +108,7 @@
- [Installation](./autodiff/installation.md)
- [How to debug](./autodiff/debugging.md)
- [Autodiff flags](./autodiff/flags.md)
+ - [Type Trees](./autodiff/type-trees.md)
# Source Code Representation
diff --git a/src/about-this-guide.md b/src/about-this-guide.md
index f395772..4f5733a 100644
--- a/src/about-this-guide.md
+++ b/src/about-this-guide.md
@@ -48,9 +48,9 @@
that are not fully realized yet.
All this makes keeping this guide completely up to date on everything very hard!
-The Guide itself is of course open-source as well,
-and the sources can be found at the [GitHub repository].
-If you find any mistakes in the guide, please file an issue about it.
+The guide itself is of course open source as well,
+and the sources are hosted on [a GitHub repository].
+If you find any mistakes in the guide, please file an issue.
Even better, open a PR with a correction!
If you do contribute to the guide,
@@ -73,7 +73,7 @@
- [compiler-team] -- the home-base for the Rust compiler team, with description
of the team procedures, active working groups, and the team calendar.
- [std-dev-guide] -- a similar guide for developing the standard library.
-- [The t-compiler zulip][z]
+- [The t-compiler Zulip][z]
- The [Rust Internals forum][rif], a place to ask questions and
discuss Rust's internals
- The [Rust reference][rr], even though it doesn't specifically talk about
@@ -105,7 +105,7 @@
[cheatsheet]: https://bors.rust-lang.org/
[Miri]: https://github.com/rust-lang/miri
[@bors]: https://github.com/bors
-[GitHub repository]: https://github.com/rust-lang/rustc-dev-guide/
+[a GitHub repository]: https://github.com/rust-lang/rustc-dev-guide/
[rustc API docs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle
[Forge]: https://forge.rust-lang.org/
[compiler-team]: https://github.com/rust-lang/compiler-team/
diff --git a/src/appendix/code-index.md b/src/appendix/code-index.md
index 65fbf75..4ddb58b 100644
--- a/src/appendix/code-index.md
+++ b/src/appendix/code-index.md
@@ -13,7 +13,7 @@
`DefId` | struct | One of four types of HIR node identifiers | [Identifiers in the HIR] | [compiler/rustc_hir/src/def_id.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/struct.DefId.html)
`Diag` | struct | A struct for a compiler diagnostic, such as an error or lint | [Emitting Diagnostics] | [compiler/rustc_errors/src/diagnostic.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/struct.Diag.html)
`DocContext` | struct | A state container used by rustdoc when crawling through a crate to gather its documentation | [Rustdoc] | [src/librustdoc/core.rs](https://github.com/rust-lang/rust/blob/master/src/librustdoc/core.rs)
-`HirId` | struct | One of four types of HIR node identifiers | [Identifiers in the HIR] | [compiler/rustc_hir/src/hir_id.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/hir_id/struct.HirId.html)
+`HirId` | struct | One of four types of HIR node identifiers | [Identifiers in the HIR] | [compiler/rustc_hir_id/src/lib.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/struct.HirId.html)
`Lexer` | struct | This is the lexer used during parsing. It consumes characters from the raw source code being compiled and produces a series of tokens for use by the rest of the parser | [The parser] | [compiler/rustc_parse/src/lexer/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_parse/lexer/struct.Lexer.html)
`NodeId` | struct | One of four types of HIR node identifiers. Being phased out | [Identifiers in the HIR] | [compiler/rustc_ast/src/ast.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/node_id/struct.NodeId.html)
`P` | struct | An owned immutable smart pointer. By contrast, `&T` is not owned, and `Box<T>` is not immutable. | None | [compiler/rustc_ast/src/ptr.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast/ptr/struct.P.html)
diff --git a/src/appendix/glossary.md b/src/appendix/glossary.md
index 1837b59..21162f8 100644
--- a/src/appendix/glossary.md
+++ b/src/appendix/glossary.md
@@ -68,6 +68,7 @@
<span id="rib">rib</span> | A data structure in the name resolver that keeps track of a single scope for names. ([see more](../name-resolution.md))
<span id="rpit">RPIT</span> | A return-position `impl Trait`. ([see the reference](https://doc.rust-lang.org/reference/types/impl-trait.html#abstract-return-types)).
<span id="rpitit">RPITIT</span> | A return-position `impl Trait` in trait. Unlike RPIT, this is desugared to a generic associated type (GAT). Introduced in [RFC 3425](https://rust-lang.github.io/rfcs/3425-return-position-impl-trait-in-traits.html). ([see more](../return-position-impl-trait-in-trait.md))
+<span id="rustbuild">rustbuild</span> | A deprecated term for the part of bootstrap that is written in Rust
<span id="scrutinee">scrutinee</span> | A scrutinee is the expression that is matched on in `match` expressions and similar pattern matching constructs. For example, in `match x { A => 1, B => 2 }`, the expression `x` is the scrutinee.
<span id="sess">`sess`</span> | The compiler _session_, which stores global data used throughout compilation
<span id="side-tables">side tables</span> | Because the [AST](#ast) and HIR are immutable once created, we often carry extra information about them in the form of hashtables, indexed by the id of a particular node.
diff --git a/src/autodiff/type-trees.md b/src/autodiff/type-trees.md
new file mode 100644
index 0000000..68cb786
--- /dev/null
+++ b/src/autodiff/type-trees.md
@@ -0,0 +1,193 @@
+# TypeTrees for Autodiff
+
+## What are TypeTrees?
+Memory layout descriptors for Enzyme. Tell Enzyme exactly how types are structured in memory so it can compute derivatives efficiently.
+
+## Structure
+```rust
+TypeTree(Vec<Type>)
+
+Type {
+ offset: isize, // byte offset (-1 = everywhere)
+ size: usize, // size in bytes
+ kind: Kind, // Float, Integer, Pointer, etc.
+ child: TypeTree // nested structure
+}
+```
+
+## Example: `fn compute(x: &f32, data: &[f32]) -> f32`
+
+**Input 0: `x: &f32`**
+```rust
+TypeTree(vec![Type {
+ offset: -1, size: 8, kind: Pointer,
+ child: TypeTree(vec![Type {
+ offset: 0, size: 4, kind: Float, // Single value: use offset 0
+ child: TypeTree::new()
+ }])
+}])
+```
+
+**Input 1: `data: &[f32]`**
+```rust
+TypeTree(vec![Type {
+ offset: -1, size: 8, kind: Pointer,
+ child: TypeTree(vec![Type {
+ offset: -1, size: 4, kind: Float, // -1 = all elements
+ child: TypeTree::new()
+ }])
+}])
+```
+
+**Output: `f32`**
+```rust
+TypeTree(vec![Type {
+ offset: 0, size: 4, kind: Float, // Single scalar: use offset 0
+ child: TypeTree::new()
+}])
+```
+
+## Why Needed?
+- Enzyme can't deduce complex type layouts from LLVM IR
+- Prevents slow memory pattern analysis
+- Enables correct derivative computation for nested structures
+- Tells Enzyme which bytes are differentiable vs metadata
+
+## What Enzyme Does With This Information:
+
+Without TypeTrees:
+```llvm
+; Enzyme sees generic LLVM IR:
+define float @distance(ptr %p1, ptr %p2) {
+; Has to guess what these pointers point to
+; Slow analysis of all memory operations
+; May miss optimization opportunities
+}
+```
+
+With TypeTrees:
+```llvm
+define "enzyme_type"="{[-1]:Float@float}" float @distance(
+ ptr "enzyme_type"="{[-1]:Pointer, [-1,0]:Float@float}" %p1,
+ ptr "enzyme_type"="{[-1]:Pointer, [-1,0]:Float@float}" %p2
+) {
+; Enzyme knows exact type layout
+; Can generate efficient derivative code directly
+}
+```
+
+# TypeTrees - Offset and -1 Explained
+
+## Type Structure
+
+```rust
+Type {
+ offset: isize, // WHERE this type starts
+ size: usize, // HOW BIG this type is
+ kind: Kind, // WHAT KIND of data (Float, Int, Pointer)
+ child: TypeTree // WHAT'S INSIDE (for pointers/containers)
+}
+```
+
+## Offset Values
+
+### Regular Offset (0, 4, 8, etc.)
+**Specific byte position within a structure**
+
+```rust
+struct Point {
+ x: f32, // offset 0, size 4
+ y: f32, // offset 4, size 4
+ id: i32, // offset 8, size 4
+}
+```
+
+TypeTree for `&Point` (internal representation):
+```rust
+TypeTree(vec![
+ Type { offset: 0, size: 4, kind: Float }, // x at byte 0
+ Type { offset: 4, size: 4, kind: Float }, // y at byte 4
+ Type { offset: 8, size: 4, kind: Integer } // id at byte 8
+])
+```
+
+Generates LLVM
+```llvm
+"enzyme_type"="{[-1]:Pointer, [-1,0]:Float@float, [-1,4]:Float@float, [-1,8]:Integer, [-1,9]:Integer, [-1,10]:Integer, [-1,11]:Integer}"
+```
+
+### Offset -1 (Special: "Everywhere")
+**Means "this pattern repeats for ALL elements"**
+
+#### Example 1: Direct Array `[f32; 100]` (no pointer indirection)
+```rust
+TypeTree(vec![Type {
+ offset: -1, // ALL positions
+ size: 4, // each f32 is 4 bytes
+ kind: Float, // every element is float
+}])
+```
+
+Generates LLVM: `"enzyme_type"="{[-1]:Float@float}"`
+
+#### Example 1b: Array Reference `&[f32; 100]` (with pointer indirection)
+```rust
+TypeTree(vec![Type {
+ offset: -1, size: 8, kind: Pointer,
+ child: TypeTree(vec![Type {
+ offset: -1, // ALL array elements
+ size: 4, // each f32 is 4 bytes
+ kind: Float, // every element is float
+ }])
+}])
+```
+
+Generates LLVM: `"enzyme_type"="{[-1]:Pointer, [-1,-1]:Float@float}"`
+
+Instead of listing 100 separate Types with offsets `0,4,8,12...396`
+
+#### Example 2: Slice `&[i32]`
+```rust
+// Pointer to slice data
+TypeTree(vec![Type {
+ offset: -1, size: 8, kind: Pointer,
+ child: TypeTree(vec![Type {
+ offset: -1, // ALL slice elements
+ size: 4, // each i32 is 4 bytes
+ kind: Integer
+ }])
+}])
+```
+
+Generates LLVM: `"enzyme_type"="{[-1]:Pointer, [-1,-1]:Integer}"`
+
+#### Example 3: Mixed Structure
+```rust
+struct Container {
+ header: i64, // offset 0
+ data: [f32; 1000], // offset 8, but elements use -1
+}
+```
+
+```rust
+TypeTree(vec![
+ Type { offset: 0, size: 8, kind: Integer }, // header
+ Type { offset: 8, size: 4000, kind: Pointer,
+ child: TypeTree(vec![Type {
+ offset: -1, size: 4, kind: Float // ALL array elements
+ }])
+ }
+])
+```
+
+## Key Distinction: Single Values vs Arrays
+
+**Single Values** use offset `0` for precision:
+- `&f32` has exactly one f32 value at offset 0
+- More precise than using -1 ("everywhere")
+- Generates: `{[-1]:Pointer, [-1,0]:Float@float}`
+
+**Arrays** use offset `-1` for efficiency:
+- `&[f32; 100]` has the same pattern repeated 100 times
+- Using -1 avoids listing 100 separate offsets
+- Generates: `{[-1]:Pointer, [-1,-1]:Float@float}`
\ No newline at end of file
diff --git a/src/backend/debugging.md b/src/backend/debugging.md
index 4f8712d..3dc95f2 100644
--- a/src/backend/debugging.md
+++ b/src/backend/debugging.md
@@ -183,7 +183,7 @@
### Getting help and asking questions
If you have some questions, head over to the [rust-lang Zulip] and
-specifically the `#t-compiler/wg-llvm` stream.
+specifically the `#t-compiler/wg-llvm` channel.
[rust-lang Zulip]: https://rust-lang.zulipchat.com/
diff --git a/src/backend/updating-llvm.md b/src/backend/updating-llvm.md
index a4e22b7..ebef15d 100644
--- a/src/backend/updating-llvm.md
+++ b/src/backend/updating-llvm.md
@@ -1,6 +1,6 @@
# Updating LLVM
-<!-- date-check: Aug 2025 -->
+<!-- date-check: Aug 2024 -->
Rust supports building against multiple LLVM versions:
* Tip-of-tree for the current LLVM development branch is usually supported
@@ -93,7 +93,7 @@
## New LLVM Release Updates
-<!-- date-check: Aug 2025 -->
+<!-- date-check: Jul 2023 -->
Unlike bugfixes,
updating to a new release of LLVM typically requires a lot more work.
diff --git a/src/borrow_check/region_inference/member_constraints.md b/src/borrow_check/region_inference/member_constraints.md
index 52e7400..2804c97 100644
--- a/src/borrow_check/region_inference/member_constraints.md
+++ b/src/borrow_check/region_inference/member_constraints.md
@@ -92,7 +92,7 @@
## Choices are always lifetime parameters
At present, the "choice" regions from a member constraint are always lifetime
-parameters from the current function. As of <!-- date-check --> August 2025,
+parameters from the current function. As of <!-- date-check --> October 2021,
this falls out from the placement of impl Trait, though in the future it may not
be the case. We take some advantage of this fact, as it simplifies the current
code. In particular, we don't have to consider a case like `'0 member of ['1,
diff --git a/src/building/bootstrapping/writing-tools-in-bootstrap.md b/src/building/bootstrapping/writing-tools-in-bootstrap.md
index 41d0cf8..8ac2e6b 100644
--- a/src/building/bootstrapping/writing-tools-in-bootstrap.md
+++ b/src/building/bootstrapping/writing-tools-in-bootstrap.md
@@ -3,21 +3,32 @@
There are three types of tools you can write in bootstrap:
- **`Mode::ToolBootstrap`**
+
Use this for tools that don’t need anything from the in-tree compiler and can run with the stage0 `rustc`.
- The output is placed in the "bootstrap-tools" directory. This mode is for general-purpose tools built
- entirely with the stage0 compiler, including target libraries and only works for stage 0.
+ The output is placed in the "bootstrap-tools" directory.
+ This mode is for general-purpose tools built entirely with the stage0 compiler,
+ including target libraries, and it only works for stage 0.
- **`Mode::ToolStd`**
- Use this for tools that rely on the locally built std. The output goes into the "stageN-tools" directory.
+
+ Use this for tools that rely on the locally built std.
+ The output goes into the "stageN-tools" directory.
This mode is rarely used, mainly for `compiletest` which requires `libtest`.
-- **`Mode::ToolRustc`**
- Use this for tools that depend on both the locally built `rustc` and the target `std`. This is more complex than
- the other modes because the tool must be built with the same compiler used for `rustc` and placed in the "stageN-tools"
- directory. When you choose `Mode::ToolRustc`, `ToolBuild` implementation takes care of this automatically.
- If you need to use the builder’s compiler for something specific, you can get it from `ToolBuildResult`, which is
- returned by the tool's [`Step`].
+- **`Mode::ToolRustcPrivate`**
-Regardless of the tool type you must return `ToolBuildResult` from the tool’s [`Step`] implementation and use `ToolBuild` inside it.
+ Use this for tools that use the `rustc_private` mechanism,
+ and thus depend on the locally built `rustc` and its rlib artifacts.
+ This is more complex than the other modes,
+ because the tool must be built with the same compiler used for `rustc`,
+ and placed in the "stageN-tools" directory.
+ When you choose `Mode::ToolRustcPrivate`,
+ `ToolBuild` implementation takes care of this automatically.
+ If you need to use the builder’s compiler for something specific,
+ you can get it from `ToolBuildResult`, which is returned by the tool's [`Step`].
+
+Regardless of the tool type,
+you must return `ToolBuildResult` from the tool’s [`Step`] implementation,
+and use `ToolBuild` inside it.
[`Step`]: https://doc.rust-lang.org/nightly/nightly-rustc/bootstrap/core/builder/trait.Step.html
diff --git a/src/building/how-to-build-and-run.md b/src/building/how-to-build-and-run.md
index b07d353..36610f2 100644
--- a/src/building/how-to-build-and-run.md
+++ b/src/building/how-to-build-and-run.md
@@ -149,7 +149,7 @@
```
PS C:\Users\vboxuser\rust> ./x
./x : File C:\Users\vboxuser\rust\x.ps1 cannot be loaded because running scripts is disabled on this system. For more
-information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
+information, see about_Execution_Policies at https://go.microsoft.com/fwlink/?LinkID=135170.
At line:1 char:1
+ ./x
+ ~~~
diff --git a/src/compiler-debugging.md b/src/compiler-debugging.md
index edd2aa6..f451447 100644
--- a/src/compiler-debugging.md
+++ b/src/compiler-debugging.md
@@ -367,7 +367,7 @@
error: aborting due to previous error
```
-[`Layout`]: https://doc.rust-lang.org/nightly/nightly-rustc/stable_mir/abi/struct.Layout.html
+[`Layout`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_public/abi/struct.Layout.html
## Configuring CodeLLDB for debugging `rustc`
diff --git a/src/compiler-src.md b/src/compiler-src.md
index d67bacb..27b40f1 100644
--- a/src/compiler-src.md
+++ b/src/compiler-src.md
@@ -153,7 +153,8 @@
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`].
+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].
@@ -162,6 +163,7 @@
[`src/tools/rustdoc-js`]: https://github.com/rust-lang/rust/tree/master/src/tools/rustdoc-js
[`src/tools/rustdoc-themes`]: https://github.com/rust-lang/rust/tree/master/src/tools/rustdoc-themes
[`src/tools/rustdoc`]: https://github.com/rust-lang/rust/tree/master/src/tools/rustdoc
+[`src/rustdoc-json-types`]: https://github.com/rust-lang/rust/tree/master/src/rustdoc-json-types
[rustdoc-chapter]: ./rustdoc.md
## Tests
diff --git a/src/compiler-team.md b/src/compiler-team.md
index 9922ee7..8c0481f 100644
--- a/src/compiler-team.md
+++ b/src/compiler-team.md
@@ -1,10 +1,14 @@
# 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
@@ -12,7 +16,7 @@
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 streams,
+- 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.
@@ -130,12 +134,3 @@
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.
-
-### Full team membership
-
-Full team membership is typically extended once someone made many
-contributions to the Rust compiler over time, ideally (but not
-necessarily) to multiple areas. Sometimes this might be implementing a
-new feature, but it is also important — perhaps more important! — to
-have time and willingness to help out with general upkeep such as
-bugfixes, tracking regressions, and other less glamorous work.
diff --git a/src/contributing.md b/src/contributing.md
index 1ade495..3d196ae 100644
--- a/src/contributing.md
+++ b/src/contributing.md
@@ -26,8 +26,7 @@
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](https://github.com/rust-lang/rust/issues/new/choose) and filling out the fields
+Opening an issue is as easy as following [thi link][create an issue] and filling out the fields
in the appropriate provided template.
## Bug fixes or "normal" code changes
@@ -75,7 +74,7 @@
to important types, or important changes to how the compiler does something, or
smaller user-facing changes.
-**When in doubt, ask on [zulip]. It would be a shame to put a lot of work
+**When in doubt, ask on [Zulip]. It would be a shame to put a lot of work
into a PR that ends up not getting merged!** [See this document][mcpinfo] for
more info on MCPs.
@@ -127,7 +126,7 @@
> from), and work with the compiler team to see if we can help you **break down a large potentially
> unreviewable PR into a series of smaller more individually reviewable PRs**.
>
-> You can communicate with the compiler team by creating a [#t-compiler thread on zulip][t-compiler]
+> You can communicate with the compiler team by creating a [#t-compiler thread on Zulip][t-compiler]
> to discuss your proposed changes.
>
> Communicating with the compiler team beforehand helps in several ways:
@@ -154,9 +153,14 @@
not against the commit your branch is based on. This can lead to unexpected failures
if your branch is outdated, even when there are no explicit merge conflicts.
-Update your branch only when needed: when you have merge conflicts, upstream CI is broken and blocking your green PR, or a maintainer requests it. Avoid updating an already-green PR under review unless necessary. During review, make incremental commits to address feedback. Prefer to squash or rebase only at the end, or when a reviewer requests it.
+Update your branch only when needed: when you have merge conflicts, upstream CI is broken and blocking your green PR, or a maintainer requests it.
+Avoid updating an already-green PR under review unless necessary.
+During review, make incremental commits to address feedback.
+Prefer to squash or rebase only at the end, or when a reviewer requests it.
-When updating, use `git push --force-with-lease` and leave a brief comment explaining what changed. Some repos prefer merging from `upstream/master` instead of rebasing; follow the project's conventions. See [keeping things up to date](git.md#keeping-things-up-to-date) for detailed instructions.
+When updating, use `git push --force-with-lease` and leave a brief comment explaining what changed.
+Some repos prefer merging from `upstream/master` instead of rebasing; follow the project's conventions.
+See [keeping things up to date](git.md#keeping-things-up-to-date) for detailed instructions.
After rebasing, it's recommended to [run the relevant tests locally](tests/intro.md) to catch any issues before CI runs.
@@ -370,8 +374,10 @@
`rustdoc src/doc/reference.md` will render reference to `doc/reference.html`.
The CSS might be messed up, but you can verify that the HTML is right.
-Please notice that at this time we don't accept typography/spellcheck fixes to **internal documentation** (example:
-tests, library or compiler code) as it's usually not worth the churn or the review time.
+Please notice that we don't accept typography/spellcheck fixes to **internal documentation**
+as it's usually not worth the churn or the review time.
+Examples of internal documentation is code comments and rustc api docs.
+However, feel free to fix those if accompanied by other improvements in the same PR.
### Contributing to rustc-dev-guide
@@ -435,7 +441,8 @@
#### ⚠️ 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 working group documentation](https://forge.rust-lang.org/wg-rustc-dev-guide/index.html#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 working group documentation].
## Issue triage
@@ -452,6 +459,7 @@
[regression-]: https://github.com/rust-lang/rust/labels?q=regression
[relnotes]: https://github.com/rust-lang/rust/labels/relnotes
[S-tracking-]: https://github.com/rust-lang/rust/labels?q=s-tracking
+[the rustc-dev-guide working group documentation]: https://forge.rust-lang.org/wg-rustc-dev-guide/index.html#where-to-contribute-rustc-dev-guide-changes
### Rfcbot labels
@@ -499,3 +507,4 @@
[RFC 1574]: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text
[rustc-dev-guide]: https://rustc-dev-guide.rust-lang.org/
[rdgrepo]: https://github.com/rust-lang/rustc-dev-guide
+[create an issue]: https://github.com/rust-lang/rust/issues/new/choose
diff --git a/src/diagnostics/diagnostic-items.md b/src/diagnostics/diagnostic-items.md
index 4000cbd..9360427 100644
--- a/src/diagnostics/diagnostic-items.md
+++ b/src/diagnostics/diagnostic-items.md
@@ -48,7 +48,7 @@
For the naming conventions of diagnostic items, please refer to
[*Naming Conventions*](#naming-conventions).
-2. <!-- date-check: Aug 2025 -->
+2. <!-- date-check: Feb 2023 -->
Diagnostic items in code are accessed via symbols in
[`rustc_span::symbol::sym`].
To add your newly-created diagnostic item,
diff --git a/src/diagnostics/error-codes.md b/src/diagnostics/error-codes.md
index 98d9a7a..1693432 100644
--- a/src/diagnostics/error-codes.md
+++ b/src/diagnostics/error-codes.md
@@ -10,7 +10,7 @@
The explanations are written in Markdown (see the [CommonMark Spec] for
specifics around syntax), and all of them are linked in the [`rustc_error_codes`]
crate. Please read [RFC 1567] for details on how to format and write long error
-codes. As of <!-- date-check --> August 2025, there is an
+codes. As of <!-- date-check --> February 2023, there is an
effort[^new-explanations] to replace this largely outdated RFC with a new more
flexible standard.
diff --git a/src/diagnostics/lintstore.md b/src/diagnostics/lintstore.md
index f0d349c..7b98bc6 100644
--- a/src/diagnostics/lintstore.md
+++ b/src/diagnostics/lintstore.md
@@ -21,7 +21,7 @@
as the macro is somewhat unwieldy to add new fields to,
like all macros).
-As of <!-- date-check --> Aug 2025,
+As of <!-- date-check --> Aug 2022,
we lint against direct declarations without the use of the macro.
Lint declarations don't carry any "state" - they are merely global identifiers
diff --git a/src/diagnostics/translation.md b/src/diagnostics/translation.md
index 5d143da..58d75f5 100644
--- a/src/diagnostics/translation.md
+++ b/src/diagnostics/translation.md
@@ -2,12 +2,12 @@
<div class="warning">
rustc's current diagnostics translation infrastructure (as of
-<!-- date-check --> August 2025
+<!-- date-check --> October 2024
) unfortunately causes some friction for compiler contributors, and the current
infrastructure is mostly pending a redesign that better addresses needs of both
compiler contributors and translation teams. Note that there is no current
active redesign proposals (as of
-<!-- date-check --> August 2025
+<!-- date-check --> October 2024
)!
Please see the tracking issue <https://github.com/rust-lang/rust/issues/132181>
diff --git a/src/fuzzing.md b/src/fuzzing.md
index 540a8c6..cc98b49 100644
--- a/src/fuzzing.md
+++ b/src/fuzzing.md
@@ -1,6 +1,6 @@
# Fuzzing
-<!-- date-check: Aug 2025 -->
+<!-- date-check: Mar 2023 -->
For the purposes of this guide, *fuzzing* is any testing methodology that
involves compiling a wide variety of programs in an attempt to uncover bugs in
@@ -90,14 +90,15 @@
triggering the ICE, such as syntax errors or borrow-checking errors
- Minimize the test case (see below). If successful, you can label the
issue with `S-has-mcve`. Otherwise, you can apply `E-needs-mcve`.
-- Add the minimal test case to the rust-lang/rust repo as a [crashes test].
+- Add the minimal test case to the rust-lang/rust repo as a [crash test].
While you're at it, consider including other "untracked" crashes in your PR.
- Please don't forget to mark your issue with `S-bug-has-test` afterwards.
+ Please don't forget to mark all relevant issues with `S-bug-has-test` once
+ your PR is merged.
See also [applying and removing labels][labeling].
[bisect]: https://rust-lang.github.io/cargo-bisect-rustc/
-[crashes test]: tests/compiletest.html#crashes-tests
+[crash test]: tests/compiletest.html#crash-tests
[labeling]: https://forge.rust-lang.org/release/issue-triaging.html#applying-and-removing-labels
## Minimization
diff --git a/src/hir.md b/src/hir.md
index 38ba331..0b341a4 100644
--- a/src/hir.md
+++ b/src/hir.md
@@ -102,7 +102,7 @@
[`DefId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/struct.DefId.html
[`LocalDefId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/struct.LocalDefId.html
-[`HirId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/hir_id/struct.HirId.html
+[`HirId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/struct.HirId.html
[`BodyId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/hir/struct.BodyId.html
[Node]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/hir/enum.Node.html
[`CrateNum`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/struct.CrateNum.html
diff --git a/src/notification-groups/arm.md b/src/notification-groups/arm.md
index 3abc32c..5b79030 100644
--- a/src/notification-groups/arm.md
+++ b/src/notification-groups/arm.md
@@ -9,7 +9,7 @@
ARM-related issues as well as suggestions on how to resolve
interesting questions regarding our ARM support.
-The group also has an associated Zulip stream ([`#t-compiler/arm`])
+The group also has an associated Zulip channel ([`#t-compiler/arm`])
where people can go to pose questions and discuss ARM-specific
topics.
diff --git a/src/notification-groups/emscripten.md b/src/notification-groups/emscripten.md
index 100dbdf..9e4086c 100644
--- a/src/notification-groups/emscripten.md
+++ b/src/notification-groups/emscripten.md
@@ -9,7 +9,7 @@
Emscripten-related issues as well as suggestions on how to resolve
interesting questions regarding our Emscripten support.
-The group also has an associated Zulip stream ([`#t-compiler/wasm`])
+The group also has an associated Zulip channel ([`#t-compiler/wasm`])
where people can go to pose questions and discuss Emscripten-specific
topics.
diff --git a/src/notification-groups/risc-v.md b/src/notification-groups/risc-v.md
index 1b31297..7c8a3cd 100644
--- a/src/notification-groups/risc-v.md
+++ b/src/notification-groups/risc-v.md
@@ -9,7 +9,7 @@
RISC-V-related issues as well as suggestions on how to resolve
interesting questions regarding our RISC-V support.
-The group also has an associated Zulip stream ([`#t-compiler/risc-v`])
+The group also has an associated Zulip channel ([`#t-compiler/risc-v`])
where people can go to pose questions and discuss RISC-V-specific
topics.
diff --git a/src/notification-groups/rust-for-linux.md b/src/notification-groups/rust-for-linux.md
index 696f203..ed1de91 100644
--- a/src/notification-groups/rust-for-linux.md
+++ b/src/notification-groups/rust-for-linux.md
@@ -12,7 +12,7 @@
for resolving the breakage or decide to temporarily accept the breakage
and unblock CI by temporarily removing the RfL CI jobs.
-The group also has an associated Zulip stream ([`#rust-for-linux`])
+The group also has an associated Zulip channel ([`#rust-for-linux`])
where people can go to ask questions and discuss topics related to Rust
for Linux.
diff --git a/src/notification-groups/wasi.md b/src/notification-groups/wasi.md
index e438ee4..88b9465 100644
--- a/src/notification-groups/wasi.md
+++ b/src/notification-groups/wasi.md
@@ -9,7 +9,7 @@
WASI-related issues as well as suggestions on how to resolve
interesting questions regarding our WASI support.
-The group also has an associated Zulip stream ([`#t-compiler/wasm`])
+The group also has an associated Zulip channel ([`#t-compiler/wasm`])
where people can go to pose questions and discuss WASI-specific
topics.
diff --git a/src/notification-groups/wasm.md b/src/notification-groups/wasm.md
index c8b674c..6f52b04 100644
--- a/src/notification-groups/wasm.md
+++ b/src/notification-groups/wasm.md
@@ -9,7 +9,7 @@
WebAssembly-related issues as well as suggestions on how to resolve
interesting questions regarding our WASM support.
-The group also has an associated Zulip stream ([`#t-compiler/wasm`])
+The group also has an associated Zulip channel ([`#t-compiler/wasm`])
where people can go to pose questions and discuss WASM-specific
topics.
diff --git a/src/notification-groups/windows.md b/src/notification-groups/windows.md
index e615a2c..d245208 100644
--- a/src/notification-groups/windows.md
+++ b/src/notification-groups/windows.md
@@ -9,7 +9,7 @@
Windows-related issues as well as suggestions on how to resolve
interesting questions regarding our Windows support.
-The group also has an associated Zulip stream ([`#t-compiler/windows`])
+The group also has an associated Zulip channel ([`#t-compiler/windows`])
where people can go to pose questions and discuss Windows-specific
topics.
diff --git a/src/opaque-types-type-alias-impl-trait.md b/src/opaque-types-type-alias-impl-trait.md
index 5a4a31e..956f568 100644
--- a/src/opaque-types-type-alias-impl-trait.md
+++ b/src/opaque-types-type-alias-impl-trait.md
@@ -15,7 +15,7 @@
but nothing else (regardless of whether it implements any other traits).
Since there needs to be a concrete background type,
-you can (as of <!-- date-check --> August 2025) express that type
+you can (as of <!-- date-check --> January 2021) express that type
by using the opaque type in a "defining use site".
```rust,ignore
diff --git a/src/overview.md b/src/overview.md
index 9f02019..378d8c4 100644
--- a/src/overview.md
+++ b/src/overview.md
@@ -304,7 +304,7 @@
system has been retrofitted into the compiler, so parts of it are not query-fied
yet. Also, LLVM isn't our code, so that isn't querified either. The plan is to
eventually query-fy all of the steps listed in the previous section,
-but as of <!-- date-check --> August 2025, only the steps between `HIR` and
+but as of <!-- date-check --> November 2022, only the steps between `HIR` and
`LLVM-IR` are query-fied. That is, lexing, parsing, name resolution, and macro
expansion are done all at once for the whole program.
diff --git a/src/parallel-rustc.md b/src/parallel-rustc.md
index b448243..ce69b66 100644
--- a/src/parallel-rustc.md
+++ b/src/parallel-rustc.md
@@ -1,14 +1,14 @@
# Parallel compilation
<div class="warning">
-As of <!-- date-check --> August 2025,
+As of <!-- date-check --> November 2024,
the parallel front-end is undergoing significant changes,
so this page contains quite a bit of outdated information.
Tracking issue: <https://github.com/rust-lang/rust/issues/113349>
</div>
-As of <!-- date-check --> August 2025, most of the rust compiler is now
+As of <!-- date-check --> November 2024, most of the rust compiler is now
parallelized.
- The codegen part is executed concurrently by default. You can use the `-C
@@ -104,7 +104,7 @@
| **ModuleItems::par_foreign_items**(&self, f: impl Fn(ForeignItemId)) | run `f` on all foreign items in the module | rustc_middle::hir |
There are a lot of loops in the compiler which can possibly be parallelized
-using these functions. As of <!-- date-check--> August 2025, scenarios where
+using these functions. As of <!-- date-check--> August 2022, scenarios where
the parallel iterator function has been used are as follows:
| caller | scenario | callee |
@@ -155,7 +155,7 @@
## Rustdoc
-As of <!-- date-check--> August 2025, there are still a number of steps to
+As of <!-- date-check--> November 2022, there are still a number of steps to
complete before `rustdoc` rendering can be made parallel (see a open discussion
of [parallel `rustdoc`][parallel-rustdoc]).
diff --git a/src/profiling.md b/src/profiling.md
index 7dfd74a..de06bd7 100644
--- a/src/profiling.md
+++ b/src/profiling.md
@@ -108,6 +108,6 @@
MIR optimizations have little impact. Compared to the default `RUSTFLAGS="-Z
mir-opt-level=1"`, level 0 adds 0.3GB and level 2 removes 0.2GB.
-As of <!-- date-check --> August 2025,
+As of <!-- date-check --> July 2022,
inlining happens in LLVM and GCC codegen backends,
missing only in the Cranelift one.
diff --git a/src/profiling/with_perf.md b/src/profiling/with_perf.md
index 0d4f23b..e452dde 100644
--- a/src/profiling/with_perf.md
+++ b/src/profiling/with_perf.md
@@ -4,8 +4,7 @@
## Initial steps
-- Get a clean checkout of rust-lang/master, or whatever it is you want
- to profile.
+- Get a clean checkout of rust-lang/rust
- Set the following settings in your `bootstrap.toml`:
- `rust.debuginfo-level = 1` - enables line debuginfo
- `rust.jemalloc = false` - lets you do memory use profiling with valgrind
diff --git a/src/queries/query-evaluation-model-in-detail.md b/src/queries/query-evaluation-model-in-detail.md
index f487707..c1a4373 100644
--- a/src/queries/query-evaluation-model-in-detail.md
+++ b/src/queries/query-evaluation-model-in-detail.md
@@ -74,7 +74,7 @@
"input" data, i.e. pieces of immutable data that were computed before the
context was created and that queries can access to do their computations.
-As of <!-- date-check --> August 2025, this input data consists mainly of
+As of <!-- date-check --> January 2021, this input data consists mainly of
the HIR map, upstream crate metadata, and the command-line options the compiler
was invoked with; but in the future inputs will just consist of command-line
options and a list of source files -- the HIR map will itself be provided by a
diff --git a/src/queries/salsa.md b/src/queries/salsa.md
index c0caa20..dc7160e 100644
--- a/src/queries/salsa.md
+++ b/src/queries/salsa.md
@@ -7,7 +7,7 @@
Depth](https://www.youtube.com/watch?v=i_IhACacPRY), also by Niko
Matsakis.
-> As of <!-- date-check --> August 2025, although Salsa is inspired by (among
+> As of <!-- date-check --> November 2022, although Salsa is inspired by (among
> other things) rustc's query system, it is not used directly in rustc. It
> _is_ used in [chalk], an implementation of Rust's trait system, and
> extensively in [`rust-analyzer`], the official implementation of the language
diff --git a/src/query.md b/src/query.md
index 0a92731..8377a7b 100644
--- a/src/query.md
+++ b/src/query.md
@@ -1,7 +1,7 @@
# Queries: demand-driven compilation
As described in [Overview of the compiler], the Rust compiler
-is still (as of <!-- date-check --> August 2025) transitioning from a
+is still (as of <!-- date-check --> July 2021) transitioning from a
traditional "pass-based" setup to a "demand-driven" system. The compiler query
system is the key to rustc's demand-driven organization.
The idea is pretty simple. Instead of entirely independent passes
diff --git a/src/rustdoc-internals.md b/src/rustdoc-internals.md
index 02abce2..4affbaf 100644
--- a/src/rustdoc-internals.md
+++ b/src/rustdoc-internals.md
@@ -99,7 +99,7 @@
`--document-private-items` to `rustdoc`. Note that unlike the previous set of [`AST`][ast]
transformations, the passes are run on the _cleaned_ crate.
-Here is the list of passes as of <!-- date-check --> August 2025:
+Here is the list of passes as of <!-- date-check --> March 2023:
- `calculate-doc-coverage` calculates information used for the `--show-coverage`
flag.
@@ -122,7 +122,7 @@
- `bare_urls` detects links that are not linkified, e.g., in Markdown such as
`Go to https://example.com/.` It suggests wrapping the link with angle brackets:
`Go to <https://example.com/>.` to linkify it. This is the code behind the <!--
- date-check: Aug 2025 --> `rustdoc::bare_urls` `lint`.
+ date-check: may 2022 --> `rustdoc::bare_urls` `lint`.
- `check_code_block_syntax` validates syntax inside Rust code blocks
(<code>```rust</code>)
@@ -212,7 +212,7 @@
a lot of `rustdoc`'s architecture was designed around not doing that, but a
`TyCtxt` is now passed to `formats::renderer::run_format`, which is used to
run generation for both `HTML` and the
-(unstable as of <!-- date-check --> August 2025) JSON format.
+(unstable as of <!-- date-check --> March 2023) JSON format.
This change has allowed other changes to remove data from the "clean" [`AST`][ast]
that can be easily derived from `TyCtxt` queries, and we'll usually accept
diff --git a/src/rustdoc-internals/rustdoc-json-test-suite.md b/src/rustdoc-internals/rustdoc-json-test-suite.md
index e08f770..10e9452 100644
--- a/src/rustdoc-internals/rustdoc-json-test-suite.md
+++ b/src/rustdoc-internals/rustdoc-json-test-suite.md
@@ -1,3 +1,83 @@
# The `rustdoc-json` test suite
-> **FIXME**: This section is a stub. It will be populated by [PR #2422](https://github.com/rust-lang/rustc-dev-guide/pull/2422/).
+This page is specifically about the test suite named `rustdoc-json`, which tests rustdoc's [json output].
+For other test suites used for testing rustdoc, see [§Rustdoc test suites](../tests/compiletest.md#rustdoc-test-suites).
+
+Tests are run with compiletest, and have access to the usual set of [directives](../tests/directives.md).
+Frequenly used directives here are:
+
+- [`//@ aux-build`][aux-build] to have dependencies.
+- `//@ edition: 2021` (or some other edition).
+- `//@ compile-flags: --document-hidden-items` to enable [document private items].
+
+Each crate's json output is checked by 2 programs: [jsondoclint](#jsondocck) and [jsondocck](#jsondocck).
+
+## jsondoclint
+
+[jsondoclint] checks that all [`Id`]s exist in the `index` (or `paths`).
+This makes sure there are no dangling [`Id`]s.
+
+<!-- TODO: It does some more things too?
+Also, talk about how it works
+ -->
+
+## jsondocck
+
+[jsondocck] processes direcives given in comments, to assert that the values in the output are expected.
+It's alot like [htmldocck](./rustdoc-test-suite.md) in that way.
+
+It uses [JSONPath] as a query language, which takes a path, and returns a *list* of values that that path is said to match to.
+
+### Directives
+
+- `//@ has <path>`: Checks `<path>` exists, i.e. matches at least 1 value.
+- `//@ !has <path>`: Checks `<path>` doesn't exist, i.e. matches 0 values.
+- `//@ has <path> <value>`: Check `<path>` exists, and at least 1 of the matches is equal to the given `<value>`
+- `//@ !has <path> <value>`: Checks `<path>` exists, but none of the matches equal the given `<value>`.
+- `//@ is <path> <value>`: Check `<path>` matches exactly one value, and it's equal to the given `<value>`.
+- `//@ is <path> <value> <value>...`: Check that `<path>` matches to exactly every given `<value>`.
+ Ordering doesn't matter here.
+- `//@ !is <path> <value>`: Check `<path>` matches exactly one value, and that value is not equal to the given `<value>`.
+- `//@ count <path> <number>`: Check that `<path>` matches to `<number>` of values.
+- `//@ set <name> = <path>`: Check that `<path>` matches exactly one value, and store that value to the variable called `<name>`.
+
+These are defined in [`directive.rs`].
+
+### Values
+
+Values can be either JSON values, or variables.
+
+- JSON values are JSON literals, e.g. `true`, `"string"`, `{"key": "value"}`.
+ These often need to be quoted using `'`, to be processed as 1 value. See [§Argument spliting](#argument-spliting)
+- Variables can be used to store the value in one path, and use it in later queries.
+ They are set with the `//@ set <name> = <path>` directive, and accessed with `$<name>`
+
+ ```rust
+ //@ set foo = $some.path
+ //@ is $.some.other.path $foo
+ ```
+
+### Argument spliting
+
+Arguments to directives are split using the [shlex] crate, which implements POSIX shell escaping.
+This is because both `<path>` and `<value>` arguments to [directives](#directives) frequently have both
+whitespace and quote marks.
+
+To use the `@ is` with a `<path>` of `$.index[?(@.docs == "foo")].some.field` and a value of `"bar"` [^why_quote], you'd write:
+
+```rust
+//@ is '$.is[?(@.docs == "foo")].some.field' '"bar"'
+```
+
+[^why_quote]: The value needs to be `"bar"` *after* shlex splitting, because we
+ it needs to be a JSON string value.
+
+[json output]: https://doc.rust-lang.org/nightly/rustdoc/unstable-features.html#json-output
+[jsondocck]: https://github.com/rust-lang/rust/tree/master/src/tools/jsondocck
+[jsondoclint]: https://github.com/rust-lang/rust/tree/master/src/tools/jsondoclint
+[aux-build]: ../tests/compiletest.md#building-auxiliary-crates
+[`Id`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc_json_types/struct.Id.html
+[document private items]: https://doc.rust-lang.org/nightly/rustdoc/command-line-arguments.html#--document-private-items-show-items-that-are-not-public
+[`directive.rs`]: https://github.com/rust-lang/rust/blob/master/src/tools/jsondocck/src/directive.rs
+[shlex]: https://docs.rs/shlex/1.3.0/shlex/index.html
+[JSONPath]: https://www.rfc-editor.org/rfc/rfc9535.html
diff --git a/src/rustdoc.md b/src/rustdoc.md
index 4181c2f..b021f58 100644
--- a/src/rustdoc.md
+++ b/src/rustdoc.md
@@ -119,7 +119,7 @@
require type-checking bodies; for example it cannot generate `.rlib` files or run most lints.
We want to move away from this model eventually, but we need some alternative for
[the people using it][async-std]; see [various][zulip stop accepting broken code]
-[previous][rustdoc meeting 2024-07-08] [zulip][compiler meeting 2023-01-26] [discussion][notriddle rfc].
+[previous][rustdoc meeting 2024-07-08] [Zulip][compiler meeting 2023-01-26] [discussion][notriddle rfc].
For examples of code that breaks if this hack is removed, see
[`tests/rustdoc-ui/error-in-impl-trait`].
diff --git a/src/serialization.md b/src/serialization.md
index 8eb37bb..702d3cf 100644
--- a/src/serialization.md
+++ b/src/serialization.md
@@ -106,7 +106,7 @@
[`Encodable`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_serialize/trait.Encodable.html
[`Encoder`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_serialize/trait.Encoder.html
[`RefDecodable`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/codec/trait.RefDecodable.html
-[`rustc_middle`]: https://doc.rust-lang.org/nightly/nightly-rustc/src/rustc_type_ir/codec.rs.html#21
+[`rustc_middle`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/index.html
[`ty::Predicate`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/predicate/struct.Predicate.html
[`TyCtxt`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyCtxt.html
[`TyDecodable`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_macros/derive.TyDecodable.html
diff --git a/src/solve/caching.md b/src/solve/caching.md
index e568d47..cb7403d 100644
--- a/src/solve/caching.md
+++ b/src/solve/caching.md
@@ -106,7 +106,7 @@
[`provisional_result`]: https://github.com/rust-lang/rust/blob/7606c13961ddc1174b70638e934df0439b7dc515/compiler/rustc_trait_selection/src/solve/search_graph.rs#L57
[initial-prov-result]: https://github.com/rust-lang/rust/blob/7606c13961ddc1174b70638e934df0439b7dc515/compiler/rustc_trait_selection/src/solve/search_graph.rs#L366-L370
[fixpoint]: https://github.com/rust-lang/rust/blob/7606c13961ddc1174b70638e934df0439b7dc515/compiler/rustc_trait_selection/src/solve/search_graph.rs#L425-L446
-[^2]: summarizing the relevant [zulip thread]
+[^2]: summarizing the relevant [Zulip thread]
[zulip thread]: https://rust-lang.zulipchat.com/#narrow/stream/364551-t-types.2Ftrait-system-refactor/topic/global.20cache
[unstable-result-ex]: https://github.com/rust-lang/rust/blob/7606c13961ddc1174b70638e934df0439b7dc515/tests/ui/traits/next-solver/cycles/coinduction/incompleteness-unstable-result.rs#L4-L16
diff --git a/src/solve/the-solver.md b/src/solve/the-solver.md
index 006fb64..0e095b5 100644
--- a/src/solve/the-solver.md
+++ b/src/solve/the-solver.md
@@ -71,6 +71,6 @@
## Learning more
The solver should be fairly self-contained. I hope that the above information provides a
-good foundation when looking at the code itself. Please reach out on zulip if you get stuck
+good foundation when looking at the code itself. Please reach out on Zulip if you get stuck
while doing so or there are some quirks and design decisions which were unclear and deserve
better comments or should be mentioned here.
diff --git a/src/stability.md b/src/stability.md
index 665215f..3c4c65f 100644
--- a/src/stability.md
+++ b/src/stability.md
@@ -30,7 +30,7 @@
Previously, due to a [rustc bug], stable items inside unstable modules were
available to stable code in that location.
-As of <!-- date-check --> August 2025, items with [accidentally stabilized
+As of <!-- date-check --> September 2024, items with [accidentally stabilized
paths] are marked with the `#[rustc_allowed_through_unstable_modules]` attribute
to prevent code dependent on those paths from breaking. Do *not* add this attribute
to any more items unless that is needed to avoid breaking changes.
diff --git a/src/tests/adding.md b/src/tests/adding.md
index e5c26be..46b8a1e 100644
--- a/src/tests/adding.md
+++ b/src/tests/adding.md
@@ -29,6 +29,8 @@
suites.
- Need to inspect the resulting binary in some way? Or if all the other test
suites are too limited for your purposes? Then use `run-make`.
+ - Use `run-make-cargo` if you need to exercise in-tree `cargo` in conjunction
+ with in-tree `rustc`.
- Check out the [compiletest] chapter for more specialized test suites.
After deciding on which kind of test to add, see [best
diff --git a/src/tests/best-practices.md b/src/tests/best-practices.md
index be00207..10372c3 100644
--- a/src/tests/best-practices.md
+++ b/src/tests/best-practices.md
@@ -71,7 +71,7 @@
> //! Regression test for <https://github.com/rust-lang/rust/issues/123456>.
> ```
>
-> One exception to this rule is [crashes tests]: there it is canonical that
+> One exception to this rule is [crash tests]: there it is canonical that
> tests are named only after issue numbers because its purpose is to track
> snippets from which issues no longer ICE/crash, and they would either be
> removed or converted into proper ui/other tests in the fix PRs.
@@ -83,10 +83,10 @@
- E.g. for an implementation of RFC 2093 specifically, we can group a
collection of tests under `tests/ui/rfc-2093-infer-outlives/`. For the
directory name, include what the RFC is about.
-- For the [`run-make`] test suite, each `rmake.rs` must be contained within an
- immediate subdirectory under `tests/run-make/`. Further nesting is not
- presently supported. Avoid including issue number in the directory name too,
- include that info in a comment inside `rmake.rs`.
+- For the [`run-make`]/`run-make-support` test suites, each `rmake.rs` must
+ be contained within an immediate subdirectory under `tests/run-make/` or
+ `tests/run-make-cargo/` respectively. Further nesting is not presently
+ supported. Avoid using _only_ an issue number for the test name as well.
## Test descriptions
@@ -199,4 +199,4 @@
[compiletest directives]: ./directives.md
[`run-make`]: ./compiletest.md#run-make-tests
[FileCheck]: https://llvm.org/docs/CommandGuide/FileCheck.html
-[crashes tests]: ./compiletest.md#crashes-tests
+[crash tests]: ./compiletest.md#crash-tests
diff --git a/src/tests/ci.md b/src/tests/ci.md
index 95850c0..6c0b5c2 100644
--- a/src/tests/ci.md
+++ b/src/tests/ci.md
@@ -1,18 +1,18 @@
# Testing with CI
The primary goal of our CI system is to ensure that the `master` branch of
-`rust-lang/rust` is always in a valid state and passes our test suite.
+`rust-lang/rust` is always in a valid state by passing our test suite.
From a high-level point of view, when you open a pull request at
`rust-lang/rust`, the following will happen:
- A small [subset](#pull-request-builds) of tests and checks are run after each
- push to the PR. This should help catching common errors.
+ push to the PR. This should help catch common errors.
- When the PR is approved, the [bors] bot enqueues the PR into a [merge queue].
- Once the PR gets to the front of the queue, bors will create a merge commit
and run the [full test suite](#auto-builds) on it. The merge commit either
contains only one specific PR or it can be a ["rollup"](#rollups) which
- combines multiple PRs together, to save CI costs.
+ combines multiple PRs together, to reduce CI costs and merge delays.
- Once the whole test suite finishes, two things can happen. Either CI fails
with an error that needs to be addressed by the developer, or CI succeeds and
the merge commit is then pushed to the `master` branch.
@@ -22,7 +22,7 @@
## CI workflow
-<!-- date-check: Aug 2025 -->
+<!-- date-check: Oct 2024 -->
Our CI is primarily executed on [GitHub Actions], with a single workflow defined
in [`.github/workflows/ci.yml`], which contains a bunch of steps that are
@@ -38,12 +38,12 @@
> orchestrating the scripts that drive the process.
In essence, all CI jobs run `./x test`, `./x dist` or some other command with
-different configurations, across various operating systems, targets and
+different configurations, across various operating systems, targets, and
platforms. There are two broad categories of jobs that are executed, `dist` and
non-`dist` jobs.
- Dist jobs build a full release of the compiler for a specific platform,
- including all the tools we ship through rustup; Those builds are then uploaded
+ including all the tools we ship through rustup. Those builds are then uploaded
to the `rust-lang-ci2` S3 bucket and are available to be locally installed
with the [rustup-toolchain-install-master] tool. The same builds are also used
for actual releases: our release process basically consists of copying those
@@ -70,7 +70,7 @@
and `tidy` jobs, all running on Linux. These execute a relatively short
(~40 minutes) and lightweight test suite that should catch common issues. More
specifically, they run a set of lints, they try to perform a cross-compile check
-build to Windows mingw (without producing any artifacts) and they test the
+build to Windows mingw (without producing any artifacts), and they test the
compiler using a *system* version of LLVM. Unfortunately, it would take too many
resources to run the full test suite for each commit on every PR.
@@ -95,17 +95,16 @@
test suite is quite slow; it can take several hours until all the `auto` CI
jobs finish.
-Most platforms only run the build steps, some run a restricted set of tests,
+Most platforms only run the build steps, some run a restricted set of tests;
only a subset run the full suite of tests (see Rust's [platform tiers]).
Auto jobs are defined in the `auto` section of [`jobs.yml`]. They are executed
-on the `auto` branch under the `rust-lang/rust` repository and
-their results can be seen [here](https://github.com/rust-lang/rust/actions),
-although usually you will be notified of the result by a comment made by bors on
-the corresponding PR.
+on the `auto` branch under the `rust-lang/rust` repository,
+and the final result will be reported via a comment made by bors on the corresponding PR.
+The live results can be seen on [the GitHub Actions workflows page].
At any given time, at most a single `auto` build is being executed. Find out
-more [here](#merging-prs-serially-with-bors).
+more in [Merging PRs serially with bors](#merging-prs-serially-with-bors).
[platform tiers]: https://forge.rust-lang.org/release/platform-support.html#rust-platform-support
@@ -125,7 +124,7 @@
when you start a try build). To create a try build and schedule it for a
performance benchmark, you can use the `@bors try @rust-timer queue` command
combination.
-- Check the impact of the PR across the Rust ecosystem, using a [crater] run.
+- Check the impact of the PR across the Rust ecosystem, using a [Crater](crater.md) run.
Again, a working compiler build is needed for this, which can be produced by
the [dist-x86_64-linux] CI job.
- Run a specific CI job (e.g. Windows tests) on a PR, to quickly test if it
@@ -134,11 +133,11 @@
By default, if you send a comment with `@bors try`, the jobs defined in the `try` section of
[`jobs.yml`] will be executed. We call this mode a "fast try build". Such a try build
will not execute any tests, and it will allow compilation warnings. It is useful when you want to
-get an optimized toolchain as fast as possible, for a crater run or performance benchmarks,
+get an optimized toolchain as fast as possible, for a Crater run or performance benchmarks,
even if it might not be working fully correctly. If you want to do a full build for the default try job,
specify its job name in a job pattern (explained below).
-If you want to run custom CI job(s) in a try build and make sure that they pass all tests and do
+If you want to run custom CI jobs in a try build and make sure that they pass all tests and do
not produce any compilation warnings, you can select CI jobs to be executed by specifying a *job pattern*,
which can be used in one of two ways:
- You can add a set of `try-job: <job pattern>` directives to the PR description (described below) and then
@@ -151,8 +150,9 @@
Each job pattern can either be an exact name of a job or a glob pattern that matches multiple jobs,
for example `*msvc*` or `*-alt`. You can start at most 20 jobs in a single try build. When using
-glob patterns, you might want to wrap them in backticks (`` ` ``) to avoid GitHub rendering
-the pattern as Markdown.
+glob patterns in the PR description, you can optionally wrap them in backticks (`` ` ``) to avoid GitHub rendering
+the pattern as Markdown if it contains e.g. an asterisk. Note that this escaping will not work when using
+the `@bors jobs=` parameter.
The job pattern needs to match one or more jobs defined in the `auto` or `optional` sections
of [`jobs.yml`]:
@@ -189,18 +189,17 @@
> that are exercised this way.
Try builds are executed on the `try` branch under the `rust-lang/rust` repository and
-their results can be seen [here](https://github.com/rust-lang/rust/actions),
+their results can be seen on [the GitHub Actions workflows page],
although usually you will be notified of the result by a comment made by bors on
the corresponding PR.
Multiple try builds can execute concurrently across different PRs, but there can be at most
a single try build running on a single PR at any given time.
-Note that try builds are handled using the new [bors][new-bors] implementation.
+Note that try builds are handled using the [new bors] implementation.
[rustc-perf]: https://github.com/rust-lang/rustc-perf
-[crater]: https://github.com/rust-lang/crater
-[new-bors]: https://github.com/rust-lang/bors
+[new bors]: https://github.com/rust-lang/bors
### Modifying CI jobs
@@ -210,8 +209,7 @@
You can also modify what gets executed temporarily, for example to test a
particular platform or configuration that is challenging to test locally (for
example, if a Windows build fails, but you don't have access to a Windows
-machine). Don't hesitate to use CI resources in such situations to try out a
-fix!
+machine). Don't hesitate to use CI resources in such situations.
You can perform an arbitrary CI job in two ways:
- Use the [try build](#try-builds) functionality, and specify the CI jobs that
@@ -254,8 +252,8 @@
</div>
Although you are welcome to use CI, just be conscious that this is a shared
-resource with limited concurrency. Try not to enable too many jobs at once (one
-or two should be sufficient in most cases).
+resource with limited concurrency. Try not to enable too many jobs at once;
+one or two should be sufficient in most cases.
## Merging PRs serially with bors
@@ -279,12 +277,12 @@
based on the latest `master` and only one can be tested at the same time, when
the results are green, `master` is fast-forwarded to that merge commit.
-Unfortunately testing a single PR at the time, combined with our long CI (~2
-hours for a full run), means we can’t merge too many PRs in a single day, and a
-single failure greatly impacts our throughput for the day. The maximum number of
+Unfortunately, testing a single PR at a time, combined with our long CI (~2
+hours for a full run), means we can’t merge a lot of PRs in a single day, and a
+single failure greatly impacts our throughput. The maximum number of
PRs we can merge in a day is around ~10.
-The large CI run times and requirement for a large builder pool is largely due
+The long CI run times, and requirement for a large builder pool, is largely due
to the fact that full release artifacts are built in the `dist-` builders. This
is worth it because these release artifacts:
@@ -297,12 +295,11 @@
Some PRs don’t need the full test suite to be executed: trivial changes like
typo fixes or README improvements *shouldn’t* break the build, and testing every
-single one of them for 2+ hours is a big waste of time. To solve this, we
+single one of them for 2+ hours would be wasteful. To solve this, we
regularly create a "rollup", a PR where we merge several pending trivial PRs so
they can be tested together. Rollups are created manually by a team member using
the "create a rollup" button on the [merge queue]. The team member uses their
-judgment to decide if a PR is risky or not, and are the best tool we have at the
-moment to keep the queue in a manageable state.
+judgment to decide if a PR is risky or not.
## Docker
@@ -315,18 +312,22 @@
- We can use ancient build environments to ensure maximum binary compatibility,
for example [using older CentOS releases][dist-x86_64-linux] on our Linux
builders.
-- We can avoid reinstalling tools (like QEMU or the Android emulator) every time
+- We can avoid reinstalling tools (like QEMU or the Android emulator) every time,
thanks to Docker image caching.
-- Users can run the same tests in the same environment locally by just running
- `cargo run --manifest-path src/ci/citool/Cargo.toml run-local <job-name>`, which is awesome to debug failures. Note that there are only linux docker images available locally due to licensing and
+- Users can run the same tests in the same environment locally by just running this command:
+
+ cargo run --manifest-path src/ci/citool/Cargo.toml run-local <job-name>
+
+ This is helpful for debugging failures.
+ Note that there are only Linux Docker images available locally due to licensing and
other restrictions.
-The docker images prefixed with `dist-` are used for building artifacts while
+The Docker images prefixed with `dist-` are used for building artifacts while
those without that prefix run tests and checks.
We also run tests for less common architectures (mainly Tier 2 and Tier 3
-platforms) in CI. Since those platforms are not x86 we either run everything
-inside QEMU or just cross-compile if we don’t want to run the tests for that
+platforms) in CI. Since those platforms are not x86, we either run everything
+inside QEMU, or we just cross-compile if we don’t want to run the tests for that
platform.
These builders are running on a special pool of builders set up and maintained
@@ -363,41 +364,41 @@
[ghcr.io]: https://github.com/rust-lang/rust/pkgs/container/rust-ci
[Docker registry caching]: https://docs.docker.com/build/cache/backends/registry/
-### LLVM caching with sccache
+### LLVM caching with Sccache
-We build some C/C++ stuff in various CI jobs, and we rely on [sccache] to cache
+We build some C/C++ stuff in various CI jobs, and we rely on [Sccache] to cache
the intermediate LLVM artifacts. Sccache is a distributed ccache developed by
Mozilla, which can use an object storage bucket as the storage backend.
-With sccache there's no need to calculate the hash key ourselves. Sccache
+With Sccache there's no need to calculate the hash key ourselves. Sccache
invalidates the cache automatically when it detects changes to relevant inputs,
such as the source code, the version of the compiler, and important environment
variables.
-So we just pass the sccache wrapper on top of cargo and sccache does the rest.
+So we just pass the Sccache wrapper on top of Cargo and Sccache does the rest.
-We store the persistent artifacts on the S3 bucket `rust-lang-ci-sccache2`. So
-when the CI runs, if sccache sees that LLVM is being compiled with the same C/C++
-compiler and the LLVM source code is the same, sccache retrieves the individual
+We store the persistent artifacts on the S3 bucket, `rust-lang-ci-sccache2`. So
+when the CI runs, if Sccache sees that LLVM is being compiled with the same C/C++
+compiler and the LLVM source code is the same, Sccache retrieves the individual
compiled translation units from S3.
[sccache]: https://github.com/mozilla/sccache
## Custom tooling around CI
-During the years we developed some custom tooling to improve our CI experience.
+During the years, we developed some custom tooling to improve our CI experience.
### Rust Log Analyzer to show the error message in PRs
The build logs for `rust-lang/rust` are huge, and it’s not practical to find
-what caused the build to fail by looking at the logs. To improve the developers’
-experience we developed a bot called [Rust Log Analyzer][rla] (RLA) that
-receives the build logs on failure and extracts the error message automatically,
-posting it on the PR.
+what caused the build to fail by looking at the logs.
+We therefore developed a bot called [Rust Log Analyzer][rla] (RLA) that
+receives the build logs on failure, and extracts the error message automatically,
+posting it on the PR thread.
The bot is not hardcoded to look for error strings, but was trained with a bunch
of build failures to recognize which lines are common between builds and which
are not. While the generated snippets can be weird sometimes, the bot is pretty
-good at identifying the relevant lines even if it’s an error we've never seen
+good at identifying the relevant lines, even if it’s an error we've never seen
before.
[rla]: https://github.com/rust-lang/rust-log-analyzer
@@ -429,11 +430,11 @@
## Public CI dashboard
-To monitor the Rust CI, you can have a look at the [public dashboard] maintained by the infra-team.
+To monitor the Rust CI, you can have a look at the [public dashboard] maintained by the infra team.
These are some useful panels from the dashboard:
-- Pipeline duration: check how long the auto builds takes to run.
+- Pipeline duration: check how long the auto builds take to run.
- Top slowest jobs: check which jobs are taking the longest to run.
- Change in median job duration: check what jobs are slowest than before. Useful
to detect regressions.
@@ -456,8 +457,7 @@
2. Choose the job you are interested in on the left-hand side.
3. Click on the gear icon and choose "View raw logs"
4. Search for the string "Configure the build"
-5. All of the build settings are listed below that starting with the
- `configure:` prefix.
+5. All of the build settings are listed on the line with the text, `build.configure-args`
[GitHub Actions]: https://github.com/rust-lang/rust/actions
[`jobs.yml`]: https://github.com/rust-lang/rust/blob/master/src/ci/github-actions/jobs.yml
@@ -467,3 +467,4 @@
[homu]: https://github.com/rust-lang/homu
[merge queue]: https://bors.rust-lang.org/queue/rust
[dist-x86_64-linux]: https://github.com/rust-lang/rust/blob/master/src/ci/docker/host-x86_64/dist-x86_64-linux/Dockerfile
+[the GitHub Actions workflows page]: https://github.com/rust-lang/rust/actions
diff --git a/src/tests/codegen-backend-tests/cg_gcc.md b/src/tests/codegen-backend-tests/cg_gcc.md
index 4caf4c0..74dbfb7 100644
--- a/src/tests/codegen-backend-tests/cg_gcc.md
+++ b/src/tests/codegen-backend-tests/cg_gcc.md
@@ -1,3 +1,56 @@
-# GCC codegen backend tests
+# GCC codegen backend
-TODO: please add some more information to this page.
+If you ran into an error related to tests executed with the GCC codegen backend on CI,
+you can use the following command to run tests locally using the GCC backend:
+
+```bash
+./x test tests/ui --set 'rust.codegen-backends = ["llvm", "gcc"]' --test-codegen-backend gcc
+```
+
+Below, you can find more information about how to configure the GCC backend in bootstrap.
+
+## Choosing which codegen backends are built
+
+The `rust.codegen-backends = [...]` bootstrap option affects which codegen backends will be built and
+included in the sysroot of the produced `rustc`. To use the GCC codegen backend, `"gcc"` has to
+be included in this array in `bootstrap.toml`:
+
+```toml
+rust.codegen-backends = ["llvm", "gcc"]
+```
+
+If you don't want to change your `bootstrap.toml` file, you can alternatively run your `x`
+commands with `--set rust.codegen-backends=["llvm", "gcc"]'`. For example:
+
+```bash
+./x build --set 'rust.codegen-backends=["llvm", "gcc"]'
+```
+
+The first backend in the `codegen-backends` array will determine which backend will be used as the
+*default backend* of the built `rustc`. This also determines which backend will be used to compile the
+stage 1 standard library (or anything built in stage 2+). To produce `rustc` that uses the GCC backend
+by default, you can thus put `"gcc"` as the first element of this array:
+
+```bash
+./x build --set 'rust.codegen-backends=["gcc"]' library
+```
+
+## Choosing the codegen backend used in tests
+
+To run compiler tests with the GCC codegen backend being used to build the test Rust programs, you can use the
+`--test-codegen-backend` flag:
+
+```bash
+./x test tests/ui --test-codegen-backend gcc
+```
+
+Note that in order for this to work, the tested compiler must have the GCC codegen backend available in its sysroot
+directory. You can achieve that using the [instructions above](#choosing-which-codegen-backends-are-built).
+
+## Downloading GCC from CI
+
+The `gcc.download-ci-gcc` bootstrap option controls if GCC (which is a dependency of the GCC codegen backend)
+will be downloaded from CI or built locally. The default value is `true`, which will download GCC from CI
+if there are no local changes to the GCC sources and the given host target is available on CI.
+
+Note that GCC can currently only be downloaded from CI for the `x86_64-unknown-linux-gnu` target.
diff --git a/src/tests/compiletest.md b/src/tests/compiletest.md
index 4980ed8..0234b39 100644
--- a/src/tests/compiletest.md
+++ b/src/tests/compiletest.md
@@ -72,7 +72,7 @@
| [`mir-opt`](#mir-opt-tests) | Check MIR generation and optimizations |
| [`coverage`](#coverage-tests) | Check coverage instrumentation |
| [`coverage-run-rustdoc`](#coverage-tests) | `coverage` tests that also run instrumented doctests |
-| [`crashes`](#crashes-tests) | Check that the compiler ICEs/panics/crashes on certain inputs to catch accidental fixes |
+| [`crashes`](#crash-tests) | Check that the compiler ICEs/panics/crashes on certain inputs to catch accidental fixes |
### General purpose test suite
@@ -397,13 +397,19 @@
### `run-make` tests
-The tests in [`tests/run-make`] are general-purpose tests using Rust *recipes*,
-which are small programs (`rmake.rs`) allowing arbitrary Rust code such as
-`rustc` invocations, and is supported by a [`run_make_support`] library. Using
-Rust recipes provide the ultimate in flexibility.
+The tests in [`tests/run-make`] and [`tests/run-make-cargo`] are general-purpose
+tests using Rust *recipes*, which are small programs (`rmake.rs`) allowing
+arbitrary Rust code such as `rustc` invocations, and is supported by a
+[`run_make_support`] library. Using Rust recipes provide the ultimate in
+flexibility.
`run-make` tests should be used if no other test suites better suit your needs.
+The `run-make-cargo` test suite additionally builds an in-tree `cargo` to support
+use cases that require testing in-tree `cargo` in conjunction with in-tree `rustc`.
+The `run-make` test suite does not have access to in-tree `cargo` (so it can be the
+faster-to-iterate test suite).
+
#### Using Rust recipes
Each test should be in a separate directory with a `rmake.rs` Rust program,
@@ -476,6 +482,7 @@
```
[`tests/run-make`]: https://github.com/rust-lang/rust/tree/master/tests/run-make
+[`tests/run-make-cargo`]: https://github.com/rust-lang/rust/tree/master/tests/run-make-cargo
[`run_make_support`]: https://github.com/rust-lang/rust/tree/master/src/tools/run-make-support
### Coverage tests
@@ -550,7 +557,7 @@
[`src/tools/coverage-dump`]: https://github.com/rust-lang/rust/tree/master/src/tools/coverage-dump
[`tests/coverage-run-rustdoc`]: https://github.com/rust-lang/rust/tree/master/tests/coverage-run-rustdoc
-### Crashes tests
+### Crash tests
[`tests/crashes`] serve as a collection of tests that are expected to cause the
compiler to ICE, panic or crash in some other way, so that accidental fixes are
@@ -573,13 +580,13 @@
When you do so, each issue number should be noted in the file name (`12345.rs`
should suffice) and also inside the file by means of a `//@ known-bug: #12345`
directive. Please [label][labeling] the relevant issues with `S-bug-has-test`
-afterwards.
+once your PR is merged.
If you happen to fix one of the crashes, please move it to a fitting
subdirectory in `tests/ui` and give it a meaningful name. Please add a doc
comment at the top of the file explaining why this test exists, even better if
you can briefly explain how the example causes rustc to crash previously and
-what was done to prevent rustc to ICE/panic/crash.
+what was done to prevent rustc to ICE / panic / crash.
Adding
diff --git a/src/tests/crater.md b/src/tests/crater.md
index 9d4ac87..96bb5a4 100644
--- a/src/tests/crater.md
+++ b/src/tests/crater.md
@@ -8,30 +8,30 @@
## When to run Crater
-You should request a crater run if your PR makes large changes to the compiler
+You should request a Crater run if your PR makes large changes to the compiler
or could cause breakage. If you are unsure, feel free to ask your PR's reviewer.
## Requesting Crater Runs
-The rust team maintains a few machines that can be used for running crater runs
-on the changes introduced by a PR. If your PR needs a crater run, leave a
+The Rust team maintains a few machines that can be used for Crater runs
+on the changes introduced by a PR. If your PR needs a Crater run, leave a
comment for the triage team in the PR thread. Please inform the team whether you
-require a "check-only" crater run, a "build only" crater run, or a
-"build-and-test" crater run. The difference is primarily in time; the
-conservative (if you're not sure) option is to go for the build-and-test run. If
+require a "check-only" Crater run, a "build only" Crater run, or a
+"build-and-test" Crater run. The difference is primarily in time;
+if you're not sure, go for the build-and-test run. If
making changes that will only have an effect at compile-time (e.g., implementing
-a new trait) then you only need a check run.
+a new trait), then you only need a check run.
Your PR will be enqueued by the triage team and the results will be posted when
-they are ready. Check runs will take around ~3-4 days, with the other two taking
+they are ready. Check runs will take around ~3-4 days, and the other two taking
5-6 days on average.
-While crater is really useful, it is also important to be aware of a few
+While Crater is really useful, it is also important to be aware of a few
caveats:
- Not all code is on crates.io! There is a lot of code in repos on GitHub and
elsewhere. Also, companies may not wish to publish their code. Thus, a
- successful crater run is not a magically green light that there will be no
+ successful Crater run does not mean there will be no
breakage; you still need to be careful.
- Crater only runs Linux builds on x86_64. Thus, other architectures and
@@ -41,5 +41,5 @@
the crate doesn't compile any more (e.g. used old nightly features), has
broken or flaky tests, requires network access, or other reasons.
-- Before crater can be run, `@bors try` needs to succeed in building artifacts.
- This means that if your code doesn't compile, you cannot run crater.
+- Before Crater can be run, `@bors try` needs to succeed in building artifacts.
+ This means that if your code doesn't compile, you cannot run Crater.
diff --git a/src/tests/directives.md b/src/tests/directives.md
index 6cf7390..4be78fa 100644
--- a/src/tests/directives.md
+++ b/src/tests/directives.md
@@ -36,13 +36,13 @@
The following is a list of compiletest directives. Directives are linked to
sections that describe the command in more detail if available. This list may
not be exhaustive. Directives can generally be found by browsing the
-`TestProps` structure found in [`header.rs`] from the compiletest source.
+`TestProps` structure found in [`directives.rs`] from the compiletest source.
-[`header.rs`]: https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/header.rs
+[`directives.rs`]: https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/directives.rs
### Assembly
-<!-- date-check: Aug 2025 -->
+<!-- date-check: Oct 2024 -->
| Directive | Explanation | Supported test suites | Possible values |
|-------------------|-------------------------------|-----------------------|----------------------------------------|
@@ -52,14 +52,14 @@
See [Building auxiliary crates](compiletest.html#building-auxiliary-crates)
-| Directive | Explanation | Supported test suites | Possible values |
-|-----------------------|-------------------------------------------------------------------------------------------------------|-----------------------|-----------------------------------------------|
-| `aux-bin` | Build a aux binary, made available in `auxiliary/bin` relative to test directory | All except `run-make` | Path to auxiliary `.rs` file |
-| `aux-build` | Build a separate crate from the named source file | All except `run-make` | Path to auxiliary `.rs` file |
-| `aux-crate` | Like `aux-build` but makes available as extern prelude | All except `run-make` | `<extern_prelude_name>=<path/to/aux/file.rs>` |
-| `aux-codegen-backend` | Similar to `aux-build` but pass the compiled dylib to `-Zcodegen-backend` when building the main file | `ui-fulldeps` | Path to codegen backend file |
-| `proc-macro` | Similar to `aux-build`, but for aux forces host and don't use `-Cprefer-dynamic`[^pm]. | All except `run-make` | Path to auxiliary proc-macro `.rs` file |
-| `build-aux-docs` | Build docs for auxiliaries as well. Note that this only works with `aux-build`, not `aux-crate`. | All except `run-make` | N/A |
+| Directive | Explanation | Supported test suites | Possible values |
+|-----------------------|-------------------------------------------------------------------------------------------------------|----------------------------------------|-----------------------------------------------|
+| `aux-bin` | Build a aux binary, made available in `auxiliary/bin` relative to test directory | All except `run-make`/`run-make-cargo` | Path to auxiliary `.rs` file |
+| `aux-build` | Build a separate crate from the named source file | All except `run-make`/`run-make-cargo` | Path to auxiliary `.rs` file |
+| `aux-crate` | Like `aux-build` but makes available as extern prelude | All except `run-make`/`run-make-cargo` | `<extern_prelude_name>=<path/to/aux/file.rs>` |
+| `aux-codegen-backend` | Similar to `aux-build` but pass the compiled dylib to `-Zcodegen-backend` when building the main file | `ui-fulldeps` | Path to codegen backend file |
+| `proc-macro` | Similar to `aux-build`, but for aux forces host and don't use `-Cprefer-dynamic`[^pm]. | All except `run-make`/`run-make-cargo` | Path to auxiliary proc-macro `.rs` file |
+| `build-aux-docs` | Build docs for auxiliaries as well. Note that this only works with `aux-build`, not `aux-crate`. | All except `run-make`/`run-make-cargo` | N/A |
[^pm]: please see the [Auxiliary proc-macro section](compiletest.html#auxiliary-proc-macro) in the compiletest chapter for specifics.
@@ -113,7 +113,7 @@
| `known-bug` | No error annotation needed due to known bug | `ui`, `crashes`, `incremental` | Issue number `#123456` |
| `compare-output-by-lines` | Compare the output by lines, rather than as a single string | All | N/A |
-[^check_stdout]: presently <!-- date-check: Aug 2025 --> this has a weird quirk
+[^check_stdout]: presently <!-- date-check: Oct 2024 --> this has a weird quirk
where the test binary's stdout and stderr gets concatenated and then
`error-pattern`s are matched on this combined output, which is ??? slightly
questionable to say the least.
@@ -243,18 +243,18 @@
### Affecting how tests are built
-| Directive | Explanation | Supported test suites | Possible values |
-|---------------------|----------------------------------------------------------------------------------------------|---------------------------|--------------------------------------------------------------------------------------------|
-| `compile-flags` | Flags passed to `rustc` when building the test or aux file | All except for `run-make` | Any valid `rustc` flags, e.g. `-Awarnings -Dfoo`. Cannot be `-Cincremental` or `--edition` |
-| `edition` | The edition used to build the test | All except for `run-make` | Any valid `--edition` value |
-| `rustc-env` | Env var to set when running `rustc` | All except for `run-make` | `<KEY>=<VALUE>` |
-| `unset-rustc-env` | Env var to unset when running `rustc` | All except for `run-make` | Any env var name |
-| `incremental` | Proper incremental support for tests outside of incremental test suite | `ui`, `crashes` | N/A |
-| `no-prefer-dynamic` | Don't use `-C prefer-dynamic`, don't build as a dylib via a `--crate-type=dylib` preset flag | `ui`, `crashes` | N/A |
+| Directive | Explanation | Supported test suites | Possible values |
+|---------------------|----------------------------------------------------------------------------------------------|--------------------------------------------|--------------------------------------------------------------------------------------------|
+| `compile-flags` | Flags passed to `rustc` when building the test or aux file | All except for `run-make`/`run-make-cargo` | Any valid `rustc` flags, e.g. `-Awarnings -Dfoo`. Cannot be `-Cincremental` or `--edition` |
+| `edition` | The edition used to build the test | All except for `run-make`/`run-make-cargo` | Any valid `--edition` value |
+| `rustc-env` | Env var to set when running `rustc` | All except for `run-make`/`run-make-cargo` | `<KEY>=<VALUE>` |
+| `unset-rustc-env` | Env var to unset when running `rustc` | All except for `run-make`/`run-make-cargo` | Any env var name |
+| `incremental` | Proper incremental support for tests outside of incremental test suite | `ui`, `crashes` | N/A |
+| `no-prefer-dynamic` | Don't use `-C prefer-dynamic`, don't build as a dylib via a `--crate-type=dylib` preset flag | `ui`, `crashes` | N/A |
<div class="warning">
-Tests (outside of `run-make`) that want to use incremental tests not in the
+Tests (outside of `run-make`/`run-make-cargo`) that want to use incremental tests not in the
incremental test-suite must not pass `-C incremental` via `compile-flags`, and
must instead use the `//@ incremental` directive.
@@ -264,9 +264,9 @@
### Rustdoc
-| Directive | Explanation | Supported test suites | Possible values |
-|-------------|--------------------------------------------------------------|------------------------------------------|---------------------------|
-| `doc-flags` | Flags passed to `rustdoc` when building the test or aux file | `rustdoc`, `rustdoc-js`, `rustdoc-json` | Any valid `rustdoc` flags |
+| Directive | Explanation | Supported test suites | Possible values |
+|-------------|--------------------------------------------------------------|-----------------------------------------|---------------------------|
+| `doc-flags` | Flags passed to `rustdoc` when building the test or aux file | `rustdoc`, `rustdoc-js`, `rustdoc-json` | Any valid `rustdoc` flags |
<!--
**FIXME(rustdoc)**: what does `check-test-line-numbers-match` do?
@@ -374,7 +374,7 @@
To add a new directive property:
1. Look for the `pub struct TestProps` declaration in
- [`src/tools/compiletest/src/header.rs`] and add the new public property to
+ [`src/tools/compiletest/src/directives.rs`] and add the new public property to
the end of the declaration.
2. Look for the `impl TestProps` implementation block immediately following the
struct declaration and initialize the new property to its default value.
@@ -383,7 +383,7 @@
When `compiletest` encounters a test file, it parses the file a line at a time
by calling every parser defined in the `Config` struct's implementation block,
-also in [`src/tools/compiletest/src/header.rs`] (note that the `Config` struct's
+also in [`src/tools/compiletest/src/directives.rs`] (note that the `Config` struct's
declaration block is found in [`src/tools/compiletest/src/common.rs`]).
`TestProps`'s `load_from()` method will try passing the current line of text to
each parser, which, in turn typically checks to see if the line begins with a
@@ -406,7 +406,7 @@
writing additional parsing code unnecessarily.
As a concrete example, here is the implementation for the
-`parse_failure_status()` parser, in [`src/tools/compiletest/src/header.rs`]:
+`parse_failure_status()` parser, in [`src/tools/compiletest/src/directives.rs`]:
```diff
@@ -232,6 +232,7 @@ pub struct TestProps {
@@ -508,6 +508,6 @@
1, as `parse_failure_status()` will have overridden the `TestProps` default
value, for that test specifically.
-[`src/tools/compiletest/src/header.rs`]: https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/header.rs
+[`src/tools/compiletest/src/directives.rs`]: https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/directives.rs
[`src/tools/compiletest/src/common.rs`]: https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/common.rs
[`src/tools/compiletest/src/runtest.rs`]: https://github.com/rust-lang/rust/tree/master/src/tools/compiletest/src/runtest.rs
diff --git a/src/tests/intro.md b/src/tests/intro.md
index b90c16d..4fa63b8 100644
--- a/src/tests/intro.md
+++ b/src/tests/intro.md
@@ -70,10 +70,12 @@
Tidy is a custom tool used for validating source code style and formatting
conventions, such as rejecting long lines. There is more information in the
-[section on coding conventions](../conventions.md#formatting).
+[section on coding conventions](../conventions.md#formatting) or the [Tidy Readme].
> Examples: `./x test tidy`
+[Tidy Readme]: https://github.com/rust-lang/rust/blob/master/src/tools/tidy/Readme.md
+
### Formatting
diff --git a/src/tests/misc.md b/src/tests/misc.md
index ed80c6c..cc8f501 100644
--- a/src/tests/misc.md
+++ b/src/tests/misc.md
@@ -2,7 +2,7 @@
## `RUSTC_BOOTSTRAP` and stability
-<!-- date-check: Aug 2025 -->
+<!-- date-check: Nov 2024 -->
This is a bootstrap/compiler implementation detail, but it can also be useful
for testing:
@@ -24,8 +24,8 @@
//@ rustc-env:RUSTC_BOOTSTRAP=-1
```
-For `run-make` tests, `//@ rustc-env` is not supported. You can do something
-like the following for individual `rustc` invocations.
+For `run-make`/`run-make-cargo` tests, `//@ rustc-env` is not supported. You can do
+something like the following for individual `rustc` invocations.
```rust,ignore
use run_make_support::rustc;
diff --git a/src/tests/running.md b/src/tests/running.md
index 317b65f..482f3c4 100644
--- a/src/tests/running.md
+++ b/src/tests/running.md
@@ -339,9 +339,34 @@
build tools use `remote-test-client` to communicate with the server to
coordinate running tests (see [src/bootstrap/src/core/build_steps/test.rs]).
-> **TODO**
->
-> - Is there any support for using an iOS emulator?
+To run on the iOS/tvOS/watchOS/visionOS simulator, we can similarly treat it as
+a "remote" machine. A curious detail here is that the network is shared between
+the simulator instance and the host macOS, so we can use the local loopback
+address `127.0.0.1`. Something like the following should work:
+
+```sh
+# Build the test server for the iOS simulator:
+./x build src/tools/remote-test-server --target aarch64-apple-ios-sim
+
+# If you already have a simulator instance open, copy the device UUID from:
+xcrun simctl list devices booted
+UDID=01234567-89AB-CDEF-0123-456789ABCDEF
+
+# Alternatively, create and boot a new simulator instance:
+xcrun simctl list runtimes
+xcrun simctl list devicetypes
+UDID=$(xcrun simctl create $CHOSEN_DEVICE_TYPE $CHOSEN_RUNTIME)
+xcrun simctl boot $UDID
+# See https://nshipster.com/simctl/ for details.
+
+# Spawn the runner on port 12345:
+xcrun simctl spawn $UDID ./build/host/stage2-tools/aarch64-apple-ios-sim/release/remote-test-server -v --bind 127.0.0.1:12345
+
+# In a new terminal, run tests via the runner:
+export TEST_DEVICE_ADDR="127.0.0.1:12345"
+./x test --host='' --target aarch64-apple-ios-sim --skip tests/debuginfo
+# FIXME(madsmtm): Allow debuginfo tests to work (maybe needs `.dSYM` folder to be copied to the target?).
+```
[armhf-gnu]: https://github.com/rust-lang/rust/tree/master/src/ci/docker/host-x86_64/armhf-gnu/Dockerfile
[QEMU]: https://www.qemu.org/
diff --git a/src/thir.md b/src/thir.md
index 6a3525d..3d3dafa 100644
--- a/src/thir.md
+++ b/src/thir.md
@@ -2,7 +2,7 @@
The THIR ("Typed High-Level Intermediate Representation"), previously called HAIR for
"High-Level Abstract IR", is another IR used by rustc that is generated after
-[type checking]. It is (as of <!-- date-check --> August 2025) used for
+[type checking]. It is (as of <!-- date-check --> January 2024) used for
[MIR construction], [exhaustiveness checking], and [unsafety checking].
[type checking]: ./type-checking.md
@@ -52,7 +52,7 @@
}
```
-Here is how that gets represented in THIR (as of <!-- date-check --> August 2025):
+Here is how that gets represented in THIR (as of <!-- date-check --> Aug 2022):
```rust,no_run
Thir {
diff --git a/src/tracing.md b/src/tracing.md
index 5e5b81f..a7cdab7 100644
--- a/src/tracing.md
+++ b/src/tracing.md
@@ -109,7 +109,7 @@
See the [`tracing`] crate's docs, and specifically the docs for [`debug!`] to
see the full syntax you can use. (Note: unlike the compiler, the [`tracing`]
-crate and its examples use the `RUST_LOG` environment variable. rustc, rustdoc,
+crate and its examples use the `RUSTC_LOG` environment variable. rustc, rustdoc,
and other tools set custom environment variables.)
**Note that unless you use a very strict filter, the logger will emit a lot of
diff --git a/src/traits/chalk.md b/src/traits/chalk.md
index eac8e6b..ca5ed52 100644
--- a/src/traits/chalk.md
+++ b/src/traits/chalk.md
@@ -1,11 +1,11 @@
# Chalk-based trait solving
[Chalk][chalk] is an experimental trait solver for Rust that is
-(as of <!-- date-check --> August 2025) under development by the [Types team].
+(as of <!-- date-check --> May 2022) under development by the [Types team].
Its goal is to enable a lot of trait system features and bug fixes
that are hard to implement (e.g. GATs or specialization). If you would like to
help in hacking on the new solver, drop by on the rust-lang Zulip in the [`#t-types`]
-stream and say hello!
+channel and say hello!
[Types team]: https://github.com/rust-lang/types-team
[`#t-types`]: https://rust-lang.zulipchat.com/#narrow/stream/144729-t-types
diff --git a/src/traits/resolution.md b/src/traits/resolution.md
index 711b7eb..ccb2b04 100644
--- a/src/traits/resolution.md
+++ b/src/traits/resolution.md
@@ -120,7 +120,7 @@
The subroutines that decide whether a particular impl/where-clause/etc applies
to a particular obligation are collectively referred to as the process of
-_matching_. For `impl` candidates <!-- date-check: Aug 2025 -->,
+_matching_. For `impl` candidates <!-- date-check: Oct 2022 -->,
this amounts to unifying the impl header (the `Self` type and the trait arguments)
while ignoring nested obligations. If matching succeeds then we add it
to a set of candidates. There are other rules when assembling candidates for
diff --git a/src/ty-fold.md b/src/ty-fold.md
index d0fa548..2325302 100644
--- a/src/ty-fold.md
+++ b/src/ty-fold.md
@@ -1,4 +1,4 @@
-<!-- date-check: Aug 2025 -->
+<!-- date-check: may 2024 -->
# `TypeFoldable` and `TypeFolder`
In [a previous chapter], we discussed instantiating binders.
diff --git a/src/type-inference.md b/src/type-inference.md
index 0c7e283..24982a2 100644
--- a/src/type-inference.md
+++ b/src/type-inference.md
@@ -66,7 +66,7 @@
[Unification in the Chalk project]: http://smallcultfollowing.com/babysteps/blog/2017/03/25/unification-in-chalk-part-1/
All told, the inference context stores five kinds of inference variables
-(as of <!-- date-check --> August 2025):
+(as of <!-- date-check --> March 2023):
- Type variables, which come in three varieties:
- General type variables (the most common). These can be unified with any
@@ -239,13 +239,13 @@
[`take_and_reset_region_constraints`] at the end. This extracts all of the
outlives constraints added during the canonical query. This is required
as the NLL solver must not only know *what* regions outlive each other,
-but also *where*. Finally, the NLL solver invokes [`take_region_var_origins`],
+but also *where*. Finally, the NLL solver invokes [`get_region_var_infos`],
providing all region variables to the solver.
-[`resolve_regions_and_report_errors`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/infer/struct.InferCtxt.html#method.resolve_regions_and_report_errors
+[`resolve_regions_and_report_errors`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_trait_selection/traits/struct.ObligationCtxt.html#method.resolve_regions_and_report_errors
[`lexical_region_resolve`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/infer/lexical_region_resolve/index.html
[`take_and_reset_region_constraints`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/infer/struct.InferCtxt.html#method.take_and_reset_region_constraints
-[`take_region_var_origins`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/infer/struct.InferCtxt.html#method.take_region_var_origins
+[`get_region_var_infos`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_infer/infer/struct.InferCtxt.html#method.get_region_var_infos
## Lexical region resolution
diff --git a/src/typing_parameter_envs.md b/src/typing_parameter_envs.md
index db15467..45635eb 100644
--- a/src/typing_parameter_envs.md
+++ b/src/typing_parameter_envs.md
@@ -2,11 +2,14 @@
## Typing Environments
-When interacting with the type system there are a few variables to consider that can affect the results of trait solving. The set of in-scope where clauses, and what phase of the compiler type system operations are being performed in (the [`ParamEnv`][penv] and [`TypingMode`][tmode] structs respectively).
+When interacting with the type system there are a few variables to consider that can affect the results of trait solving.
+The set of in-scope where clauses, and what phase of the compiler type system operations are being performed in (the [`ParamEnv`][penv] and [`TypingMode`][tmode] structs respectively).
-When an environment to perform type system operations in has not yet been created, the [`TypingEnv`][tenv] can be used to bundle all of the external context required into a single type.
+When an environment to perform type system operations in has not yet been created,
+the [`TypingEnv`][tenv] can be used to bundle all of the external context required into a single type.
-Once a context to perform type system operations in has been created (e.g. an [`ObligationCtxt`][ocx] or [`FnCtxt`][fnctxt]) a `TypingEnv` is typically not stored anywhere as only the `TypingMode` is a property of the whole environment, whereas different `ParamEnv`s can be used on a per-goal basis.
+Once a context to perform type system operations in has been created (e.g. an [`ObligationCtxt`][ocx] or [`FnCtxt`][fnctxt]) a `TypingEnv` is typically not stored anywhere as only the `TypingMode` is a property of the whole environment,
+whereas different `ParamEnv`s can be used on a per-goal basis.
[ocx]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_trait_selection/traits/struct.ObligationCtxt.html
[fnctxt]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/fn_ctxt/struct.FnCtxt.html
@@ -15,9 +18,14 @@
### What is a `ParamEnv`
-The [`ParamEnv`][penv] is a list of in-scope where-clauses, it typically corresponds to a specific item's where clauses. Some clauses are not explicitly written but are instead implicitly added in the [`predicates_of`][predicates_of] query, such as `ConstArgHasType` or (some) implied bounds.
+The [`ParamEnv`][penv] is a list of in-scope where-clauses,
+it typically corresponds to a specific item's where clauses.
+Some clauses are not explicitly written but are instead implicitly added in the [`predicates_of`][predicates_of] query,
+such as `ConstArgHasType` or (some) implied bounds.
-In most cases `ParamEnv`s are initially created via the [`param_env` query][query] which returns a `ParamEnv` derived from the provided item's where clauses. A `ParamEnv` can also be created with arbitrary sets of clauses that are not derived from a specific item, such as in [`compare_method_predicate_entailment`][method_pred_entailment] where we create a hybrid `ParamEnv` consisting of the impl's where clauses and the trait definition's function's where clauses.
+In most cases `ParamEnv`s are initially created via the [`param_env` query][query] which returns a `ParamEnv` derived from the provided item's where clauses.
+A `ParamEnv` can also be created with arbitrary sets of clauses that are not derived from a specific item,
+such as in [`compare_method_predicate_entailment`][method_pred_entailment] where we create a hybrid `ParamEnv` consisting of the impl's where clauses and the trait definition's function's where clauses.
---
@@ -30,7 +38,9 @@
<T as Trait>::Assoc: Clone,
{}
```
-If we were conceptually inside of `foo` (for example, type-checking or linting it) we would use this `ParamEnv` everywhere that we interact with the type system. This would allow things such as [normalization], evaluating generic constants, and proving where clauses/goals, to rely on `T` being sized, implementing `Trait`, etc.
+If we were conceptually inside of `foo` (for example, type-checking or linting it) we would use this `ParamEnv` everywhere that we interact with the type system.
+This would allow things such as [normalization], evaluating generic constants,
+and proving where clauses/goals, to rely on `T` being sized, implementing `Trait`, etc.
A more concrete example:
```rust
@@ -72,9 +82,13 @@
### Acquiring a `ParamEnv`
-Using the wrong [`ParamEnv`][penv] when interacting with the type system can lead to ICEs, illformed programs compiling, or erroring when we shouldn't. See [#82159](https://github.com/rust-lang/rust/pull/82159) and [#82067](https://github.com/rust-lang/rust/pull/82067) as examples of PRs that modified the compiler to use the correct param env and in the process fixed ICEs.
+Using the wrong [`ParamEnv`][penv] when interacting with the type system can lead to ICEs,
+illformed programs compiling, or erroring when we shouldn't.
+See [#82159](https://github.com/rust-lang/rust/pull/82159) and [#82067](https://github.com/rust-lang/rust/pull/82067) as examples of PRs that modified the compiler to use the correct param env and in the process fixed ICEs.
-In the large majority of cases, when a `ParamEnv` is required it either already exists somewhere in scope, or above in the call stack and should be passed down. A non exhaustive list of places where you might find an existing `ParamEnv`:
+In the large majority of cases, when a `ParamEnv` is required it either already exists somewhere in scope,
+or above in the call stack and should be passed down.
+A non exhaustive list of places where you might find an existing `ParamEnv`:
- During typeck `FnCtxt` has a [`param_env` field][fnctxt_param_env]
- When writing late lints the `LateContext` has a [`param_env` field][latectxt_param_env]
- During well formedness checking the `WfCheckingCtxt` has a [`param_env` field][wfckctxt_param_env]
@@ -82,16 +96,20 @@
- In the next-gen trait solver all `Goal`s have a [`param_env` field][goal_param_env] specifying what environment to prove the goal in
- When editing an existing [`TypeRelation`][typerelation] if it implements [`PredicateEmittingRelation`][predicate_emitting_relation] then a [`param_env` method][typerelation_param_env] will be available.
-If you aren't sure if there's a `ParamEnv` in scope somewhere that can be used it can be worth opening a thread in the [`#t-compiler/help`][compiler_help] zulip stream where someone may be able to point out where a `ParamEnv` can be acquired from.
+If you aren't sure if there's a `ParamEnv` in scope somewhere that can be used it can be worth opening a thread in the [`#t-compiler/help`][compiler_help] Zulip channel where someone may be able to point out where a `ParamEnv` can be acquired from.
-Manually constructing a `ParamEnv` is typically only needed at the start of some kind of top level analysis (e.g. hir typeck or borrow checking). In such cases there are three ways it can be done:
+Manually constructing a `ParamEnv` is typically only needed at the start of some kind of top level analysis (e.g. hir typeck or borrow checking).
+In such cases there are three ways it can be done:
- Calling the [`tcx.param_env(def_id)` query][param_env_query] which returns the environment associated with a given definition.
- Creating an empty environment with [`ParamEnv::empty`][env_empty].
-- Using [`ParamEnv::new`][param_env_new] to construct an env with an arbitrary set of where clauses. Then calling [`traits::normalize_param_env_or_error`][normalize_env_or_error] to handle normalizing and elaborating all the where clauses in the env.
+- Using [`ParamEnv::new`][param_env_new] to construct an env with an arbitrary set of where clauses.
+ Then calling [`traits::normalize_param_env_or_error`][normalize_env_or_error] to handle normalizing and elaborating all the where clauses in the env.
Using the `param_env` query is by far the most common way to construct a `ParamEnv` as most of the time the compiler is performing an analysis as part of some specific definition.
-Creating an empty environment with `ParamEnv::empty` is typically only done either in codegen (indirectly via [`TypingEnv::fully_monomorphized`][tenv_mono]), or as part of some analysis that do not expect to ever encounter generic parameters (e.g. various parts of coherence/orphan check).
+Creating an empty environment with `ParamEnv::empty` is typically only done either in codegen (indirectly via [`TypingEnv::fully_monomorphized`][tenv_mono]),
+or as part of some analysis that do not expect to ever encounter generic parameters
+(e.g. various parts of coherence/orphan check).
Creating an env from an arbitrary set of where clauses is usually unnecessary and should only be done if the environment you need does not correspond to an actual item in the source code (e.g. [`compare_method_predicate_entailment`][method_pred_entailment]).
@@ -113,11 +131,14 @@
### How are `ParamEnv`s constructed
-Creating a [`ParamEnv`][pe] is more complicated than simply using the list of where clauses defined on an item as written by the user. We need to both elaborate supertraits into the env and fully normalize all aliases. This logic is handled by [`traits::normalize_param_env_or_error`][normalize_env_or_error] (even though it does not mention anything about elaboration).
+Creating a [`ParamEnv`][pe] is more complicated than simply using the list of where clauses defined on an item as written by the user.
+We need to both elaborate supertraits into the env and fully normalize all aliases.
+This logic is handled by [`traits::normalize_param_env_or_error`][normalize_env_or_error] (even though it does not mention anything about elaboration).
#### Elaborating supertraits
-When we have a function such as `fn foo<T: Copy>()` we would like to be able to prove `T: Clone` inside of the function as the `Copy` trait has a `Clone` supertrait. Constructing a `ParamEnv` looks at all of the trait bounds in the env and explicitly adds new where clauses to the `ParamEnv` for any supertraits found on the traits.
+When we have a function such as `fn foo<T: Copy>()` we would like to be able to prove `T: Clone` inside of the function as the `Copy` trait has a `Clone` supertrait.
+Constructing a `ParamEnv` looks at all of the trait bounds in the env and explicitly adds new where clauses to the `ParamEnv` for any supertraits found on the traits.
A concrete example would be the following function:
```rust
@@ -133,13 +154,16 @@
fn requires_impl<T: Clone + SuperSuperTrait>(a: T) {}
```
-If we did not elaborate the env then the `requires_impl` call would fail to typecheck as we would not be able to prove `T: Clone` or `T: SuperSuperTrait`. In practice we elaborate the env which means that `bar`'s `ParamEnv` is actually:
+If we did not elaborate the env then the `requires_impl` call would fail to typecheck as we would not be able to prove `T: Clone` or `T: SuperSuperTrait`.
+In practice we elaborate the env which means that `bar`'s `ParamEnv` is actually:
`[T: Sized, T: Copy, T: Clone, T: Trait, T: SuperTrait, T: SuperSuperTrait]`
This allows us to prove `T: Clone` and `T: SuperSuperTrait` when type checking `bar`.
The `Clone` trait has a `Sized` supertrait however we do not end up with two `T: Sized` bounds in the env (one for the supertrait and one for the implicitly added `T: Sized` bound) as the elaboration process (implemented via [`util::elaborate`][elaborate]) deduplicates where clauses.
-A side effect of this is that even if no actual elaboration of supertraits takes place, the existing where clauses in the env are _also_ deduplicated. See the following example:
+A side effect of this is that even if no actual elaboration of supertraits takes place,
+the existing where clauses in the env are _also_ deduplicated.
+See the following example:
```rust
trait Trait {}
// The unelaborated `ParamEnv` would be:
@@ -156,7 +180,8 @@
#### Normalizing all bounds
-In the old trait solver the where clauses stored in `ParamEnv` are required to be fully normalized as otherwise the trait solver will not function correctly. A concrete example of needing to normalize the `ParamEnv` is the following:
+In the old trait solver the where clauses stored in `ParamEnv` are required to be fully normalized as otherwise the trait solver will not function correctly.
+A concrete example of needing to normalize the `ParamEnv` is the following:
```rust
trait Trait<T> {
type Assoc;
@@ -182,11 +207,14 @@
fn requires_impl<U: Trait<u32>>(_: U) {}
```
-As humans we can tell that `<T as Other>::Bar` is equal to `u32` so the trait bound on `U` is equivalent to `U: Trait<u32>`. In practice trying to prove `U: Trait<u32>` in the old solver in this environment would fail as it is unable to determine that `<T as Other>::Bar` is equal to `u32`.
+As humans we can tell that `<T as Other>::Bar` is equal to `u32` so the trait bound on `U` is equivalent to `U: Trait<u32>`.
+In practice trying to prove `U: Trait<u32>` in the old solver in this environment would fail as it is unable to determine that `<T as Other>::Bar` is equal to `u32`.
To work around this we normalize `ParamEnv`'s after constructing them so that `foo`'s `ParamEnv` is actually: `[T: Sized, U: Sized, U: Trait<u32>]` which means the trait solver is now able to use the `U: Trait<u32>` in the `ParamEnv` to determine that the trait bound `U: Trait<u32>` holds.
-This workaround does not work in all cases as normalizing associated types requires a `ParamEnv` which introduces a bootstrapping problem. We need a normalized `ParamEnv` in order for normalization to give correct results, but we need to normalize to get that `ParamEnv`. Currently we normalize the `ParamEnv` once using the unnormalized param env and it tends to give okay results in practice even though there are some examples where this breaks ([example]).
+This workaround does not work in all cases as normalizing associated types requires a `ParamEnv` which introduces a bootstrapping problem.
+We need a normalized `ParamEnv` in order for normalization to give correct results, but we need to normalize to get that `ParamEnv`.
+Currently we normalize the `ParamEnv` once using the unnormalized param env and it tends to give okay results in practice even though there are some examples where this breaks ([example]).
In the next-gen trait solver the requirement for all where clauses in the `ParamEnv` to be fully normalized is not present and so we do not normalize when constructing `ParamEnv`s.
@@ -196,9 +224,12 @@
## Typing Modes
-Depending on what context we are performing type system operations in, different behaviour may be required. For example during coherence there are stronger requirements about when we can consider goals to not hold or when we can consider types to be unequal.
+Depending on what context we are performing type system operations in,
+different behaviour may be required.
+For example during coherence there are stronger requirements about when we can consider goals to not hold or when we can consider types to be unequal.
-Tracking which "phase" of the compiler type system operations are being performed in is done by the [`TypingMode`][tmode] enum. The documentation on the `TypingMode` enum is quite good so instead of repeating it here verbatim we would recommend reading the API documentation directly.
+Tracking which "phase" of the compiler type system operations are being performed in is done by the [`TypingMode`][tmode] enum.
+The documentation on the `TypingMode` enum is quite good so instead of repeating it here verbatim we would recommend reading the API documentation directly.
[penv]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.ParamEnv.html
[tenv]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TypingEnv.html
