yaze/docs/internal/wasm/build-guide.md

WASM Build Guide

This guide covers building the experimental WebAssembly version of YAZE.

Prerequisites

1. Emscripten SDK (emsdk)
   • Install from emscripten.org.
   • 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:

# 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.

# Use the helper script (Python based)
./scripts/serve-wasm.sh [port]

Or manually:

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.