@ondeinference / onde

Code Commits Issues Pulls Cloud Agent CI/CD

feature/diffusion-vision

copilot/assess-inference-engine-complexity copilot/fix-onde-npm-sdk-v1-1-2-release development feature/diffusion-vision main

md 13.3 KB

View source Raw

name: sdk-swift-package description: Build the Onde Swift package (XCFramework) from Rust source using UniFFI and distribute it via a remote-binary Package.swift for Swift Package Index. Covers xcframework assembly, App Group shared container, models/hub cache convention, and the onde-swift release workflow. allowed-tools: Read, Write, Edit, Glob, Grep, Bash

user-invocable: true

Skill: Swift Package (XCFramework Distribution)

What this skill covers

Building the Onde Swift package from Rust source using UniFFI, assembling an XCFramework, and distributing it via a remote-binary Package.swift for Swift Package Index.

Repository layout

onde/
├── src/                         # Rust source (lib.rs, inference/, hf_cache.rs, whisper.rs)
├── sdk/Onde/                    # Output: generated Swift package (git-ignored locally)
│   ├── Package.swift
│   ├── Sources/Onde/            # UniFFI-generated onde.swift glue + header
│   └── OndeFramework.xcframework
├── uniffi-bindgen/              # onde's own uniffi-bindgen CLI binary
│   ├── Cargo.toml
│   └── uniffi-bindgen.rs        # fn main() { uniffi::uniffi_bindgen_main() }
├── uniffi.toml                  # UniFFI binding config (package_name, cdylib_name)
├── build.rs                     # Provides tvOS ___chkstk_darwin stub via cc
└── Cargo.toml                   # uniffi = "=0.31.0" — version MUST stay pinned

Key constraints

Constraint	Detail
UniFFI version	Pinned to `=0.31.0` in `Cargo.toml` and `uniffi-bindgen/Cargo.toml`. Never bump without coordinating with the Kotlin and Python SDKs.
tvOS targets	Tier-3 — require `cargo +nightly -Z build-std`. Stable toolchain is used for iOS/macOS.
tvOS linker	`___chkstk_darwin` is missing from tvOS libSystem. `build.rs` compiles `tvos_chkstk.s` as a no-op stub. This is automatic — do not remove it.
`cargo-swift`	Not required. The project owns its own `uniffi-bindgen` binary. Use it directly (same as `build-kotlin.sh` does for Android).
`.xcframework` in `Package.swift`	Published `Package.swift` must use remote `url:` + `checksum:` — never a local `path:`.
Swift package name	`Onde` (PascalCase). Git repo slug: `onde-swift` under the `ondeinference` org.
App Group ID	`group.com.ondeinference.apps` — shared across all Onde-powered apps (Flutter, Tauri, native Swift).
HF cache subdirectory	`<container>/models/hub/` — NOT `huggingface/hub/`. Must match the Tauri and Dart SDK convention.

Apple target triples

Slice	Triple	Toolchain
iOS device	`aarch64-apple-ios`	stable
iOS simulator (Intel)	`x86_64-apple-ios`	stable
iOS simulator (Apple Silicon)	`aarch64-apple-ios-sim`	stable
tvOS device	`aarch64-apple-tvos`	nightly + `-Z build-std`
tvOS simulator (Intel)	`x86_64-apple-tvos`	nightly + `-Z build-std`
tvOS simulator (Apple Silicon)	`aarch64-apple-tvos-sim`	nightly + `-Z build-std`
macOS (Apple Silicon)	`aarch64-apple-darwin`	stable
macOS (Intel)	`x86_64-apple-darwin`	stable

Build sequence (manual / CI)

1. Build the `uniffi-bindgen` CLI (host)

cargo build --manifest-path uniffi-bindgen/Cargo.toml --release
BINDGEN=uniffi-bindgen/target/release/uniffi-bindgen   # or workspace target/

2. Compile Rust staticlibs per Apple target

# Stable targets (iOS, macOS)
cargo build --target aarch64-apple-ios --release
cargo build --target x86_64-apple-ios --release
cargo build --target aarch64-apple-ios-sim --release
cargo build --target aarch64-apple-darwin --release
cargo build --target x86_64-apple-darwin --release

# Nightly targets (tvOS — tier 3)
cargo +nightly build -Z build-std \
    --target aarch64-apple-tvos --release
cargo +nightly build -Z build-std \
    --target x86_64-apple-tvos --release
cargo +nightly build -Z build-std \
    --target aarch64-apple-tvos-sim --release

3. lipo simulator slices

# iOS simulator fat lib
lipo -create \
    target/x86_64-apple-ios/release/libonde.a \
    target/aarch64-apple-ios-sim/release/libonde.a \
    -output /tmp/libonde-ios-sim.a

# tvOS simulator fat lib
lipo -create \
    target/x86_64-apple-tvos/release/libonde.a \
    target/aarch64-apple-tvos-sim/release/libonde.a \
    -output /tmp/libonde-tvos-sim.a

# macOS universal fat lib
lipo -create \
    target/aarch64-apple-darwin/release/libonde.a \
    target/x86_64-apple-darwin/release/libonde.a \
    -output /tmp/libonde-macos.a

4. Generate Swift bindings

mkdir -p sdk/Onde/Sources/Onde

$BINDGEN generate \
    --library target/aarch64-apple-ios/release/libonde.a \
    --language swift \
    --out-dir sdk/Onde/Sources/Onde \
    --config uniffi.toml

This produces onde.swift and ondeFFI.h (+ ondeFFI.modulemap).

5. Create the `.xcframework`

Each slice needs a headers directory alongside its .a:

HEADERS=sdk/Onde/Sources/Onde   # contains ondeFFI.h + ondeFFI.modulemap

xcodebuild -create-xcframework \
    -library target/aarch64-apple-ios/release/libonde.a      -headers $HEADERS \
    -library /tmp/libonde-ios-sim.a                          -headers $HEADERS \
    -library target/aarch64-apple-tvos/release/libonde.a     -headers $HEADERS \
    -library /tmp/libonde-tvos-sim.a                         -headers $HEADERS \
    -library /tmp/libonde-macos.a                            -headers $HEADERS \
    -output sdk/Onde/OndeFramework.xcframework

6. Zip and compute checksum

cd sdk/Onde
zip -r OndeFramework.xcframework.zip OndeFramework.xcframework
CHECKSUM=$(shasum -a 256 OndeFramework.xcframework.zip | cut -d ' ' -f1)
echo $CHECKSUM

7. Publish (two-repo strategy)

Upload OndeFramework.xcframework.zip as a GitHub Release asset on the Rust source repo.
In the ondeinference/onde-kit Swift-only repo, update Package.swift:
- url: → the GitHub Release asset download URL
- checksum: → the SHA-256 from step 6
Commit, tag the version (0.1.0, etc.), and push to onde-kit.
Swift Package Index indexes onde-kit on every new tag.

`Package.swift` (published form)

// swift-tools-version:5.5
import PackageDescription

let package = Package(
    name: "Onde",
    platforms: [
        .iOS(.v14),
        .macOS(.v12),
        .tvOS(.v13),
    ],
    products: [
        .library(name: "Onde", targets: ["Onde"])
    ],
    targets: [
        .binaryTarget(
            name: "OndeFramework",
            url: "https://github.com/ondeinference/onde-kit/releases/download/0.1.0/OndeFramework.xcframework.zip",
            checksum: "<sha256>"
        ),
        .target(
            name: "Onde",
            dependencies: [.target(name: "OndeFramework")]
        ),
    ]
)

UniFFI type map (Rust → Swift)

Rust type	UniFFI derive	Swift type
`ChatRole`	`uniffi::Enum`	`enum ChatRole`
`ChatMessage`	`uniffi::Record`	`struct ChatMessage`
`SamplingConfig`	`uniffi::Record`	`struct SamplingConfig`
`GgufModelConfig`	`uniffi::Record`	`struct GgufModelConfig`
`InferenceResult`	`uniffi::Record`	`struct InferenceResult`
`StreamChunk`	`uniffi::Record`	`struct StreamChunk`
`EngineStatus`	`uniffi::Enum`	`enum EngineStatus`
`EngineInfo`	`uniffi::Record`	`struct EngineInfo`
`InferenceError`	`uniffi::Error`	`enum OndeError : Error`
`OndeChatEngine`	`uniffi::Object`	`class OndeChatEngine`
`StreamChunkListener`	`callback_interface`	`protocol StreamChunkListener`

UniFFI compatibility rules: - Use u64/u32 instead of usize (UniFFI does not support usize). - Streaming is exposed as a free function (streamChatMessage) not an Object method — UniFFI 0.31 does not support callback_interface in Object method parameters. - Use concrete String parameters in OndeChatEngine methods — impl Into<String> does not cross the FFI boundary.

Swift API quick reference

import Onde

// Engine lifecycle
let engine = OndeChatEngine()
try await engine.loadDefaultModel(systemPrompt: "You are helpful.", sampling: nil)
try await engine.loadGgufModel(config: qwen251_5bConfig(), systemPrompt: nil, sampling: nil)
await engine.unloadModel()
let loaded: Bool = await engine.isLoaded()
let info: EngineInfo = await engine.info()

// Chat
let result: InferenceResult = try await engine.sendMessage(message: "Hello!")
let oneShot: InferenceResult = try await engine.generate(messages: [...], sampling: nil)

// History
let history: [ChatMessage] = await engine.history()
let removed: UInt64 = await engine.clearHistory()
await engine.pushHistory(message: userMessage(content: "..."))

// Streaming (free function, callback-based)
try await streamChatMessage(engine: engine, message: "Tell me a story.", listener: myHandler)

// Config free functions
defaultModelConfig()           // platform-appropriate default
qwen251_5bConfig()             // ~941 MB, iOS/tvOS/Android
qwen253bConfig()               // ~1.93 GB, macOS/desktop

// Sampling presets
defaultSamplingConfig()        // temp=0.7, top_p=0.95, max=512
deterministicSamplingConfig()  // temp=0.0
mobileSamplingConfig()         // temp=0.7, max=128

// Message constructors
systemMessage(content:)
userMessage(content:)
assistantMessage(content:)

App Group Shared Container & Cache Convention

All Onde-powered apps use the App Group group.com.ondeinference.apps to share downloaded models. The cache layout inside the shared container is:

<group container>/
├── models/          ← HF_HOME
│   └── hub/         ← HF_HUB_CACHE (GGUF files live here)
└── tmp/             ← TMPDIR (iOS sandbox restricts system TMPDIR)

Important: The subdirectory is models/, NOT huggingface/. This was chosen to be user-friendly when browsing the container in Finder/Files. All SDKs (Rust, Swift, Dart) and all app types (Tauri, Flutter, native) must use the same path or models won't be shared.

Swift setup (called once at app launch)

import Foundation

func setupInferenceEnvironment() {
    guard let container = FileManager.default.containerURL(
        forSecurityApplicationGroupIdentifier: "group.com.ondeinference.apps"
    ) else {
        // Fall back to app-private Application Support if App Group is unavailable.
        let appSupport = FileManager.default
            .urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
        setupHfCache(at: appSupport)
        return
    }
    setupHfCache(at: container)
}

private func setupHfCache(at base: URL) {
    let hfHome = base.appendingPathComponent("models")
    let hfHub  = hfHome.appendingPathComponent("hub")
    try? FileManager.default.createDirectory(at: hfHub, withIntermediateDirectories: true)

    setenv("HF_HOME",      hfHome.path, 1)
    setenv("HF_HUB_CACHE", hfHub.path,  1)

    let tmp = base.appendingPathComponent("tmp")
    try? FileManager.default.createDirectory(at: tmp, withIntermediateDirectories: true)
    setenv("TMPDIR", tmp.path, 1)
}

Entitlements required

Both iOS and macOS targets need the App Group entitlement:

<key>com.apple.security.application-groups</key>
<array>
    <string>group.com.ondeinference.apps</string>
</array>

The App Group must also be registered in the Apple Developer Portal under Identifiers → App Groups before Xcode can provision it.

Local development (Xcode)

Use the local path form during development — the remote binary form is only needed for distribution:

// Package.swift (local dev only — never commit to onde-kit)
.binaryTarget(name: "OndeFramework", path: "./OndeFramework.xcframework")

In Xcode: File → Add Package Dependencies → Add Local → select sdk/Onde/.

Common pitfalls

Pitfall	Fix
Local `path:` in published `Package.swift`	Always `url:` + `checksum:` in `onde-swift`
Stale checksum after rebuild	Always recompute `shasum -a 256` — never hardcode
Missing simulator slice	lipo `x86_64` + `aarch64-sim` before passing to `xcodebuild`
UniFFI version drift	Keep `uniffi = "=0.31.0"` in both `Cargo.toml` and `uniffi-bindgen/Cargo.toml`
tvOS build with stable toolchain	tvOS targets are tier-3; always use `cargo +nightly -Z build-std`
Empty `Sources/` in `onde-swift`	Copy the generated `onde.swift` (and header) into the repo on every release
`___chkstk_darwin` linker error	Ensure `tvos_chkstk.s` exists at crate root; `build.rs` compiles it automatically
Missing Metal toolchain (Xcode 26+)	Run `xcodebuild -downloadComponent MetalToolchain`, then `cargo clean -p mistralrs-quant`
Cache path mismatch (`huggingface/` vs `models/`)	All SDKs MUST use `<container>/models/hub/` — using `huggingface/hub/` means models are not shared across apps
App Group not working	Register `group.com.ondeinference.apps` in Apple Developer Portal → Identifiers → App Groups; enable App Groups capability on the App ID; add entitlement to the target
`CODE_SIGN_IDENTITY = "-"` blocks App Groups	Remove ad-hoc signing from project-level build settings; App Groups require a real development certificate
Android NDK `LD` on PATH breaks Xcode	Never `export LD=$TOOLCHAIN/bin/ld` globally — it hijacks Xcode's linker. Use Cargo's `.cargo/config.toml` for Android linker config

#user-invocable: true

#Skill: Swift Package (XCFramework Distribution)

#What this skill covers

#Repository layout

#Key constraints

#Apple target triples

#Build sequence (manual / CI)

#1. Build the uniffi-bindgen CLI (host)

#2. Compile Rust staticlibs per Apple target

#3. lipo simulator slices

#4. Generate Swift bindings

#5. Create the .xcframework

#6. Zip and compute checksum

#7. Publish (two-repo strategy)

#Package.swift (published form)

#UniFFI type map (Rust → Swift)

#Swift API quick reference

#App Group Shared Container & Cache Convention

#Swift setup (called once at app launch)

#Entitlements required

#Local development (Xcode)

#Common pitfalls