Build a sysroot that supports C++ exceptions by default - #606
Merged
Conversation
This was referenced Mar 11, 2026
This commit collects together some LLVM PRs, some changes in the build configuration here, and some thoughts from WebAssembly#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 WebAssembly#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 WebAssembly#334 Closes WebAssembly#565
alexcrichton
force-pushed
the
exceptions
branch
from
March 30, 2026 14:48
b96bbc9 to
2f7a86e
Compare
ricochet
approved these changes
Mar 31, 2026
Co-authored-by: Joel Dice <joel.dice@akamai.com>
alexcrichton
enabled auto-merge (squash)
April 8, 2026 16:40
lewing
added a commit
to lewing/wasi-sdk
that referenced
this pull request
Apr 13, 2026
Enable C++ exceptions in the libc++/libc++abi/libunwind sysroot build. This is required for the CoreCLR WASM interpreter on WASI, which uses C++ exceptions for managed exception handling dispatch. Changes: - LIBCXX_ENABLE_EXCEPTIONS: OFF -> ON - LIBCXXABI_ENABLE_EXCEPTIONS: OFF -> ON - Add libunwind to LLVM_ENABLE_RUNTIMES - Add LIBCXXABI_USE_LLVM_UNWINDER, LIBUNWIND_ENABLE_SHARED, LIBUNWIND_USE_COMPILER_RT settings - Add -fwasm-exceptions to CMAKE_C_FLAGS and CMAKE_CXX_FLAGS This aligns with upstream wasi-sdk 33 (WebAssembly#606) which now builds exception-enabled sysroots by default. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This was referenced Apr 30, 2026
zah
added a commit
to metacraft-labs/aztec-packages
that referenced
this pull request
Aug 23, 2026
wasi-sdk 27 ships a sysroot whose libc++abi is built `-fno-exceptions`:
$ llvm-ar t share/wasi-sysroot/lib/wasm32-wasi/libc++abi.a
... cxa_exception_storage.cpp.o ... cxa_noexception.cpp.o ...
# cxa_exception.cpp.o and cxa_personality.cpp.o are ABSENT
So a wasm build that throws cannot link, with or without `-fwasm-exceptions`:
wasm-ld: error: undefined symbol: __cxa_allocate_exception
wasm-ld: error: undefined symbol: __cxa_throw
wasm-ld: error: undefined symbol: _Unwind_CallPersonality
That is why `cmake/arch.cmake` forces `-fno-exceptions` on every wasm build and
why `common/try_catch_shim.hpp` exists, with
#define try if (true)
#define catch(...) if (false)
under `BB_NO_EXCEPTIONS`. Those macros are a workaround for a toolchain
limitation, not a design choice, and they carry a latent hazard that has nothing
to do with any particular consumer: in a wasm build, *any* code that reaches a
`throw` — including third-party header-only libraries that were never audited
for it — runs `std::abort()` on the whole module, and any `catch` block written
to recover from it is compiled to `if (false)` and silently never runs.
wasi-sdk 33 (2026-04-30) builds "a sysroot that supports C++ exceptions by
default" (WebAssembly/wasi-sdk#606). The sysroot gains `eh/` and `noeh/`
multilib variants, and clang selects `eh/` when `-fwasm-exceptions` is passed.
This commit only moves the pin; it does not turn exceptions on anywhere. Nothing
about the shipped wasm build changes: `-fno-exceptions` and `BB_NO_EXCEPTIONS`
stay exactly as they are, so the artefact is built the same way. What changes is
that removing them becomes possible at all — a decision worth taking separately,
on its own cost/benefit.
Three things this needed beyond the version number:
* `cmake/threading.cmake` used `--target=wasm32-wasi-threads`. Clang has
deprecated that spelling, and `-Werror` makes the deprecation warning fatal,
so under wasi-sdk 33 every barretenberg translation unit in the `wasm-threads`
build fails on it and the build stops; the only units that get through are the
four FetchContent'd gtest/gmock ones, which are not compiled with `-Werror`.
Fixed to `wasm32-wasip1-threads`. Both spellings resolve to the same sysroot
directory, and `wasm32-wasip1-threads` exists in wasi-sdk 27's sysroot too, so
this is safe before and after the bump.
* `CMakePresets.json` set `"WASI_SDK_PREFIX": "/opt/wasi-sdk"` in the preset's
`environment` block, which *shadows* the ambient variable rather than
defaulting to it — the preset could only ever use `/opt/wasi-sdk`. It now uses
`$penv{WASI_SDK_PREFIX}`, and `/opt/wasi-sdk` is established as the default
where the SDK is installed (the build image, `bootstrap.sh`, and
`setup-container.sh`), so the no-argument behaviour is unchanged while a
toolchain installed elsewhere now works.
* `bootstrap.sh`'s toolchain check greps `/opt/wasi-sdk/VERSION` for
`$expected_abs_wasi_version`, so bumping that one variable is what makes CI
demand the new image.
Verified against `233d8e0993`:
* No native source, header, script or preset is touched, so native builds
cannot be affected. `git show --stat` is five files, all of them wasm
toolchain or container setup.
* The `wasm` preset builds to completion with wasi-sdk 33, sources unmodified:
200/200 targets, producing `barretenberg.wasm` and `ecc_tests`.
* The `wasm-threads` preset builds to completion with wasi-sdk 33 after the
triple fix. Without it, every barretenberg translation unit the build reaches
fails fatally on the deprecated triple and nothing fails for any other reason.
* `build-wasm-threads/bin/ecc_tests` — the binary CI runs — was built and run
with wasi-sdk 27 (unpatched triple) and with wasi-sdk 33 (patched):
1104 tests from 78 test suites, 1010 passed, exit 0 on both, with the two
transcripts identical line for line.
* An isolated probe confirms the exception situation in both directions:
wasi-sdk 27 fails to link a `throw`/`catch` for wasm32 with the three
undefined symbols above; wasi-sdk 33 links it and it runs correctly, on
wasmtime and on V8.
zah
added a commit
to metacraft-labs/aztec-packages
that referenced
this pull request
Aug 23, 2026
wasi-sdk 27 ships a sysroot whose libc++abi is built `-fno-exceptions`:
$ llvm-ar t share/wasi-sysroot/lib/wasm32-wasi/libc++abi.a
... cxa_exception_storage.cpp.o ... cxa_noexception.cpp.o ...
# cxa_exception.cpp.o and cxa_personality.cpp.o are ABSENT
So a wasm build that throws cannot link, with or without `-fwasm-exceptions`:
wasm-ld: error: undefined symbol: __cxa_allocate_exception
wasm-ld: error: undefined symbol: __cxa_throw
wasm-ld: error: undefined symbol: _Unwind_CallPersonality
That is why `cmake/arch.cmake` forces `-fno-exceptions` on every wasm build and
why `common/try_catch_shim.hpp` exists, with
#define try if (true)
#define catch(...) if (false)
under `BB_NO_EXCEPTIONS`. Those macros are a workaround for a toolchain
limitation, not a design choice, and they carry a latent hazard that has nothing
to do with any particular consumer: in a wasm build, *any* code that reaches a
`throw` — including third-party header-only libraries that were never audited
for it — runs `std::abort()` on the whole module, and any `catch` block written
to recover from it is compiled to `if (false)` and silently never runs.
wasi-sdk 33 (2026-04-30) builds "a sysroot that supports C++ exceptions by
default" (WebAssembly/wasi-sdk#606). The sysroot gains `eh/` and `noeh/`
multilib variants, and clang selects `eh/` when `-fwasm-exceptions` is passed.
This commit only moves the pin; it does not turn exceptions on anywhere. Nothing
about the shipped wasm build changes: `-fno-exceptions` and `BB_NO_EXCEPTIONS`
stay exactly as they are, so the artefact is built the same way. What changes is
that removing them becomes possible at all — a decision worth taking separately,
on its own cost/benefit.
Three things this needed beyond the version number:
* `cmake/threading.cmake` used `--target=wasm32-wasi-threads`. Clang has
deprecated that spelling, and `-Werror` makes the deprecation warning fatal,
so under wasi-sdk 33 every barretenberg translation unit in the `wasm-threads`
build fails on it and the build stops; the only units that get through are the
four FetchContent'd gtest/gmock ones, which are not compiled with `-Werror`.
Fixed to `wasm32-wasip1-threads`. Both spellings resolve to the same sysroot
directory, and `wasm32-wasip1-threads` exists in wasi-sdk 27's sysroot too, so
this is safe before and after the bump.
* `CMakePresets.json` set `"WASI_SDK_PREFIX": "/opt/wasi-sdk"` in the preset's
`environment` block, which *shadows* the ambient variable rather than
defaulting to it — the preset could only ever use `/opt/wasi-sdk`. It now uses
`$penv{WASI_SDK_PREFIX}`, and `/opt/wasi-sdk` is established as the default
where the SDK is installed (the build image, `bootstrap.sh`, and
`setup-container.sh`), so the no-argument behaviour is unchanged while a
toolchain installed elsewhere now works.
* `bootstrap.sh`'s toolchain check greps `/opt/wasi-sdk/VERSION` for
`$expected_abs_wasi_version`, so bumping that one variable is what makes CI
demand the new image.
Verified against `233d8e0993`:
* No native source, header, script or preset is touched, so native builds
cannot be affected. `git show --stat` is five files, all of them wasm
toolchain or container setup.
* The `wasm` preset builds to completion with wasi-sdk 33, sources unmodified:
200/200 targets, producing `barretenberg.wasm` and `ecc_tests`.
* The `wasm-threads` preset builds to completion with wasi-sdk 33 after the
triple fix. Without it, every barretenberg translation unit the build reaches
fails fatally on the deprecated triple and nothing fails for any other reason.
* `build-wasm-threads/bin/ecc_tests` — the binary CI runs — was built and run
with wasi-sdk 27 (unpatched triple) and with wasi-sdk 33 (patched):
1104 tests from 78 test suites, 1010 passed, exit 0 on both, with the two
transcripts identical line for line.
* An isolated probe confirms the exception situation in both directions:
wasi-sdk 27 fails to link a `throw`/`catch` for wasm32 with the three
undefined symbols above; wasi-sdk 33 links it and it runs correctly, on
wasmtime and on V8.
zah
added a commit
to metacraft-labs/aztec-packages
that referenced
this pull request
Aug 23, 2026
wasi-sdk 27 ships a sysroot whose libc++abi is built `-fno-exceptions`:
$ llvm-ar t share/wasi-sysroot/lib/wasm32-wasi/libc++abi.a
... cxa_exception_storage.cpp.o ... cxa_noexception.cpp.o ...
# cxa_exception.cpp.o and cxa_personality.cpp.o are ABSENT
So a wasm build that throws cannot link, with or without `-fwasm-exceptions`:
wasm-ld: error: undefined symbol: __cxa_allocate_exception
wasm-ld: error: undefined symbol: __cxa_throw
wasm-ld: error: undefined symbol: _Unwind_CallPersonality
That is why `cmake/arch.cmake` forces `-fno-exceptions` on every wasm build and
why `common/try_catch_shim.hpp` exists, with
#define try if (true)
#define catch(...) if (false)
under `BB_NO_EXCEPTIONS`. Those macros are a workaround for a toolchain
limitation, not a design choice, and they carry a latent hazard that has nothing
to do with any particular consumer: in a wasm build, *any* code that reaches a
`throw` — including third-party header-only libraries that were never audited
for it — runs `std::abort()` on the whole module, and any `catch` block written
to recover from it is compiled to `if (false)` and silently never runs.
wasi-sdk 33 (2026-04-30) builds "a sysroot that supports C++ exceptions by
default" (WebAssembly/wasi-sdk#606). The sysroot gains `eh/` and `noeh/`
multilib variants, and clang selects `eh/` when `-fwasm-exceptions` is passed.
This commit only moves the pin; it does not turn exceptions on anywhere. Nothing
about the shipped wasm build changes: `-fno-exceptions` and `BB_NO_EXCEPTIONS`
stay exactly as they are, so the artefact is built the same way. What changes is
that removing them becomes possible at all — a decision worth taking separately,
on its own cost/benefit.
Three things this needed beyond the version number:
* `cmake/threading.cmake` used `--target=wasm32-wasi-threads`. Clang has
deprecated that spelling, and `-Werror` makes the deprecation warning fatal,
so under wasi-sdk 33 every barretenberg translation unit in the `wasm-threads`
build fails on it and the build stops; the only units that get through are the
four FetchContent'd gtest/gmock ones, which are not compiled with `-Werror`.
Fixed to `wasm32-wasip1-threads`. Both spellings resolve to the same sysroot
directory, and `wasm32-wasip1-threads` exists in wasi-sdk 27's sysroot too, so
this is safe before and after the bump.
* `CMakePresets.json` set `"WASI_SDK_PREFIX": "/opt/wasi-sdk"` in the preset's
`environment` block, which *shadows* the ambient variable rather than
defaulting to it — the preset could only ever use `/opt/wasi-sdk`. It now uses
`$penv{WASI_SDK_PREFIX}`, and `/opt/wasi-sdk` is established as the default
where the SDK is installed (the build image, `bootstrap.sh`, and
`setup-container.sh`), so the no-argument behaviour is unchanged while a
toolchain installed elsewhere now works.
* `bootstrap.sh`'s toolchain check greps `/opt/wasi-sdk/VERSION` for
`$expected_abs_wasi_version`, so bumping that one variable is what makes CI
demand the new image.
Verified against `233d8e0993`:
* No native source, header, script or preset is touched, so native builds
cannot be affected. `git show --stat` is five files, all of them wasm
toolchain or container setup.
* The `wasm` preset builds to completion with wasi-sdk 33, sources unmodified:
200/200 targets, producing `barretenberg.wasm` and `ecc_tests`.
* The `wasm-threads` preset builds to completion with wasi-sdk 33 after the
triple fix. Without it, every barretenberg translation unit the build reaches
fails fatally on the deprecated triple and nothing fails for any other reason.
* `build-wasm-threads/bin/ecc_tests` — the binary CI runs — was built and run
with wasi-sdk 27 (unpatched triple) and with wasi-sdk 33 (patched):
1104 tests from 78 test suites, 1010 passed, exit 0 on both, with the two
transcripts identical line for line.
* An isolated probe confirms the exception situation in both directions:
wasi-sdk 27 fails to link a `throw`/`catch` for wasm32 with the three
undefined symbols above; wasi-sdk 33 links it and it runs correctly, on
wasmtime and on V8.
zah
added a commit
to metacraft-labs/aztec-packages
that referenced
this pull request
Aug 24, 2026
wasi-sdk 27 ships a sysroot whose libc++abi is built `-fno-exceptions`:
$ llvm-ar t share/wasi-sysroot/lib/wasm32-wasi/libc++abi.a
... cxa_exception_storage.cpp.o ... cxa_noexception.cpp.o ...
# cxa_exception.cpp.o and cxa_personality.cpp.o are ABSENT
So a wasm build that throws cannot link, with or without `-fwasm-exceptions`:
wasm-ld: error: undefined symbol: __cxa_allocate_exception
wasm-ld: error: undefined symbol: __cxa_throw
wasm-ld: error: undefined symbol: _Unwind_CallPersonality
That is why `cmake/arch.cmake` forces `-fno-exceptions` on every wasm build and
why `common/try_catch_shim.hpp` exists, with
#define try if (true)
#define catch(...) if (false)
under `BB_NO_EXCEPTIONS`. Those macros are a workaround for a toolchain
limitation, not a design choice, and they carry a latent hazard that has nothing
to do with any particular consumer: in a wasm build, *any* code that reaches a
`throw` — including third-party header-only libraries that were never audited
for it — runs `std::abort()` on the whole module, and any `catch` block written
to recover from it is compiled to `if (false)` and silently never runs.
wasi-sdk 33 (2026-04-30) builds "a sysroot that supports C++ exceptions by
default" (WebAssembly/wasi-sdk#606). The sysroot gains `eh/` and `noeh/`
multilib variants, and clang selects `eh/` when `-fwasm-exceptions` is passed.
This commit only moves the pin; it does not turn exceptions on anywhere. Nothing
about the shipped wasm build changes: `-fno-exceptions` and `BB_NO_EXCEPTIONS`
stay exactly as they are, so the artefact is built the same way. What changes is
that removing them becomes possible at all — a decision worth taking separately,
on its own cost/benefit.
Three things this needed beyond the version number:
* `cmake/threading.cmake` used `--target=wasm32-wasi-threads`. Clang has
deprecated that spelling, and `-Werror` makes the deprecation warning fatal,
so under wasi-sdk 33 every barretenberg translation unit in the `wasm-threads`
build fails on it and the build stops; the only units that get through are the
four FetchContent'd gtest/gmock ones, which are not compiled with `-Werror`.
Fixed to `wasm32-wasip1-threads`. Both spellings resolve to the same sysroot
directory, and `wasm32-wasip1-threads` exists in wasi-sdk 27's sysroot too, so
this is safe before and after the bump.
* `CMakePresets.json` set `"WASI_SDK_PREFIX": "/opt/wasi-sdk"` in the preset's
`environment` block, which *shadows* the ambient variable rather than
defaulting to it — the preset could only ever use `/opt/wasi-sdk`. It now uses
`$penv{WASI_SDK_PREFIX}`, and `/opt/wasi-sdk` is established as the default
where the SDK is installed (the build image, `bootstrap.sh`, and
`setup-container.sh`), so the no-argument behaviour is unchanged while a
toolchain installed elsewhere now works.
* `bootstrap.sh`'s toolchain check greps `/opt/wasi-sdk/VERSION` for
`$expected_abs_wasi_version`, so bumping that one variable is what makes CI
demand the new image.
Verified against `233d8e0993`:
* No native source, header, script or preset is touched, so native builds
cannot be affected. `git show --stat` is five files, all of them wasm
toolchain or container setup.
* The `wasm` preset builds to completion with wasi-sdk 33, sources unmodified:
200/200 targets, producing `barretenberg.wasm` and `ecc_tests`.
* The `wasm-threads` preset builds to completion with wasi-sdk 33 after the
triple fix. Without it, every barretenberg translation unit the build reaches
fails fatally on the deprecated triple and nothing fails for any other reason.
* `build-wasm-threads/bin/ecc_tests` — the binary CI runs — was built and run
with wasi-sdk 27 (unpatched triple) and with wasi-sdk 33 (patched):
1104 tests from 78 test suites, 1010 passed, exit 0 on both, with the two
transcripts identical line for line.
* An isolated probe confirms the exception situation in both directions:
wasi-sdk 27 fails to link a `throw`/`catch` for wasm32 with the three
undefined symbols above; wasi-sdk 33 links it and it runs correctly, on
wasmtime and on V8.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
WASI_SDK_EXCEPTIONSconfiguration is now eitherON,OFF, orDUAL. The default depends on the version of Clang in use, where 23.0.0+ (which isn't released officially yet) will beDUALand otherwise it'sOFF. CI for our custom-built patched toolchain defaults toDUAL.DUALmode 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:
-fwasm-exceptionsvs-fexceptions.-mllvm -wasm-use-legacy-eh=falseshould become the default upstream.-lunwindshould be necessary and it should be injected automatically with-fwasm-exceptions(or-fexceptions).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