Support `-Cpanic=unwind` on WASI targets by alexcrichton · Pull Request #156061 · rust-lang/rust

alexcrichton · 2026-05-01T19:32:11Z

This commit is some minor updates/restructuring in a few locations with the end result being supporting -Cpanic=unwind on WASI targets. This continues to be off-by-default insofar as WASI targets default to -Cpanic=abort, meaning that actually using anything in this commit requires -Zbuild-std. Specifically the changes made here are:

The self-contained sysroot for WASI targets now contains a copy of libunwind.a from wasi-sdk, first shipped with wasi-sdk-33 (also updated here).
The unwind crate here in this repository uses the libunwind module instead of the custom bare-metal wasm implementation of exceptions. This means that Rust uses the _Unwind_* symbols which allows it to interoperate with C/C++/etc.
Wasm targets are all updated to pass the LLVM argument -wasm-use-legacy-eh=false to differ from LLVM's/clang's default of using the legacy exception handling proposal for WebAssembly. This has no effect by default because panic=abort is used on most targets. Emscripten is exempted from this as the Emscripten target is explicitly intended to follow LLVM's/clang's defaults.
There's a single test in the test suite that links to the panic_unwind crate which ended up requiring -Wexceptions from Wasmtime, so the test parts were updated and Wasmtime was updated in CI, too.

The net result of all of this is that this should not actually affect any WebAssembly target's default behavior. Optionally, though, WASI programs can be built with exception handling via:

RUSTFLAGS='-Cpanic=unwind' cargo +nightly run -Z build-std --target wasm32-wasip2

Effectively -Zbuild-std and -Cpanic=unwind is all that's necessary to enable this support on wasm targets.

Finally, this ends up closing #154593 as well. The WASI targets are now defined to use -lunwind to implement unwinding. This means that the in-tree definition of __cpp_exception is no longer of concern and the definition is always sourced externally. If Rust is linked with other C/C++ code using WASI then these idioms are compatible with wasi-sdk, for example, to use that as a linker. The main caveat is that when using an external linker the -fwasm-exceptions argument needs to be passed to clang for it to be able to find the libunwind.a library to link against.

Closes #154593

rustbot · 2026-05-01T19:32:14Z

These commits modify compiler targets.
(See the Target Tier Policy.)

rustbot · 2026-05-01T19:32:16Z

r? @marcoieni

rustbot has assigned @marcoieni.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

Owners of files modified in this PR: infra-ci
infra-ci expanded to Kobzol, Mark-Simulacrum, jdno, jieyouxu, marcoieni
Random selection from Mark-Simulacrum, jdno, jieyouxu, marcoieni

bjorn3 · 2026-05-03T15:08:23Z

+        // actually turned on, which it's not by default on this target. For
+        // `-Zbuild-std` builds, however, this affects when rebuilding libstd
+        // with unwinding.
+        llvm_args: cvs!["-wasm-use-legacy-eh=false"],


Isn't

rust/compiler/rustc_codegen_ssa/src/base.rs

Lines 369 to 375 in 54f67d2

// Returns `true` if this session's target will use native wasm

// exceptions. This means that the VM does the unwinding for

// us

pub fn wants_wasm_eh(sess: &Session) -> bool {

sess.target.is_like_wasm

&& (sess.target.os != Os::Emscripten || sess.opts.unstable_opts.emscripten_wasm_eh)

}

already supposed to do this?

Edit: Might be confused with wasm vs js exception handling.

View changes since the review

I believe, yeah, that's related to the Emscripten-specific scheme of exceptions pre-wasm-exceptions of using JS instead. Effectively there's 3 modes of exceptions on Wasm:

Historical JS-based support for Emscripten. That's used when wants_wasm_eh is false and is only applicable to historical versions of the Emscripten target (or -Zemscripten-wasm-eh=false)

Historical wasm support. This uses the now-legacy exception-handling proposal that shipped in browsers but was never standardized. This uses wasm instructions and has wants_wasm_eh is true. LLVM by default emits this today.

Modern wasm support. This uses the now-standard exception-handling proposal as the successor to the "legacy exceptions" of above. This is wants_wasm_eh is true plus an option to LLVM to use the new instructions.

For (1) the LLVM IR is different, and for (2) and (3) they're the same IR. I don't know much about (1) myself. For WASI this PR only exposes (3)

marcoieni · 2026-05-04T16:54:57Z

The changes in src/ci/docker look good. Someone else should review the other files since I'm not familiar with them.

alexcrichton · 2026-05-04T17:08:18Z

@bjorn3 would you be up for reviewing the non-infra-related bits?

bjorn3 · 2026-05-05T09:23:54Z

            && let Ok(mut path) = path.into_os_string().into_string()
        {
-            path.push_str(" run -C cache=n --dir .");
+            path.push_str(" run -Wexceptions -C cache=n --dir .");


There are no tests added that use exceptions, right?

View changes since the review

Almost yeah, but there's one test that does extern crate panic_unwind; which pulls in libunwind which pulls in a throw instruction which then needs this to validate

I'm surprised that even works without //@ needs-unwind to only run the test for panic=unwind. I thought rustc refused to link a panic runtime that doesn't match the -Cpanic=..., but I guess that check is only done when the panic runtime dependency is injected by rustc, not when it is explicitly done by the user.

This commit is some minor updates/restructuring in a few locations with the end result being supporting `-Cpanic=unwind` on WASI targets. This continues to be off-by-default insofar as WASI targets default to `-Cpanic=abort`, meaning that actually using anything in this commit requires `-Zbuild-std`. Specifically the changes made here are: * The self-contained sysroot for WASI targets now contains a copy of `libunwind.a` from wasi-sdk, first shipped with wasi-sdk-33 (also updated here). * The `unwind` crate here in this repository uses the `libunwind` module instead of the custom bare-metal wasm implementation of exceptions. This means that Rust uses the `_Unwind_*` symbols which allows it to interoperate with C/C++/etc. * Wasm targets are all updated to pass the LLVM argument `-wasm-use-legacy-eh=false` to differ from LLVM's/clang's default of using the legacy exception handling proposal for WebAssembly. This has no effect by default because `panic=abort` is used on most targets. Emscripten is exempted from this as the Emscripten target is explicitly intended to follow LLVM's/clang's defaults. * There's a single test in the test suite that links to the `panic_unwind` crate which ended up requiring `-Wexceptions` from Wasmtime, so the test parts were updated and Wasmtime was updated in CI, too. The net result of all of this is that this should not actually affect any WebAssembly target's default behavior. Optionally, though, WASI programs can be built with exception handling via: RUSTFLAGS='-Cpanic=unwind' cargo +nightly run -Z build-std --target wasm32-wasip2 Effectively `-Zbuild-std` and `-Cpanic=unwind` is all that's necessary to enable this support on wasm targets. Finally, this ends up closing 154593 as well. The WASI targets are now defined to use `-lunwind` to implement unwinding. This means that the in-tree definition of `__cpp_exception` is no longer of concern and the definition is always sourced externally. If Rust is linked with other C/C++ code using WASI then these idioms are compatible with wasi-sdk, for example, to use that as a linker. The main caveat is that when using an external linker the `-fwasm-exceptions` argument needs to be passed to `clang` for it to be able to find the `libunwind.a` library to link against. Closes 154593

rustbot · 2026-05-05T18:05:27Z

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

bjorn3 · 2026-05-06T08:11:04Z

@bors r+

rust-bors · 2026-05-06T08:11:08Z

📌 Commit 13c6e60 has been approved by bjorn3

It is now in the queue for this repository.

rustbot assigned marcoieni May 1, 2026

This comment has been minimized.

Sign in to view

alexcrichton force-pushed the unwinding-onw-asi branch from a960b56 to 3661ec1 Compare May 1, 2026 19:32

bjorn3 reviewed May 3, 2026

View reviewed changes

bjorn3 reviewed May 5, 2026

View reviewed changes

Comment thread library/unwind/src/libunwind.rs

bjorn3 reviewed May 5, 2026

View reviewed changes

Comment thread src/bootstrap/src/core/build_steps/compile.rs

bjorn3 reviewed May 5, 2026

View reviewed changes

alexcrichton force-pushed the unwinding-onw-asi branch from 3661ec1 to 13c6e60 Compare May 5, 2026 18:05

rust-bors Bot added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels May 6, 2026

	// Returns `true` if this session's target will use native wasm
	// exceptions. This means that the VM does the unwinding for
	// us
	pub fn wants_wasm_eh(sess: &Session) -> bool {
	sess.target.is_like_wasm
	&& (sess.target.os != Os::Emscripten \|\| sess.opts.unstable_opts.emscripten_wasm_eh)
	}

Uh oh!

Conversation

alexcrichton commented May 1, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rustbot commented May 1, 2026

Uh oh!

rustbot commented May 1, 2026

Uh oh!

This comment has been minimized.

bjorn3 May 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexcrichton May 4, 2026

Choose a reason for hiding this comment

Uh oh!

marcoieni commented May 4, 2026

Uh oh!

alexcrichton commented May 4, 2026

Uh oh!

Uh oh!

Uh oh!

bjorn3 May 5, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexcrichton May 5, 2026

Choose a reason for hiding this comment

Uh oh!

bjorn3 May 6, 2026

Choose a reason for hiding this comment

Uh oh!

rustbot commented May 5, 2026

Uh oh!

bjorn3 commented May 6, 2026

Uh oh!

rust-bors Bot commented May 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

alexcrichton commented May 1, 2026 •

edited by rustbot

Loading

bjorn3 May 3, 2026 •

edited

Loading

bjorn3 May 5, 2026 •

edited by rustbot

Loading