From d2a7b4ca9538f22ac613a3296a9e140c16a431d4 Mon Sep 17 00:00:00 2001 From: shubham5080 Date: Tue, 7 Jul 2026 22:09:33 +0530 Subject: [PATCH 1/3] docs: add exception handling toolchain compatibility guide Signed-off-by: shubham5080 --- docs/develop/c/exception_handling.md | 43 ++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 docs/develop/c/exception_handling.md diff --git a/docs/develop/c/exception_handling.md b/docs/develop/c/exception_handling.md new file mode 100644 index 00000000..28d5fe1a --- /dev/null +++ b/docs/develop/c/exception_handling.md @@ -0,0 +1,43 @@ +--- +sidebar_position: 6 +--- + +# Exception Handling + +WasmEdge implements the [latest exception-handling proposal](https://github.com/WebAssembly/exception-handling) (post Oct 2023). Legacy EH instructions such as `delegate` are rejected at load time. + +Enable the proposal when running or compiling: + +```bash +wasmedge --enable-exception-handling module.wasm +wasmedge compile --enable-exception-handling module.wasm module.aot.wasm +``` + +## Toolchain compatibility + +| Toolchain | Compatible with WasmEdge EH | Notes | +|-----------|----------------------------|-------| +| Emscripten (`-fwasm-exceptions`) | No (as of 2026) | Often emits legacy EH (e.g. opcode `0x117` / `delegate`) | +| C/C++ via wasi-sdk / clang | Check your LLVM version | Must emit the latest EH proposal, not legacy EH | +| `wasm-3.0-exceptions` spec tests | Yes | Official test inputs used by WasmEdge | + +WasmEdge does not plan to support legacy EH. Use modules built for the current proposal only. + +## How WasmEdge tests EH + +CI runs the `wasm-3.0-exceptions` suite from [wasmedge-spectest](https://github.com/WasmEdge/wasmedge-spectest). See `test/spec/CMakeLists.txt` in the [WasmEdge](https://github.com/WasmEdge/WasmEdge) repository. + +To run a spec test locally after building tests, or fetch a `.wasm` from that repository: + +```bash +wasmedge --enable-exception-handling path/to/test.wasm +``` + +## Emscripten repro (expected failure today) + +```bash +emcc -O1 -fwasm-exceptions -sSTANDALONE_WASM a.cpp -o a.wasm +wasmedge --enable-exception-handling a.wasm +``` + +Example `a.cpp` and more detail: [examples/exception_handling](https://github.com/WasmEdge/WasmEdge/tree/master/examples/exception_handling) in the WasmEdge repository. From 7135b5acf46f10b2c16a4f18d16ad25a28b63fb5 Mon Sep 17 00:00:00 2001 From: shubham5080 Date: Wed, 8 Jul 2026 11:06:12 +0530 Subject: [PATCH 2/3] docs: list toolchain versions in EH compatibility table Signed-off-by: shubham5080 --- docs/develop/c/exception_handling.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/develop/c/exception_handling.md b/docs/develop/c/exception_handling.md index 28d5fe1a..7d73b77d 100644 --- a/docs/develop/c/exception_handling.md +++ b/docs/develop/c/exception_handling.md @@ -15,11 +15,12 @@ wasmedge compile --enable-exception-handling module.wasm module.aot.wasm ## Toolchain compatibility -| Toolchain | Compatible with WasmEdge EH | Notes | -|-----------|----------------------------|-------| -| Emscripten (`-fwasm-exceptions`) | No (as of 2026) | Often emits legacy EH (e.g. opcode `0x117` / `delegate`) | -| C/C++ via wasi-sdk / clang | Check your LLVM version | Must emit the latest EH proposal, not legacy EH | -| `wasm-3.0-exceptions` spec tests | Yes | Official test inputs used by WasmEdge | +| Toolchain | Version | Compatible | Notes | +|-----------|---------|------------|-------| +| WasmEdge (runtime) | 0.17.x | Yes | Latest EH proposal; use `--enable-exception-handling` | +| Emscripten (`-fwasm-exceptions`) | 3.1.64, 6.0.0 | No | Emits legacy EH (e.g. opcode `0x117` / `delegate`) | +| wasi-sdk / clang | None verified | No | No public wasi-sdk release verified to emit latest EH yet | +| `wasm-3.0-exceptions` spec tests | wasmedge-spectest | Yes | Official test inputs used by WasmEdge CI | WasmEdge does not plan to support legacy EH. Use modules built for the current proposal only. From a2e805e6d09b65920e79e191445116d939765381 Mon Sep 17 00:00:00 2001 From: shubham5080 Date: Wed, 8 Jul 2026 11:14:19 +0530 Subject: [PATCH 3/3] docs: move EH example into WasmEdge Book page Signed-off-by: shubham5080 --- docs/develop/c/exception_handling.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/develop/c/exception_handling.md b/docs/develop/c/exception_handling.md index 7d73b77d..577c2cb6 100644 --- a/docs/develop/c/exception_handling.md +++ b/docs/develop/c/exception_handling.md @@ -36,9 +36,26 @@ wasmedge --enable-exception-handling path/to/test.wasm ## Emscripten repro (expected failure today) +`a.cpp`: + +```cpp +#include + +int main() { + try { + puts("throw..."); + throw 1; + puts("(never reached)"); + } catch (...) { + puts("catch!"); + } + return 0; +} +``` + ```bash emcc -O1 -fwasm-exceptions -sSTANDALONE_WASM a.cpp -o a.wasm wasmedge --enable-exception-handling a.wasm ``` -Example `a.cpp` and more detail: [examples/exception_handling](https://github.com/WasmEdge/WasmEdge/tree/master/examples/exception_handling) in the WasmEdge repository. +Typical error: `loading failed: illegal opcode, Code: 0x117` (`Deprecated delegate instruction`).