From aadf600574a3b72a3ba53723f8a6f498557b297f Mon Sep 17 00:00:00 2001
From: Alex Crichton <alex@alexcrichton.com>
Date: Wed, 6 May 2026 14:41:52 -0700
Subject: [PATCH] Document wasi-sdk minimum versions for WASI targets

This commit updates the documentation for WASI targets in the rustc book
to mention a minimum version of wasi-sdk that's required.

Closes 155971
---
 .../src/platform-support/wasm32-wasip1.md     | 19 +++++++++++----
 .../src/platform-support/wasm32-wasip2.md     | 23 ++++++++-----------
 2 files changed, 24 insertions(+), 18 deletions(-)

diff --git a/src/doc/rustc/src/platform-support/wasm32-wasip1.md b/src/doc/rustc/src/platform-support/wasm32-wasip1.md
index eb74edda22de..16499659291a 100644
--- a/src/doc/rustc/src/platform-support/wasm32-wasip1.md
+++ b/src/doc/rustc/src/platform-support/wasm32-wasip1.md
@@ -70,17 +70,16 @@ be used instead.
 
 [`wasi-libc`]: https://github.com/WebAssembly/wasi-libc
 
-## Building the target
+## Building the target in rustc
 
-To build this target first acquire a copy of
-[`wasi-sdk`](https://github.com/WebAssembly/wasi-sdk/). At this time version 22
-is the minimum needed.
+To build this target first acquire a copy of [`wasi-sdk`]. At this time version
+33 is the minimum needed.
 
 Next configure the `WASI_SDK_PATH` environment variable to point to where this
 is installed. For example:
 
 ```text
-export WASI_SDK_PATH=/path/to/wasi-sdk-22.0
+export WASI_SDK_PATH=/path/to/wasi-sdk-33.0
 ```
 
 Next be sure to enable LLD when building Rust from source as LLVM's `wasm-ld`
@@ -103,6 +102,16 @@ Rust programs can be built for that target:
 rustc --target wasm32-wasip1 your-code.rs
 ```
 
+The `wasm32-wasip1` toolchain comes with a self-contained sysroot meaning that
+no external compiler is required when building for this target. Users which
+build a `staticlib`, however, or use an external `-Clinker`, are recommended to
+use [`wasi-sdk`]. The minimum version required of [`wasi-sdk`] will change over
+time as it's updated in Rust and Rust relies on newer features that [`wasi-sdk`]
+has. See the documentation above about building the target in rustc for the
+minimum known working version.
+
+[`wasi-sdk`]: https://github.com/WebAssembly/wasi-sdk
+
 ## Cross-compilation
 
 This target can be cross-compiled from any hosts.
diff --git a/src/doc/rustc/src/platform-support/wasm32-wasip2.md b/src/doc/rustc/src/platform-support/wasm32-wasip2.md
index 861083ad4a61..4b7e84d71576 100644
--- a/src/doc/rustc/src/platform-support/wasm32-wasip2.md
+++ b/src/doc/rustc/src/platform-support/wasm32-wasip2.md
@@ -27,23 +27,20 @@ are required to support components since this target outputs a component as
 opposed to a core wasm module. As of the time of this writing Wasmtime 17 and
 above is able to run this target natively with no extra flags.
 
-## Building the target
+## Building the target in rustc
 
-To build this target first acquire a copy of
-[`wasi-sdk`](https://github.com/WebAssembly/wasi-sdk/). At this time version 22
-is the minimum needed.
+See the documentation for the [building the `wasm32-wasip1` target in
+rustc](./wasm32-wasip1.md#building-the-target-in-rustc) for more information. The tl;dr;
+is that [`wasi-sdk`] is required, and the `wasm32-wasip1` target documents the
+minimum version required.
 
-Next configure the `WASI_SDK_PATH` environment variable to point to where this
-is installed. For example:
+[`wasi-sdk`]: https://github.com/WebAssembly/wasi-sdk
 
-```text
-export WASI_SDK_PATH=/path/to/wasi-sdk-22.0
-```
+## Building Rust programs
 
-Next be sure to enable LLD when building Rust from source as LLVM's `wasm-ld`
-driver for LLD is required when linking WebAssembly code together. Rust's build
-system will automatically pick up any necessary binaries and programs from
-`WASI_SDK_PATH`.
+For more information see the documentation [`wasm32-wasip1`
+target](./wasm32-wasip1.md#building-rust-programs). Replace `wasm32-wasip1`
+target strings with `wasm32-wasip2`, however.
 
 ## Testing