docs: wasm exceptions as the review left them

The README called an exception escaping main a trap. It is an uncaught
WebAssembly exception, and nothing prints its type or what(); the
README says so now. It also lists what a wasm build refuses and why,
says that setjmp needs -lsetjmp and that a longjmp across a noexcept
function ends the program, that a wasmtime older than 47 needs
-W exceptions=y, and that an old wasm-opt on PATH breaks release links.
It documents exit and park in a page from EnableWasiBrowserRuntime,
with the declaration of the park import.

The wasi example still sent Arch users to wasi-libc++, which has no
exception-enabled libraries. It asks for a wasi-sdk 33 sysroot or the
Flatpak now, and names the browsers a page needs. AGENTS.md notes that
the runtime test needs node, so it runs in the native loop and not in
CI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Jorijn van der Graaf 2026-10-31 06:10:41 +01:00
commit 3e125d83f0
Signed by: jorijnvdgraaf
GPG key ID: 2937E59CDCC1BCFB
3 changed files with 18 additions and 4 deletions

View file

@ -4,9 +4,14 @@ Build a C++26 program for the `wasm32-wasi` target and run it in a browser.
## Prerequisites
- `wasi-libc`, `wasi-libc++`, `wasi-libc++abi` (Arch packages — provide
`/usr/share/wasi-sysroot/`, which `crafter-build` finds automatically).
Other distros: install the WASI SDK and set `cfg.sysroot` in `project.cpp`.
- A WASI sysroot with the exception-enabled libc++, `lib/wasm32-wasip1/eh/`
from wasi-sdk 33 or later: wasm builds compile C++ exceptions and link those
libraries. The Flatpak bundles one, which `crafter-build` uses as it is.
Elsewhere, point `CRAFTER_BUILD_WASI_SYSROOT` at a wasi-sdk sysroot, or set
`cfg.sysroot` in `project.cpp`. Arch's `wasi-libc++` packages have no such
libraries, and the build stops with a message saying so.
- For the browser: WebAssembly exception handling, in Chrome 137, Firefox 131,
Safari 18.4 or newer.
## Build