Rollup merge of #157426 - tshepang:rdg-sync, r=tshepang

rustc-dev-guide subtree update

Subtree update of `rustc-dev-guide` to e99720b.

Created using https://github.com/rust-lang/josh-sync.

r? @ghost

Author: JonathanBrouwer

ci/sembr/Cargo.lock

@@ -1 +1 @@
-f2b291d902bfde7d7f209fc3a64908134bcef201
+49b19d32b9f01a5aa606f3bf2e90e6e0aa462c03

rust-version

@@ -28,7 +28,7 @@ The actual numbers will depend on your code.
 To confirm that your previous step worked, we will use llvm's `opt` tool. Find your path to the opt binary, with a path similar to `<some_dir>/rust/build/<x86/arm/...-target-triple>/ci-llvm/bin/opt`. If you build LLVM from source, you'll likely need to replace `ci-llvm` with `build`. Also find `llvmenzyme-21.<so/dll/dylib>` path, similar to `/rust/build/target-triple/enzyme/build/enzyme/llvmenzyme-21`. Please keep in mind that llvm frequently updates it's llvm backend, so the version number might be higher (20, 21, ...). Once you have both, run the following command:
 
 ```sh
-<path/to/opt> out.ll -load-pass-plugin=/path/to/build/<target-triple>/stage1/lib/libEnzyme-21.so -passes="enzyme" -enzyme-strict-aliasing=0  -s
+<path/to/opt> out.ll -load-pass-plugin=/path/to/build/<target-triple>/stage1/lib/libEnzyme-21.so -passes="enzyme" -enzyme-strict-aliasing=0  -S
 ```
 This command might fail for future versions or on your system, in which case you should replace libEnzyme-21.so with LLVMEnzyme-21.so. Look at the Enzyme docs for instructions on how to build it. You might need to also adjust how to build your LLVM version.
 
@@ -41,7 +41,7 @@ If you fail to get the same error, please open an issue in the rust repository.
 First find your `llvm-extract` binary, it's in the same folder as your opt binary. then run:
 
 ```sh
-<path/to/llvm-extract> -s --func=<name> --recursive --rfunc="enzyme_autodiff*" --rfunc="enzyme_fwddiff*" --rfunc=<fnc_called_by_enzyme> out.ll -o mwe.ll 
+<path/to/llvm-extract> -S --func=<name> --recursive --rfunc="enzyme_autodiff*" --rfunc="enzyme_fwddiff*" --rfunc=<fnc_called_by_enzyme> out.ll -o mwe.ll
 ```
 
 This command creates `mwe.ll`, a minimal working example.

src/autodiff/debugging.md

@@ -13,18 +13,13 @@ Please open an issue if you want to help enabling automatic builds for your pref
 
 ## Installation guide
 
-If you want to use `std::autodiff` and don't plan to contribute PR's to the project, then we recommend to just use your existing nightly installation and download the missing component.
-In the future, rustup will be able to do it for you.
-For now, you'll have to manually download and copy it.
-
-1) On our github repository, find the last merged PR: [`Repo`]
-2) Scroll down to the lower end of the PR, where you'll find a rust-bors message saying `Test successful` with a `CI` link.
-3) Click on the `CI` link, and grep for your target. E.g. `dist-x86_64-linux` or `dist-aarch64-llvm-mingw` and click `Load summary`.
-4) Under the `CI artifacts` section, find the `enzyme-nightly` artifact, download, and unpack it.
-5) Copy the artifact (libEnzyme-22.so for linux, libEnzyme-22.dylib for apple, etc.), which should be in a folder named `enzyme-preview`, to your rust toolchain directory. E.g. for linux: `cp  ~/Downloads/enzyme-nightly-x86_64-unknown-linux-gnu/enzyme-preview/lib/rustlib/x86_64-unknown-linux-gnu/lib/libEnzyme-22.so ~/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/lib`
-
-Apple support was temporarily reverted, due to downstream breakages.
-Please (currently) build it from source.
+If you want to use `std::autodiff` on Linux or Windows and don't plan to contribute PR's to the project, then we recommend to just use your existing nightly installation and download the missing component. Please run:
+
+```console
+rustup +nightly component add enzyme
+```
+
+Apple support was temporarily reverted, due to downstream breakages. Please build it from source till we can re-enable it.
 
 ## Installation guide for Nix user.
 

src/autodiff/installation.md

@@ -15,7 +15,7 @@ fn main() {
 }
 ```
 
-The detailed documentation for the `std::autodiff` module is available at [std::autodiff](https://doc.rust-lang.org/std/autodiff/index.html).
+The detailed documentation for the `std::autodiff` module is available at [std::autodiff](https://doc.rust-lang.org/nightly/std/autodiff/index.html).
 
 Differentiable programming is used in various fields like numerical computing, [solid mechanics][ratel], [computational chemistry][molpipx], [fluid dynamics][waterlily] or for Neural Network training via Backpropagation, [ODE solver][diffsol], [differentiable rendering][libigl], [quantum computing][catalyst], and climate simulations.
 
@@ -25,3 +25,12 @@ Differentiable programming is used in various fields like numerical computing, [
 [diffsol]: https://github.com/martinjrobins/diffsol
 [libigl]: https://github.com/alecjacobson/libigl-enzyme-example?tab=readme-ov-file#run
 [catalyst]: https://github.com/PennyLaneAI/catalyst
+
+
+`std::autodiff` is currently based on Enzyme, an LLVM based tool for automatic differentation. There are three main reasons for relying on compiler based autodiff:
+
+- **Usability**: Current autodiff crates do not support normal Rust programs. They either enforce a custom DSL, require the usage of library provided types (instead of e.g. slices or arrays), or are limited to scalar functions. Compiler based autodiff allows users to write normal Rust code, including arrays, slices, user-defined structs and enums, control flow, and more.
+- **Performance**: Most existing Rust autodiff approaches have a constant overhead per operation. This can easily be amortized for ML applications which have few expensive operations on large tensors. It is, however, often unacceptable for applications in the HPC or scientific computing field. By working on (optimized) LLVM IR, compiler based autodiff can achieve [significantly][Enzyme] better performance in those cases.
+- **Features**: By operating on such a low level and sharing the implementation with other LLVM based languages, we can leverage the large amount of work already done in the Enzyme project. For example, we can support Rust code calling MPI routines, or GPU code, including libraries like CuBLAS.
+
+[Enzyme]: https://dl.acm.org/doi/10.5555/3495724.3496770

src/autodiff/internals.md

@@ -45,6 +45,12 @@ git clone https://github.com/rust-lang/rust.git
 cd rust
 ```
 
+> **NOTE**: On Windows, antivirus scanning can make Git and build commands
+> noticeably slower in a large checkout. If that happens, consider adding only
+> the Rust checkout directory to the
+> [Windows Security exclusion list][windows-security-exclusions].
+> Avoid adding broader exclusions than needed.
+
 ### Partial clone the repository
 
 Due to the size of the repository, cloning on a slower internet connection can take a long time,
@@ -97,6 +103,7 @@ This chapter focuses on the basics to be productive, but
 if you want to learn more about `x.py`, [read this chapter][bootstrap].
 
 [bootstrap]: ./bootstrapping/intro.md
+[windows-security-exclusions]: https://support.microsoft.com/windows/add-an-exclusion-to-windows-security-811816c0-4dfd-af4a-47e4-c301afe13b26
 
 Also, using `x` rather than `x.py` is recommended as:
 
@@ -279,6 +286,16 @@ Instead, you can build a specific component by providing its name, like this:
 If you choose the `library` profile when running `x setup`, you can omit `--stage 1` (it's the
 default).
 
+If you want to build a tool, you can use:
+
+```bash
+./x build src/tools/cargo
+```
+
+You can also check the [the section on tool tests][tool-tests-link].
+
+[tool-tests-link]: ../tests/intro.md#tool-tests
+
 ## Creating a rustup toolchain
 
 Once you have successfully built `rustc`, you will have created a bunch

src/building/how-to-build-and-run.md

@@ -40,6 +40,12 @@ compiler toolchain. You can use it with rustup by linking it.
 rustup toolchain link stage1 build/host/stage1
 ```
 
+**NOTE**: If you use `./x setup tools`, the default stage will be set to 2 instead of 1.
+Adjust your command accordingly:
+```sh
+rustup toolchain link stage2 build/host/stage2
+```
+
 Now you have a toolchain called `stage1` linked to your build. You can use it to
 test the compiler.
 

src/building/quickstart.md

@@ -255,6 +255,9 @@ It is also perfectly fine
 (and even encouraged!) to use the CI to test your changes if it can help your productivity.
 In particular, we don't recommend running the full `./x test` suite locally,
 since it takes a very long time to execute.
+See the [Testing with CI] chapter for using Rust's CI to test your changes.
+
+[Testing with CI]: https://rustc-dev-guide.rust-lang.org/tests/ci.html#testing-with-ci
 
 ### r+
 

src/contributing.md

@@ -1,4 +1,3 @@
-<!-- date-check: Jul 2025 -->
 
 # Implementing new language features
 
@@ -191,7 +190,7 @@ The below steps needs to be followed in order to implement a new unstable featur
     If the feature gate is not set,
     you should either maintain the pre-feature behavior or raise an error,
     depending on what makes sense.
-    Errors should generally use [`rustc_session::parse::feature_err`].
+    Errors should generally use [`rustc_session::errors::feature_err`].
     For an example of adding an error, see [#81015].
 
    For features introducing new syntax, pre-expansion gating should be used instead.
@@ -221,7 +220,7 @@ The below steps needs to be followed in order to implement a new unstable featur
 
 [`GatedSpans`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/parse/struct.GatedSpans.html
 [#81015]: https://github.com/rust-lang/rust/pull/81015
-[`rustc_session::parse::feature_err`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/parse/fn.feature_err.html
+[`rustc_session::errors::feature_err`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/errors/fn.feature_err.html
 [`rustc_ast_passes::feature_gate::check_crate`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast_passes/feature_gate/fn.check_crate.html
 [value the stability of Rust]: https://github.com/rust-lang/rfcs/blob/master/text/1122-language-semver.md
 [stability in code]: #stability-in-code

src/implementing-new-features.md

@@ -76,23 +76,21 @@ If we can't make progress in an iteration, this represents a compile error.
            an AST, which may produce parse errors.
          - During expansion, we create [`SyntaxContext`]s (hierarchy 2) (see
            [Hygiene][hybelow] below).
-         - These three passes happen one after another on every AST fragment
+         - These two passes happen one after another on every AST fragment
            freshly expanded from a macro:
            - [`NodeId`]s are assigned by [`InvocationCollector`].
              This also collects new macro calls from this new AST piece and
              adds them to the queue.
-           - ["Def paths"][defpath] are created and [`DefId`]s are
-             assigned to them by [`DefCollector`].
-           - Names are put into modules (from the resolver's point of
-             view) by [`BuildReducedGraphVisitor`].
+           - [`DefCollector`] creates ["Def paths"][defpath], assigns the
+             corresponding [`DefId`]s, and also builds the reduced graph
+             (putting names into modules from the resolver's point of view).
       3. After expanding a single macro and integrating its output, continue
          to the next iteration of [`fully_expand_fragment`][fef].
    5. If it's not resolved:
       1. Put the macro back in the queue.
       2. Continue to next iteration...
 
 [`AstFragment`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_expand/expand/enum.AstFragment.html
-[`BuildReducedGraphVisitor`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_resolve/build_reduced_graph/struct.BuildReducedGraphVisitor.html
 [`DefCollector`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_resolve/def_collector/struct.DefCollector.html
 [`DefId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir/def_id/struct.DefId.html
 [`ExpnId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/hygiene/struct.ExpnId.html