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:
parent
2a05b8e6fb
commit
3e125d83f0
3 changed files with 18 additions and 4 deletions
|
|
@ -192,5 +192,6 @@ Local builds are two scripts in `project.cpp`. Run them with the native binary:
|
|||
- A warning is printed only when its unit actually recompiles. A build with nothing to do is silent, which is not evidence that a warning is gone.
|
||||
- A std module source only compiles against the headers of its own libc++ release, and a sysroot does not always ship one (Alpine). The Flatpak therefore carries the sources of the release next to the bundled one under `share/crafter-build/libc++-modules/<major>/`, one `libcxx-<major>-modules` manifest module each. When the bundled LLVM is bumped, keep the release it leaves behind as such a module: sysroots on the stable distro stay on it for months. The native loop has no such directory; stage one by hand under `share/crafter-build/` to test against a foreign sysroot.
|
||||
- The wasm compile flags live in one place, `WasmBaselineFlags` in `Crafter.Build-Clang.cppm`: the std module and every unit have to agree on them, and `VariantId()` and the std PCM directory hash them, so a change rebuilds instead of mixing old and new BMIs. They enable C++ exceptions, so the link takes the exception-enabled libc++ and libunwind from the sysroot's `lib/<triple>/eh/` (wasi-sdk 33 and later). The Flatpak's sysroot has them and a distro's may not; where they are missing the wasm tests skip, so run those through the Flatpak. A browser page checks the engine with the `WasmBaselineProbes` named in `variants.json`.
|
||||
- `WasiBrowserRuntimeExit` runs `wasi-runtime/runtime.js` under node and skips where there is none. The Flatpak has no node, so CI never runs it: after touching `runtime.js`, run the suite in the native loop with node on `PATH`.
|
||||
- `VariantId()` names the output directory, so CI globs `bin/crafter.build-exe-<target>-<march>-*/` rather than predicting the hash. The hash includes the compiler, so after a toolchain update the previous variant's directories stay in `bin/` and `build/` until `clean`, and such a glob matches both.
|
||||
- The self-host build and `test` keep the dependency notes section of this very file. None of Crafter.Math, Crafter.Asset and Crafter.LintRules ships an `AGENTS.consumer.md` yet. Once one does, a build here can change AGENTS.md whenever that repository changes its notes, since all three are unpinned. The tree is then dirty, so the next build's `git describe --dirty` version differs, which is a new `crafter.build-lib` variant and a full rebuild. Commit the section to settle it.
|
||||
|
|
|
|||
Loading…
Reference in a new issue