Build a sysroot that supports C++ exceptions by default

This commit collects together some LLVM PRs, some changes in the build
configuration here, and some thoughts from #565 and related issues.
Specifically the changes here are:

* The patch for llvm/llvm-project#168449 is updated to its upstream
  (unlanded) form.
* Patches for the (landed) llvm/llvm-project#185770 and
  llvm/llvm-project#185775 are added.
* The `WASI_SDK_EXCEPTIONS` configuration is now either `ON`, `OFF`, or
  `DUAL`. The default depends on the version of Clang in use, where
  23.0.0+ (which isn't released officially yet) will be `DUAL` and
  otherwise it's `OFF`. CI for our custom-built patched toolchain
  defaults to `DUAL`.
* In `DUAL` mode libcxx is built twice into two different directories,
  once with exceptions and once without. This is supported by LLVM
  patches and means that Clang will select the right set of libraries
  based on compiler flags.

The end result here is that the produced toolchain from this repository,
by default, supports C++ exceptions. Additionally if exceptions-related
flags are not passed then the final binary will not use C++ exceptions
nor require the wasm exception-handling proposal.

There's still follow-up work from #565, such as:

* Subjectively it feels wordy to pass `-fwasm-exceptions` vs
  `-fexceptions`.
* Personally I think `-mllvm -wasm-use-legacy-eh=false` should become
  the default upstream.
* Subjectively I don't think that `-lunwind` should be necessary and it
  should be injected automatically with `-fwasm-exceptions` (or
  `-fexceptions`).
* Shared libraries for exceptions remain disabled due to build errors I
  do not personally know how to resolve.

I'll file follow-up issues for these once this has landed since they're
more minor compared to the main body of "anything works".

Closes #334
Closes #565

Author: alexcrichton

.github/workflows/main.yml

@@ -170,10 +170,16 @@ jobs:
       - uses: ./.github/actions/checkout
       - uses: ./.github/actions/install-deps
       - run: cargo install wasm-component-ld@0.5.21
-      - run: sudo apt-get update -y && sudo apt-get install -y clang-20 lld-20
+      - name: Install LLVM 22
+        run: |
+          wget -O - https://apt.llvm.org/llvm-snapshot.gpg.key | sudo apt-key add -
+          v=22
+          rel=$(lsb_release -cs)
+          sudo apt-add-repository "deb http://apt.llvm.org/$rel/ llvm-toolchain-$rel-$v main"
+          sudo apt-get update -y && sudo apt-get install -y clang-$v lld-$v
       - run: |
           cmake -G Ninja -B build -S . \
-            -DCMAKE_C_COMPILER=/usr/lib/llvm-20/bin/clang \
+            -DCMAKE_C_COMPILER=/usr/lib/llvm-22/bin/clang \
             -DCMAKE_SYSTEM_NAME=WASI \
             -DWASI_SDK_INCLUDE_TESTS=ON \
             -DWASI_SDK_CPU_CFLAGS="" \

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,43 @@ 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 as well as [resolving some upstream
+  issues](https://github.com/llvm/llvm-project/issues/188077).
+* 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.

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

ci/build.sh

@@ -37,6 +37,7 @@ cmake -G Ninja -B $build_dir/sysroot -S . \
   -DCMAKE_C_COMPILER_WORKS=ON \
   -DCMAKE_CXX_COMPILER_WORKS=ON \
   -DWASI_SDK_INCLUDE_TESTS=ON \
+  -DWASI_SDK_EXCEPTIONS=DUAL \
   "-DCMAKE_INSTALL_PREFIX=$build_dir/install"
 ninja -C $build_dir/sysroot install dist -v
 

cmake/wasi-sdk-sysroot.cmake

@@ -20,13 +20,28 @@ message(STATUS "Found executable for `ar`: ${CMAKE_AR}")
 
 find_program(MAKE make REQUIRED)
 
+set(EXCEPTIONS_DEFAULT "OFF")
+if(CMAKE_C_COMPILER_VERSION VERSION_GREATER_EQUAL 23.0.0)
+  set(EXCEPTIONS_DEFAULT "DUAL")
+endif()
+
 option(WASI_SDK_DEBUG_PREFIX_MAP "Pass `-fdebug-prefix-map` for built artifacts" ON)
 option(WASI_SDK_INCLUDE_TESTS "Whether or not to build tests by default" OFF)
 option(WASI_SDK_INSTALL_TO_CLANG_RESOURCE_DIR "Whether or not to modify the compiler's resource directory" OFF)
 option(WASI_SDK_LTO "Whether or not to build LTO assets" ON)
-option(WASI_SDK_EXCEPTIONS "Whether or not C++ exceptions are enabled" OFF)
+set(WASI_SDK_EXCEPTIONS "${EXCEPTIONS_DEFAULT}" CACHE STRING "Whether or not C++ exceptions are enabled")
 set(WASI_SDK_CPU_CFLAGS "-mcpu=lime1" CACHE STRING "CFLAGS to specify wasm features to enable")
 
+if ((WASI_SDK_EXCEPTIONS STREQUAL "DUAL") OR (WASI_SDK_EXCEPTIONS STREQUAL "ON"))
+  if(CMAKE_C_COMPILER_VERSION VERSION_LESS 22.0.0)
+    message(FATAL_ERROR "enabling C++ exceptions requires Clang 22 or later")
+  endif()
+elseif(WASI_SDK_EXCEPTIONS STREQUAL "OFF")
+  # No extra validation needed
+else()
+  message(FATAL_ERROR "unknown WASI_SDK_EXCEPTIONS value ${WASI_SDK_EXCEPTIONS}, expected one of: OFF, ON, DUAL")
+endif()
+
 set(wasi_tmp_install ${CMAKE_CURRENT_BINARY_DIR}/install)
 set(wasi_sysroot ${wasi_tmp_install}/share/wasi-sysroot)
 set(wasi_resource_dir ${wasi_tmp_install}/wasi-resource-dir)
@@ -225,7 +240,7 @@ execute_process(
   OUTPUT_VARIABLE llvm_version
   OUTPUT_STRIP_TRAILING_WHITESPACE)
 
-function(define_libcxx_sub target target_suffix extra_target_flags extra_libdir_suffix)
+function(define_libcxx_sub target target_suffix extra_target_flags extra_libdir_suffix exceptions)
   if(${target} MATCHES threads)
     set(pic OFF)
     set(target_flags -pthread)
@@ -251,7 +266,9 @@ function(define_libcxx_sub target target_suffix extra_target_flags extra_libdir_
     --sysroot ${wasi_sysroot}
     -resource-dir ${wasi_resource_dir})
 
-  if (WASI_SDK_EXCEPTIONS)
+  set(exnsuffix "")
+
+  if (exceptions)
     # TODO: lots of builds fail with shared libraries and `-fPIC`. Looks like
     # things are maybe changing in llvm/llvm-project#159143 but otherwise I'm at
     # least not really sure what the state of shared libraries and exceptions
@@ -260,6 +277,13 @@ function(define_libcxx_sub target target_suffix extra_target_flags extra_libdir_
     set(pic OFF)
     set(runtimes "libunwind;${runtimes}")
     list(APPEND extra_flags -fwasm-exceptions -mllvm -wasm-use-legacy-eh=false)
+    if (WASI_SDK_EXCEPTIONS STREQUAL "DUAL")
+      set(exnsuffix "/eh")
+    endif()
+  else()
+    if (WASI_SDK_EXCEPTIONS STREQUAL "DUAL")
+      set(exnsuffix "/noeh")
+    endif()
   endif()
 
   # The `wasm32-wasi` target is deprecated in clang, so ignore the deprecation
@@ -279,7 +303,7 @@ function(define_libcxx_sub target target_suffix extra_target_flags extra_libdir_
       ${default_cmake_args}
       # Ensure headers are installed in a target-specific path instead of a
       # target-generic path.
-      -DCMAKE_INSTALL_INCLUDEDIR=${wasi_sysroot}/include/${target}
+      -DCMAKE_INSTALL_INCLUDEDIR=${wasi_sysroot}/include/${target}${exnsuffix}
       -DCMAKE_STAGING_PREFIX=${wasi_sysroot}
       -DCMAKE_POSITION_INDEPENDENT_CODE=${pic}
       -DLIBCXX_ENABLE_THREADS:BOOL=ON
@@ -288,20 +312,20 @@ function(define_libcxx_sub target target_suffix extra_target_flags extra_libdir_
       -DLIBCXX_HAS_WIN32_THREAD_API:BOOL=OFF
       -DLLVM_COMPILER_CHECKED=ON
       -DLIBCXX_ENABLE_SHARED:BOOL=${pic}
-      -DLIBCXX_ENABLE_EXCEPTIONS:BOOL=${WASI_SDK_EXCEPTIONS}
+      -DLIBCXX_ENABLE_EXCEPTIONS:BOOL=${exceptions}
       -DLIBCXX_ENABLE_FILESYSTEM:BOOL=ON
       -DLIBCXX_ENABLE_ABI_LINKER_SCRIPT:BOOL=OFF
       -DLIBCXX_CXX_ABI=libcxxabi
       -DLIBCXX_HAS_MUSL_LIBC:BOOL=OFF
       -DLIBCXX_ABI_VERSION=2
-      -DLIBCXXABI_ENABLE_EXCEPTIONS:BOOL=${WASI_SDK_EXCEPTIONS}
+      -DLIBCXXABI_ENABLE_EXCEPTIONS:BOOL=${exceptions}
       -DLIBCXXABI_ENABLE_SHARED:BOOL=${pic}
       -DLIBCXXABI_SILENT_TERMINATE:BOOL=ON
       -DLIBCXXABI_ENABLE_THREADS:BOOL=ON
       -DLIBCXXABI_HAS_PTHREAD_API:BOOL=ON
       -DLIBCXXABI_HAS_EXTERNAL_THREAD_API:BOOL=OFF
       -DLIBCXXABI_HAS_WIN32_THREAD_API:BOOL=OFF
-      -DLIBCXXABI_USE_LLVM_UNWINDER:BOOL=${WASI_SDK_EXCEPTIONS}
+      -DLIBCXXABI_USE_LLVM_UNWINDER:BOOL=${exceptions}
       -DLIBUNWIND_ENABLE_SHARED:BOOL=${pic}
       -DLIBUNWIND_ENABLE_THREADS:BOOL=ON
       -DLIBUNWIND_USE_COMPILER_RT:BOOL=ON
@@ -310,9 +334,9 @@ function(define_libcxx_sub target target_suffix extra_target_flags extra_libdir_
       -DCMAKE_C_FLAGS=${extra_cflags}
       -DCMAKE_ASM_FLAGS=${extra_cflags}
       -DCMAKE_CXX_FLAGS=${extra_cxxflags}
-      -DLIBCXX_LIBDIR_SUFFIX=/${target}${extra_libdir_suffix}
-      -DLIBCXXABI_LIBDIR_SUFFIX=/${target}${extra_libdir_suffix}
-      -DLIBUNWIND_LIBDIR_SUFFIX=/${target}${extra_libdir_suffix}
+      -DLIBCXX_LIBDIR_SUFFIX=/${target}${exnsuffix}${extra_libdir_suffix}
+      -DLIBCXXABI_LIBDIR_SUFFIX=/${target}${exnsuffix}${extra_libdir_suffix}
+      -DLIBUNWIND_LIBDIR_SUFFIX=/${target}${exnsuffix}${extra_libdir_suffix}
       -DLIBCXX_INCLUDE_TESTS=OFF
       -DLIBCXX_INCLUDE_BENCHMARKS=OFF
 
@@ -327,30 +351,47 @@ function(define_libcxx_sub target target_suffix extra_target_flags extra_libdir_
     USES_TERMINAL_CONFIGURE ON
     USES_TERMINAL_BUILD ON
     USES_TERMINAL_INSTALL ON
+    USES_TERMINAL_PATCH ON
     PATCH_COMMAND
       ${CMAKE_COMMAND} -E chdir .. bash -c
         "git apply ${CMAKE_SOURCE_DIR}/src/llvm-pr-168449.patch || git apply ${CMAKE_SOURCE_DIR}/src/llvm-pr-168449.patch -R --check"
     COMMAND
       ${CMAKE_COMMAND} -E chdir .. bash -c
         "git apply ${CMAKE_SOURCE_DIR}/src/llvm-pr-186054.patch || git apply ${CMAKE_SOURCE_DIR}/src/llvm-pr-186054.patch -R --check"
+    COMMAND
+      ${CMAKE_COMMAND} -E chdir .. bash -c
+        "git apply ${CMAKE_SOURCE_DIR}/src/llvm-pr-185770.patch || git apply ${CMAKE_SOURCE_DIR}/src/llvm-pr-185770.patch -R --check"
   )
+  add_dependencies(libcxx-${target} libcxx-${target}${target_suffix}-build)
 endfunction()
 
-function(define_libcxx target)
-  define_libcxx_sub(${target} "" "" "")
-  if(WASI_SDK_LTO)
+function(define_libcxx_and_lto target target_suffix exceptions)
+  define_libcxx_sub(${target} "${target_suffix}" "" "" ${exceptions})
+  if (WASI_SDK_LTO)
     # Note: clang knows this /llvm-lto/${llvm_version} convention.
     # https://github.com/llvm/llvm-project/blob/llvmorg-18.1.8/clang/lib/Driver/ToolChains/WebAssembly.cpp#L204-L210
-    define_libcxx_sub(${target} "-lto" "-flto=full" "/llvm-lto/${llvm_version}")
+    define_libcxx_sub(${target} ${target_suffix}-lto "-flto=full" "/llvm-lto/${llvm_version}" ${exceptions})
+  endif()
+endfunction()
+
+function(define_libcxx target)
+  add_custom_target(libcxx-${target})
+
+  if (WASI_SDK_EXCEPTIONS STREQUAL "DUAL")
+    define_libcxx_and_lto(${target} "" OFF)
+    define_libcxx_and_lto(${target} "-exn" ON)
+  elseif(WASI_SDK_EXCEPTIONS STREQUAL "ON")
+    define_libcxx_and_lto(${target} "" ON)
+  else()
+    define_libcxx_and_lto(${target} "" OFF)
   endif()
 
   # As of this writing, `clang++` will ignore the target-specific include dirs
   # unless this one also exists:
   add_custom_target(libcxx-${target}-extra-dir
     COMMAND ${CMAKE_COMMAND} -E make_directory ${wasi_sysroot}/include/c++/v1
     COMMENT "creating libcxx-specific header file folder")
-  add_custom_target(libcxx-${target}
-    DEPENDS libcxx-${target}-build $<$<BOOL:${WASI_SDK_LTO}>:libcxx-${target}-lto-build> libcxx-${target}-extra-dir)
+  add_dependencies(libcxx-${target} libcxx-${target}-extra-dir)
 endfunction()
 
 foreach(target IN LISTS WASI_SDK_TARGETS)

cmake/wasi-sdk-toolchain.cmake

@@ -247,6 +247,9 @@ ExternalProject_Add(llvm-build
   USES_TERMINAL_CONFIGURE ON
   USES_TERMINAL_BUILD ON
   USES_TERMINAL_INSTALL ON
+  PATCH_COMMAND
+    ${CMAKE_COMMAND} -E chdir .. bash -c
+      "git apply ${CMAKE_SOURCE_DIR}/src/llvm-pr-185775.patch || git apply ${CMAKE_SOURCE_DIR}/src/llvm-pr-185775.patch -R --check"
 )
 
 add_custom_target(build ALL DEPENDS llvm-build)

src/llvm-pr-168449.patch

@@ -1,22 +1,17 @@
-diff --git a/libunwind/src/assembly.h b/libunwind/src/assembly.h
-index f8e83e138eff..c5097d25b0c6 100644
---- a/libunwind/src/assembly.h
-+++ b/libunwind/src/assembly.h
-@@ -249,6 +249,9 @@ aliasname:                                                                     \
- #define WEAK_ALIAS(name, aliasname)
- #define NO_EXEC_STACK_DIRECTIVE
- 
-+#elif defined(__wasm__)
-+#define NO_EXEC_STACK_DIRECTIVE
-+
- // clang-format on
- #else
- 
+From 852c8a2ebc0fdb1e781591e3e6e08d3a539bcfc3 Mon Sep 17 00:00:00 2001
+From: Yerzhan Zhamashev <yerzhan@novel.systems>
+Date: Wed, 21 Jan 2026 16:50:41 +0200
+Subject: [PATCH] libunwind: exclude __declspec from wasm build
+
+---
+ libunwind/src/config.h | 3 ++-
+ 1 file changed, 2 insertions(+), 1 deletion(-)
+
 diff --git a/libunwind/src/config.h b/libunwind/src/config.h
-index deb5a4d4d73d..23c9f012cbcf 100644
+index f017403fa2234..6014a37e27212 100644
 --- a/libunwind/src/config.h
 +++ b/libunwind/src/config.h
-@@ -66,7 +66,8 @@
+@@ -75,7 +75,8 @@
    #define _LIBUNWIND_EXPORT
    #define _LIBUNWIND_HIDDEN
  #else