d803bfe2b1
git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
197 lines
4.3 KiB
Markdown
197 lines
4.3 KiB
Markdown
# SONA NAPI-RS Build Instructions
|
|
|
|
## Overview
|
|
|
|
This document describes how to build the SONA Node.js native module from the Rust crate using NAPI-RS.
|
|
|
|
## Prerequisites
|
|
|
|
- Rust toolchain (1.70+)
|
|
- Node.js (16+)
|
|
- npm or yarn
|
|
- @napi-rs/cli
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
/workspaces/ruvector/
|
|
├── crates/sona/ # Rust crate
|
|
│ ├── src/
|
|
│ │ ├── napi_simple.rs # NAPI bindings
|
|
│ │ ├── engine.rs # Core engine
|
|
│ │ ├── lora.rs # LoRA implementations
|
|
│ │ ├── types.rs # Type definitions
|
|
│ │ └── ...
|
|
│ ├── Cargo.toml # Rust dependencies
|
|
│ └── build.rs # Build script
|
|
└── npm/packages/sona/ # NPM package
|
|
├── package.json # NPM configuration
|
|
├── index.js # JavaScript entry point
|
|
├── index.d.ts # TypeScript definitions
|
|
├── examples/ # Example scripts
|
|
└── test/ # Test files
|
|
```
|
|
|
|
## Build Steps
|
|
|
|
### 1. Build the Rust crate with NAPI feature
|
|
|
|
```bash
|
|
cd /workspaces/ruvector/crates/sona
|
|
cargo build --release --features napi
|
|
```
|
|
|
|
### 2. Build the Node.js module
|
|
|
|
```bash
|
|
cd /workspaces/ruvector/npm/packages/sona
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
This will:
|
|
- Install dependencies including `@napi-rs/cli`
|
|
- Build the native module for your platform
|
|
- Generate platform-specific `.node` files
|
|
|
|
### 3. Run tests
|
|
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
### 4. Run examples
|
|
|
|
```bash
|
|
node examples/basic-usage.js
|
|
node examples/custom-config.js
|
|
node examples/llm-integration.js
|
|
```
|
|
|
|
## NAPI-RS Configuration
|
|
|
|
The build is configured via `package.json`:
|
|
|
|
```json
|
|
{
|
|
"napi": {
|
|
"name": "sona",
|
|
"triples": {
|
|
"defaults": true,
|
|
"additional": [
|
|
"x86_64-unknown-linux-musl",
|
|
"aarch64-unknown-linux-gnu",
|
|
"armv7-unknown-linux-gnueabihf",
|
|
"aarch64-apple-darwin",
|
|
"x86_64-pc-windows-msvc",
|
|
"aarch64-pc-windows-msvc"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Cross-Compilation
|
|
|
|
To build for multiple platforms:
|
|
|
|
```bash
|
|
npm run build -- --target x86_64-unknown-linux-musl
|
|
npm run build -- --target aarch64-apple-darwin
|
|
npm run build -- --target x86_64-pc-windows-msvc
|
|
```
|
|
|
|
## Publishing
|
|
|
|
### Prepare for publishing
|
|
|
|
```bash
|
|
napi prepublish -t npm
|
|
```
|
|
|
|
### Create universal binary (macOS)
|
|
|
|
```bash
|
|
napi universal
|
|
```
|
|
|
|
### Publish to npm
|
|
|
|
```bash
|
|
npm publish
|
|
```
|
|
|
|
## API Differences from Rust
|
|
|
|
The NAPI bindings use a simplified API compared to the Rust API:
|
|
|
|
### Rust API (via `begin_trajectory`)
|
|
```rust
|
|
let builder = engine.begin_trajectory(embedding);
|
|
builder.add_step(activations, attention, reward);
|
|
engine.end_trajectory(builder, quality);
|
|
```
|
|
|
|
### Node.js API (via trajectory ID)
|
|
```javascript
|
|
const trajId = engine.beginTrajectory(embedding);
|
|
engine.addTrajectoryStep(trajId, activations, attention, reward);
|
|
engine.setTrajectoryRoute(trajId, "route");
|
|
engine.endTrajectory(trajId, quality);
|
|
```
|
|
|
|
This design avoids exposing the `TrajectoryBuilder` struct to JavaScript, which simplifies NAPI bindings.
|
|
|
|
## Troubleshooting
|
|
|
|
### Build fails with "could not find \`napi\`"
|
|
|
|
Ensure you're building with the `napi` feature:
|
|
```bash
|
|
cargo build --features napi
|
|
```
|
|
|
|
### Module not found at runtime
|
|
|
|
The native module must be built before running Node.js code:
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
### Platform-specific issues
|
|
|
|
Check that your Rust toolchain supports the target platform:
|
|
```bash
|
|
rustup target list
|
|
rustup target add <target-triple>
|
|
```
|
|
|
|
## Performance Notes
|
|
|
|
- The native module uses zero-copy for Float64Arrays where possible
|
|
- Global trajectory storage uses `OnceLock` for thread-safe initialization
|
|
- Mutex-protected HashMap for trajectory builders (minimal contention)
|
|
|
|
## Memory Management
|
|
|
|
- Trajectory builders are stored globally until `endTrajectory` is called
|
|
- Finished trajectories are automatically cleaned up
|
|
- No manual memory management required in JavaScript
|
|
|
|
## Feature Flags
|
|
|
|
The NAPI bindings respect these Cargo features:
|
|
|
|
- `napi` - Enable NAPI bindings (required)
|
|
- `serde-support` - Required by napi feature
|
|
- `simd` - Enable SIMD optimizations (optional, recommended)
|
|
|
|
Build with all features:
|
|
```bash
|
|
cargo build --release --features napi,simd
|
|
```
|
|
|
|
## License
|
|
|
|
MIT OR Apache-2.0
|