73 lines
2.5 KiB
Markdown
73 lines
2.5 KiB
Markdown
# WASM Build Guide
|
|
|
|
This guide covers building the experimental WebAssembly version of YAZE.
|
|
|
|
## Prerequisites
|
|
|
|
1. **Emscripten SDK (emsdk)**
|
|
* Install from [emscripten.org](https://emscripten.org/docs/getting_started/downloads.html).
|
|
* Activate the environment: `source path/to/emsdk/emsdk_env.sh`
|
|
2. **Ninja Build System**
|
|
* `brew install ninja` (macOS) or `apt-get install ninja-build` (Linux).
|
|
3. **Python 3** (for serving locally).
|
|
|
|
## Quick Build
|
|
|
|
Use the helper script for a one-step build:
|
|
|
|
```bash
|
|
# Build Release version (default)
|
|
./scripts/build-wasm.sh
|
|
|
|
# Build Debug version (with assertions and source maps)
|
|
./scripts/build-wasm.sh debug
|
|
|
|
# Build with AI runtime enabled (experimental)
|
|
./scripts/build-wasm.sh ai
|
|
```
|
|
|
|
The script handles:
|
|
1. CMake configuration using `emcmake`.
|
|
2. Compilation with `ninja`.
|
|
3. Packaging assets (`src/web` -> `dist/`).
|
|
4. Ensuring `coi-serviceworker.js` is placed correctly for SharedArrayBuffer support.
|
|
|
|
## Serving Locally
|
|
|
|
You **cannot** open `index.html` directly from the file system due to CORS and SharedArrayBuffer security requirements. You must serve it with specific headers.
|
|
|
|
```bash
|
|
# Use the helper script (Python based)
|
|
./scripts/serve-wasm.sh [port]
|
|
```
|
|
|
|
Or manually:
|
|
```bash
|
|
cd build-wasm/dist
|
|
python3 -m http.server 8080
|
|
```
|
|
*Note: The helper script sets the required `Cross-Origin-Opener-Policy` and `Cross-Origin-Embedder-Policy` headers.*
|
|
|
|
## Architecture
|
|
|
|
* **Entry Point:** `src/main_wasm.cpp` (or `src/main.cpp` with `__EMSCRIPTEN__` blocks).
|
|
* **Shell:** `src/web/index.html` template (populated by CMake/Emscripten).
|
|
* **Threading:** Uses `SharedArrayBuffer` and `pthread` pool. Requires HTTPS or localhost.
|
|
* **Filesystem:** Uses Emscripten's `IDBFS` mounted at `/home/web_user`. Data persists in IndexedDB.
|
|
|
|
## Troubleshooting
|
|
|
|
### "SharedArrayBuffer is not defined"
|
|
* **Cause:** Missing security headers.
|
|
* **Fix:** Ensure you are serving with `COOP: same-origin` and `COEP: require-corp`.
|
|
* **Check:** Is `coi-serviceworker.js` loading? It polyfills these headers for GitHub Pages (which doesn't support them natively yet).
|
|
|
|
### "Out of Memory" / "Asyncify" Crashes
|
|
* The build uses `ASYNCIFY` to support blocking calls (like `im_gui_loop`).
|
|
* If the stack overflows, check `ASYNCIFY_STACK_SIZE` in `CMakePresets.json`.
|
|
* Ensure infinite loops yield back to the browser event loop.
|
|
|
|
### "ReferenceError: _idb_... is not defined"
|
|
* **Cause:** Missing JS library imports.
|
|
* **Fix:** Check `CMAKE_EXE_LINKER_FLAGS` in `CMakePresets.json`. It should include `-lidbfs.js`.
|