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="" \

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,27 +351,44 @@ 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-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

@@ -182,6 +182,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

src/llvm-pr-185770.patch

@@ -0,0 +1,105 @@
+From d702761d9135ebbb83590d4dd1323be433701ebd Mon Sep 17 00:00:00 2001
+From: Alex Crichton <alex@alexcrichton.com>
+Date: Tue, 10 Mar 2026 15:49:55 -0700
+Subject: [PATCH] [WebAssembly] Move __cpp_exception to libunwind
+
+The `__cpp_exception` symbol is now defined in libunwind instead of
+compiler-rt. This is moved for a few reasons, but the primary reason is
+that compiler-rt is linked duplicate-ly into all shared objects meaning
+that it's not suitable for define-once symbols such as
+`__cpp_exception`. By moving the definition to the user of the symbol,
+libunwind itself, that guarantees that the symbol should be defined
+exactly once and only when appropriate. A secondary reason for this
+movement is that it avoids the need to compile compiler-rt twice: once
+with exception and once without, and instead the same build can be used
+for both exceptions-and-not.
+---
+ compiler-rt/lib/builtins/CMakeLists.txt       |  1 -
+ .../lib/builtins/wasm/__cpp_exception.S       | 26 -------------------
+ libunwind/src/Unwind-wasm.c                   | 15 +++++++++++
+ .../compiler-rt/lib/builtins/sources.gni      |  1 -
+ 4 files changed, 15 insertions(+), 28 deletions(-)
+ delete mode 100644 compiler-rt/lib/builtins/wasm/__cpp_exception.S
+
+diff --git a/compiler-rt/lib/builtins/CMakeLists.txt b/compiler-rt/lib/builtins/CMakeLists.txt
+index 6c27f6d4d529e..f0570a9092f40 100644
+--- a/compiler-rt/lib/builtins/CMakeLists.txt
++++ b/compiler-rt/lib/builtins/CMakeLists.txt
+@@ -891,7 +891,6 @@ set(s390x_SOURCES
+ 
+ set(wasm_SOURCES
+   wasm/__c_longjmp.S
+-  wasm/__cpp_exception.S
+   ${GENERIC_TF_SOURCES}
+   ${GENERIC_SOURCES}
+ )
+diff --git a/compiler-rt/lib/builtins/wasm/__cpp_exception.S b/compiler-rt/lib/builtins/wasm/__cpp_exception.S
+deleted file mode 100644
+index 0496e1dbf6158..0000000000000
+--- a/compiler-rt/lib/builtins/wasm/__cpp_exception.S
++++ /dev/null
+@@ -1,26 +0,0 @@
+-//===-- __cpp_exception.S - Implement __cpp_exception ---------------------===//
+-//
+-// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+-// See https://llvm.org/LICENSE.txt for license information.
+-// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-//
+-//===----------------------------------------------------------------------===//
+-//
+-// This file implements __cpp_exception which LLVM uses to implement exception
+-// handling when Wasm EH is enabled.
+-//
+-//===----------------------------------------------------------------------===//
+-
+-#ifdef __wasm_exception_handling__
+-
+-#ifdef __wasm64__
+-#define PTR i64
+-#else
+-#define PTR i32
+-#endif
+-
+-.globl __cpp_exception
+-.tagtype __cpp_exception PTR
+-__cpp_exception:
+-
+-#endif // !__wasm_exception_handling__
+diff --git a/libunwind/src/Unwind-wasm.c b/libunwind/src/Unwind-wasm.c
+index 2f4498c3f3989..c0ca9b775d244 100644
+--- a/libunwind/src/Unwind-wasm.c
++++ b/libunwind/src/Unwind-wasm.c
+@@ -69,6 +69,21 @@ _Unwind_RaiseException(_Unwind_Exception *exception_object) {
+   __builtin_wasm_throw(0, exception_object);
+ }
+ 
++// Define the `__cpp_exception` symbol which `__builtin_wasm_throw` above will
++// reference. This is defined here in `libunwind` as the single canonical
++// definition for this API and it's required for users to ensure that there's
++// only one copy of `libunwind` within a wasm module to ensure this is only
++// defined once and exactly once.
++__asm__(".globl __cpp_exception\n"
++#if defined(__wasm32__)
++        ".tagtype __cpp_exception i32\n"
++#elif defined(__wasm64__)
++        ".tagtype __cpp_exception i64\n"
++#else
++#error "Unsupported Wasm architecture"
++#endif
++        "__cpp_exception:\n");
++
+ /// Called by __cxa_end_catch.
+ _LIBUNWIND_EXPORT void
+ _Unwind_DeleteException(_Unwind_Exception *exception_object) {
+diff --git a/llvm/utils/gn/secondary/compiler-rt/lib/builtins/sources.gni b/llvm/utils/gn/secondary/compiler-rt/lib/builtins/sources.gni
+index 2ac71aa8e8367..c9eeede16e3eb 100644
+--- a/llvm/utils/gn/secondary/compiler-rt/lib/builtins/sources.gni
++++ b/llvm/utils/gn/secondary/compiler-rt/lib/builtins/sources.gni
+@@ -539,7 +539,6 @@ if (current_cpu == "ve") {
+ if (current_cpu == "wasm") {
+   builtins_sources += [
+     "wasm/__c_longjmp.S",
+-    "wasm/__cpp_exception.S",
+   ]
+ }
+