d803bfe2b1
git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
171 lines
4.2 KiB
Markdown
171 lines
4.2 KiB
Markdown
# SONA WASM Build Instructions
|
|
|
|
## Prerequisites
|
|
|
|
1. Install Rust and wasm32 target:
|
|
```bash
|
|
rustup target add wasm32-unknown-unknown
|
|
```
|
|
|
|
2. Install wasm-pack (recommended):
|
|
```bash
|
|
cargo install wasm-pack
|
|
```
|
|
|
|
## Building for WASM
|
|
|
|
### Option 1: Using wasm-pack (Recommended)
|
|
|
|
```bash
|
|
cd crates/sona
|
|
|
|
# For web (browser)
|
|
wasm-pack build --target web --features wasm --out-dir wasm-example/pkg
|
|
|
|
# For Node.js
|
|
wasm-pack build --target nodejs --features wasm
|
|
|
|
# For bundlers (webpack, rollup, etc.)
|
|
wasm-pack build --target bundler --features wasm
|
|
|
|
# Release build (optimized)
|
|
wasm-pack build --target web --features wasm --release --out-dir wasm-example/pkg
|
|
```
|
|
|
|
### Option 2: Using cargo directly
|
|
|
|
```bash
|
|
cd crates/sona
|
|
cargo build --target wasm32-unknown-unknown --features wasm --release
|
|
```
|
|
|
|
The WASM file will be at: `../../target/wasm32-unknown-unknown/release/sona.wasm`
|
|
|
|
## Running the Example
|
|
|
|
1. Build the WASM module:
|
|
```bash
|
|
cd crates/sona
|
|
wasm-pack build --target web --features wasm --out-dir wasm-example/pkg
|
|
```
|
|
|
|
2. Serve the example:
|
|
```bash
|
|
cd wasm-example
|
|
python3 -m http.server 8080
|
|
# Or use any static server
|
|
```
|
|
|
|
3. Open browser:
|
|
```
|
|
http://localhost:8080
|
|
```
|
|
|
|
## File Structure
|
|
|
|
After building, you'll have:
|
|
|
|
```
|
|
crates/sona/
|
|
├── src/
|
|
│ ├── lib.rs # Main library
|
|
│ ├── wasm.rs # WASM bindings
|
|
│ ├── engine.rs # SONA engine
|
|
│ ├── lora.rs # LoRA implementations
|
|
│ ├── trajectory.rs # Trajectory tracking
|
|
│ ├── ewc.rs # EWC++ implementation
|
|
│ ├── reasoning_bank.rs # Pattern storage
|
|
│ ├── types.rs # Core types
|
|
│ └── loops/ # Learning loops
|
|
├── wasm-example/
|
|
│ ├── index.html # Demo page
|
|
│ ├── index.js # Demo logic
|
|
│ ├── package.json # NPM config
|
|
│ └── pkg/ # Generated WASM package
|
|
│ ├── sona.js # JS bindings
|
|
│ ├── sona_bg.wasm # WASM binary
|
|
│ ├── sona.d.ts # TypeScript definitions
|
|
│ └── package.json # NPM package info
|
|
└── Cargo.toml # Rust config
|
|
```
|
|
|
|
## Optimizing Build Size
|
|
|
|
### 1. Use release profile
|
|
```bash
|
|
wasm-pack build --target web --features wasm --release
|
|
```
|
|
|
|
### 2. Enable wasm-opt (automatically done by wasm-pack)
|
|
The `wasm-release` profile in Cargo.toml is optimized for size:
|
|
```toml
|
|
[profile.wasm-release]
|
|
inherits = "release"
|
|
opt-level = "z" # Optimize for size
|
|
lto = true # Link-time optimization
|
|
codegen-units = 1 # Better optimization
|
|
panic = "abort" # Smaller panic handler
|
|
```
|
|
|
|
### 3. Use wasm-snip to remove panicking infrastructure
|
|
```bash
|
|
cargo install wasm-snip
|
|
wasm-snip target/wasm32-unknown-unknown/release/sona.wasm \
|
|
-o sona_snipped.wasm
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Build Errors
|
|
|
|
**Error: `getrandom` not found**
|
|
- Solution: Make sure the `wasm` feature is enabled, which includes `getrandom` with `js` feature.
|
|
|
|
**Error: Missing `wasm-bindgen`**
|
|
- Solution: Add `wasm-bindgen` to dependencies with the `wasm` feature.
|
|
|
|
### Runtime Errors
|
|
|
|
**Error: Memory allocation failed**
|
|
- Solution: Increase WASM memory limit in your environment.
|
|
|
|
**Error: Module not found**
|
|
- Solution: Make sure paths in `index.html` correctly point to `pkg/sona.js`.
|
|
|
|
## Performance Tips
|
|
|
|
1. **Use release builds** in production for better performance
|
|
2. **Enable SIMD** if targeting modern browsers (requires additional features)
|
|
3. **Lazy load** the WASM module to improve initial page load
|
|
4. **Use Web Workers** for heavy computations to avoid blocking UI
|
|
|
|
## NPM Publishing
|
|
|
|
To publish the WASM package to NPM:
|
|
|
|
```bash
|
|
cd crates/sona
|
|
wasm-pack build --target bundler --features wasm --release
|
|
wasm-pack publish
|
|
```
|
|
|
|
## Size Comparison
|
|
|
|
- **Debug build**: ~9MB
|
|
- **Release build**: ~2-3MB
|
|
- **Release + wasm-opt**: ~1-2MB
|
|
- **With all optimizations**: < 1MB
|
|
|
|
## Browser Compatibility
|
|
|
|
- **Chrome/Edge**: 91+ (full support)
|
|
- **Firefox**: 89+ (full support)
|
|
- **Safari**: 14.1+ (full support)
|
|
- **Node.js**: 16+ (with `--experimental-wasm-modules`)
|
|
|
|
## Next Steps
|
|
|
|
- See [README.md](./README.md) for API documentation
|
|
- Check [wasm-example/](./wasm-example/) for usage examples
|
|
- Read [API Reference](./docs/API.md) for detailed API docs
|