From b96bbc9597ebbda5556ea2d4533dc5e1b35fbf8e Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Wed, 11 Mar 2026 14:07:57 -0700 Subject: [PATCH] Update docs --- CppExceptions.md | 77 +++++++++++++++++++++++++++--------------------- README.md | 4 +-- 2 files changed, 45 insertions(+), 36 deletions(-) diff --git a/CppExceptions.md b/CppExceptions.md index 7ea1e2d..e996ca4 100644 --- a/CppExceptions.md +++ b/CppExceptions.md @@ -1,25 +1,17 @@ # Support for C++ Exceptions -The released artifacts for wasi-sdk at this time do not support C++ exceptions. -LLVM and Clang, however, have support for C++ exceptions in WebAssembly and this -is intended to serve as documentation of the current state of affairs of using -C++ exceptions. It should be noted though that the current status of C++ -exceptions support is not intended to be the final state of support, and this is -all continuing to be iterated on over time. +> **Note**: this documentation does not cover wasi-sdk-31, the latest version +> of wasi-sdk at this time. -## Building wasi-sdk with exceptions +From wasi-sdk-32 and onwards the artifacts produced by this repository support +compiling C++ code both with and without exceptions. The sysroot for wasm +targets contains two copies of the C++ standard library and headers -- one with +exceptions enabled and one with exceptions disabled. These are automatically +selected based on compilation flags. This means that wasi-sdk-produced binaries +can avoid using wasm exceptions entirely by disabling C++ exceptions, or C++ +exceptions can be enabled in which case wasm exceptions will be used. -When building the sysroot with wasi-sdk you can pass `-DWASI_SDK_EXCEPTIONS=ON` -to enable support for C++ exceptions. For example: - -```shell script -$ cmake -G Ninja -B build/sysroot -S . \ - -DCMAKE_TOOLCHAIN_FILE=$path/to/wasi-sdk-p1.cmake \ - -DWASI_SDK_EXCEPTIONS=ON -``` - -The C++ standard library will be compiled with support for exceptions for the -desired targets and the resulting sysroot supports using exceptions. +Currently the default is for C++ exceptions to be disabled. ## Compiling code with C++ exceptions @@ -36,25 +28,42 @@ This can be specified for example with: ```shell script $ export CFLAGS="-fwasm-exceptions -mllvm -wasm-use-legacy-eh=false" -$ export LDFLAGS="-lunwind" +$ export LDFLAGS="-fwasm-exceptions -lunwind" ``` -## Limitations +Note that `-fwasm-exceptions` must be present when linking to select the +correct C++ standard library to link. + +## Building wasi-sdk with exceptions -Currently C++ exceptions support in wasi-sdk does not support shared libraries. -Fixing this will require resolving some miscellaneous build issues in this -repository itself. +When building the sysroot with wasi-sdk you can pass `-DWASI_SDK_EXCEPTIONS=ON` +to enable support for C++ exceptions. For example: -## Future Plans +```shell script +$ cmake -G Ninja -B build/sysroot -S . \ + -DCMAKE_TOOLCHAIN_FILE=$path/to/wasi-sdk-p1.cmake \ + -DWASI_SDK_EXCEPTIONS=ON +``` + +The C++ standard library will be compiled with support for exceptions for the +desired targets and the resulting sysroot supports using exceptions. Note that +enabling C++ exceptions requires LLVM 22 or later. + +C++ exceptions are disabled by default for local builds. With a future release +of LLVM 23 the dual-sysroot nature will be on-by-default. + +## Limitations -There are a few tracking issues with historical discussion about C++ exceptions -support in wasi-sdk such as [#334](https://github.com/WebAssembly/wasi-sdk/issues/334) -and [#565](https://github.com/WebAssembly/wasi-sdk/issues/565). The major -remaining items are: +There are a few known limitations/bugs/todos around exceptions support in +wasi-sdk at this time: -* Figure out support for shared libraries. -* Determine how to ship a sysroot that supports both with-and-without - exceptions. -* Figure out how to avoid the need for extra compiler flags when using - exceptions. -* Figure out if a new wasm target is warranted. +* Currently C++ exceptions support in wasi-sdk does not support shared + libraries. Fixing this will require resolving some miscellaneous build + issues in this repository itself. +* Currently `-fwasm-exceptions` is a required flag to enable C++ exceptions. + It's unclear whethe `-fexceptions` should also be supported as a substitute. +* Currently LLVM defaults to using the legacy exception-handling proposal and + this will likely change in the future. Precompiled libraries for wasi-sdk are + all built with the standard exception-handlign proposal. +* Currently `-lunwind` is required when linking, but this may become automatic + in the future. diff --git a/README.md b/README.md index 7d28f69..7893c96 100644 --- a/README.md +++ b/README.md @@ -209,8 +209,8 @@ disabled in a configure step before building with WASI SDK. ## Notable Limitations -* C++ exceptions are disabled by default. For more information see - [CppExceptions.md]. +* C++ exceptions are disabled by default and require extra configuration to get + working, see [CppExceptions.md]. * C `setjmp`/`longjmp` require some extra configuration to get working, see [SetjmpLongjmp.md]. * Most targets do not support spawning a thread. Experimental support for