112 lines
3.8 KiB
Markdown
112 lines
3.8 KiB
Markdown
|
# libghostty-vt WASM Build Guide
|
||
|
|
|
||
|
|
## Prerequisites
|
||
|
|
|
||
|
|
1. **Zig 0.13.0+** - Required for compiling to WebAssembly
|
||
|
|
|
||
|
|
### Install Zig
|
||
|
|
|
||
|
|
**Windows (PowerShell - Admin):**
|
||
|
|
```powershell
|
||
|
|
winget install Ziglang.Zig
|
||
|
|
```
|
||
|
|
|
||
|
|
**macOS:**
|
||
|
|
```bash
|
||
|
|
brew install zig
|
||
|
|
```
|
||
|
|
|
||
|
|
**Linux:**
|
||
|
|
```bash
|
||
|
|
wget https://github.com/ziglang/zig/releases/download/0.13.0/zig-linux-x86_64-0.13.0.tar.xz
|
||
|
|
tar -xf zig-linux-x86_64-0.13.0.tar.xz
|
||
|
|
sudo mv zig-linux-x86_64-0.13.0 /opt/zig
|
||
|
|
export PATH=$PATH:/opt/zig
|
||
|
|
```
|
||
|
|
|
||
|
|
## Build Steps
|
||
|
|
|
||
|
|
### 1. Navigate to ghostty directory
|
||
|
|
```bash
|
||
|
|
cd ghostty-web/lib/ghostty
|
||
|
|
```
|
||
|
|
|
||
|
|
### 2. Build libghostty-vt WASM
|
||
|
|
```bash
|
||
|
|
zig build lib-vt -Dtarget=wasm32-freestanding
|
||
|
|
```
|
||
|
|
|
||
|
|
This will produce:
|
||
|
|
- `lib/ghostty-vt.wasm` - The WASM binary
|
||
|
|
- Headers for C integration
|
||
|
|
|
||
|
|
### 3. Alternative: Build with custom options
|
||
|
|
```bash
|
||
|
|
zig build lib-vt \
|
||
|
|
-Dtarget=wasm32-freestanding \
|
||
|
|
-Doptimize=ReleaseSmall \
|
||
|
|
-Dwasm_shared=true
|
||
|
|
```
|
||
|
|
|
||
|
|
## Build Options
|
||
|
|
|
||
|
|
| Option | Description | Default |
|
||
|
|
|--------|-------------|---------|
|
||
|
|
| `-Dtarget` | Target architecture | `wasm32-freestanding` |
|
||
|
|
| `-Doptimize` | Optimization level | `ReleaseSmall` |
|
||
|
|
| `-Dwasm_shared` | Enable shared memory | `false` |
|
||
|
|
|
||
|
|
## Output Files
|
||
|
|
|
||
|
|
After building, the following files are generated:
|
||
|
|
- `zig-out/lib/` - Library files
|
||
|
|
- `zig-out/include/` - C headers
|
||
|
|
|
||
|
|
## Integration with Web Frontend
|
||
|
|
|
||
|
|
The WASM module exports C ABI functions. To use in browser:
|
||
|
|
|
||
|
|
1. Load the WASM module in JavaScript
|
||
|
|
2. Use WebAssembly.instantiate()
|
||
|
|
3. Call exported functions for VT parsing
|
||
|
|
4. Send parsed output to xterm.js for rendering
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
```
|
||
|
|
┌─────────────────────────────────────────────┐
|
||
|
|
│ Browser │
|
||
|
|
│ ┌─────────────┐ ┌──────────────────┐ │
|
||
|
|
│ │ JavaScript │◄──►│ ghostty-vt.wasm │ │
|
||
|
|
│ │ │ │ (VT Parser) │ │
|
||
|
|
│ └──────┬──────┘ └──────────────────┘ │
|
||
|
|
│ │ │
|
||
|
|
│ ▼ │
|
||
|
|
│ ┌─────────────────────────────────────┐ │
|
||
|
|
│ │ xterm.js (Rendering) │ │
|
||
|
|
│ └─────────────────────────────────────┘ │
|
||
|
|
└─────────────────────────────────────────────┘
|
||
|
|
▲
|
||
|
|
│ WebSocket
|
||
|
|
┌────────┴────────────────────────────────────┐
|
||
|
|
│ Backend Server │
|
||
|
|
│ ┌──────────────┐ ┌──────────────────┐ │
|
||
|
|
│ │ WebSocket │───►│ PTY (shell) │ │
|
||
|
|
│ └──────────────┘ └──────────────────┘ │
|
||
|
|
└─────────────────────────────────────────────┘
|
||
|
|
```
|
||
|
|
|
||
|
|
## Troubleshooting
|
||
|
|
|
||
|
|
### "wasm32-freestanding is not a valid target"
|
||
|
|
Make sure you have Zig 0.13.0 or later:
|
||
|
|
```bash
|
||
|
|
zig version
|
||
|
|
```
|
||
|
|
|
||
|
|
### "Unable to find wasm-rt"
|
||
|
|
The WASM runtime is included in `src/os/wasm.zig`. Make sure you're using the correct build command.
|
||
|
|
|
||
|
|
### Build succeeds but browser fails to load WASM
|
||
|
|
- Check that the WASM file is served with correct MIME type (`application/wasm`)
|
||
|
|
- Ensure CORS headers are set if loading from different origin
|