Write TPDE usage/debugging sections

src/SUMMARY.md

@@ -123,6 +123,9 @@
     - [How to debug](./autodiff/debugging.md)
     - [Autodiff flags](./autodiff/flags.md)
     - [Type Trees](./autodiff/type-trees.md)
+- [TPDE internals](./tpde/internals.md)
+    - [Installation](./tpde/installation.md)
+    - [How to debug](./tpde/debugging.md)
 
 # Source code representation
 

src/tpde/debugging.md

@@ -0,0 +1,25 @@
+# Debugging TPDE
+
+Bug reports and any other contributions are always welcome.
+Do note that this backend is experimental, so there are many features missing at the moment.
+Please ask on [Zulip](https://rust-lang.zulipchat.com/) for help if you get stuck or if our documentation is unclear.
+
+# Reporting crashes
+
+When using `-Z llvm-tpde=only`, you will likely see modules failing to compile due to certain LLVM IR features being unsupported by TPDE. An LLVM module should never fail to compile with `-Z llvm-tpde=try`, so if it does, this is a bug we would particularly appreciate knowing about.
+
+It is also conceivable that a program compiled with TPDE will compile successfully but crash at runtime due to an ABI mismatch with LLVM or other miscompilation. These bugs can be similarly minimized and reported, and are of high interest to the maintainers of the `rustc` TPDE integration. These cases are harder to debug, so your help is highly appreciated.
+
+# LLVM IR reproducer
+
+A failure to compile can usually be traced back to an unsupported IR feature. You can enable logging by setting the `TPDE_LOGGING` option to `ON` in `src/bootstrap/src/core/build_steps/llvm.rs`, which will print a message containing the offending IR.
+
+Having a minimal reproducer using this feature is extremely helpful. As TPDE-LLVM operates on LLVM IR, you can follow the instructions at [Debugging LLVM](../backend/debugging.md) to emit LLVM IR and minimize the Rust reproducer.
+
+# Report your bug
+
+- If the issue is due to an unsupported feature in TPDE, please create an issue at [https://github.com/tpde2/tpde/issues](https://github.com/tpde2/tpde/issues).
+  - The goal of TPDE is to support the most commonly used subset of LLVM IR features, so it is possible that the feature will not be added in the interest of avoiding excessive complexity.
+- If the issue is due to Rust emitting invalid LLVM IR or using TPDE incorrectly, please create an issue at [https://github.com/rust-lang/rust/issues](https://github.com/rust-lang/rust/issues).
+- If unsure, please ask on Zulip before opening an issue.
+- Please feel free to also add your rust code or a link to it.

src/tpde/installation.md

@@ -0,0 +1,29 @@
+# Installation
+
+TPDE is not currently distributed through `rustup`, and needs to be built locally. The TPDE backend is Linux-only.
+
+## Build instructions
+
+Follow the instructions at [How to build and run the compiler](../building/how-to-build-and-run.md) to clone the `rust-lang/rust` repository and set up a basic bootstrap configuration with the `compiler` profile.
+
+You will also need to enable `llvm.tpde = true` in `bootstrap.toml`, and, due to present limitations with the way LLVM is built, disable CI LLVM downloads with `llvm.download-ci-llvm = false`.
+
+Afterwards, linking the toolchain with rustup will allow you to use it through cargo:
+
+```console
+rustup toolchain link stage1 build/host/stage1
+# in other crate
+RUSTFLAGS="-Zllvm-tpde" cargo +stage1 build
+```
+
+You can then run the compiler test suite:
+
+```console
+./x test --stage 1 tests/ui --compiletest-rustc-args="-Zllvm-tpde" # or -Zllvm-tpde=only
+./x test --stage 1 tests/run-make --compiletest-rustc-args="-Zllvm-tpde" # or -Zllvm-tpde=only
+```
+
+## Build instruction for TPDE itself
+
+Following the Rust build instructions above will build the TPDE library used by the Rust compiler.
+However, if working directly on TPDE, the [TPDE docs](https://docs.tpde.org/) have instructions on how to build TPDE and run its test suite, which is not exercised by bootstrap.

src/tpde/internals.md

@@ -0,0 +1,11 @@
+TPDE-LLVM is an alternative LLVM codegen backend which aims to compile code significantly faster than LLVM while maintaining performance comparable to LLVM with `-O0`. It was introduced as part of a 2026 project goal, A[dd an experimental TPDE compilation option](https://goals.rust-lang.org/2026/tpde.html).
+
+`rustc` has an experimental TPDE-LLVM backend option which can be used to improve compile times for debug builds. TPDE is currently missing the "long tail" of features supported by LLVM, but `rustc` supports falling back to regular LLVM codegen if TPDE fails.
+
+# Supported `RUSTFLAGS`
+
+To control the usage of TPDE-LLVM as the codegen backend, use the `-Z llvm-tpde` rustc flag (which can be passed to cargo via `RUSTFLAGS`). The valid options are:
+
+- `<not set>`: use LLVM normally as the codegen backend. TPDE is not used
+- `-Zllvm-tpde`, `-Zllvm-tpde=try`: attempt to compile with TPDE-LLVM, but fall back to LLVM if unsupported IR is encountered
+- `-Zllvm-tpde=only`: attempt to compile with TPDE-LLVM, and bail if unsupported IR is encountered

src/traits/hrtb.md

@@ -52,7 +52,7 @@ replace the bound region in the obligation with a placeholder, yielding
 Note that we now have no quantifiers;
 in terms of the compiler type, this changes from a `ty::PolyTraitRef`
 to a `TraitRef`. We would then create the `TraitRef` from the impl,
-using fresh variables for it's bound regions (and thus getting
+using fresh variables for its bound regions (and thus getting
 `Foo<&'$a isize>`, where `'$a` is the inference variable for `'a`).
 
 2. Next