BoltFFI BoltFFI

Packaging

Packaging takes your Rust library and produces artifacts ready for use in Xcode and Android Studio. A single command handles everything: compiling for each target architecture, generating bindings, and bundling the results into the format each platform expects.

Overview

The packaging process has three stages:

  1. Build - Compile your Rust library for each target architecture (arm64, x86_64, etc.)
  2. Generate - Create Swift/Kotlin bindings and C headers from your exported API
  3. Package - Bundle everything into platform-specific formats

For Apple, this produces an xcframework and SwiftPM package. For Android, this produces jniLibs and Kotlin sources. For WASM, this produces an npm package with TypeScript bindings.

Getting Started

Initialize your project with a configuration file:

boltffi init

This creates boltffi.toml with defaults. The minimal configuration is:

[package]
name = "mylib"

Your Cargo.toml needs the right crate types:

[lib]
crate-type = ["staticlib", "cdylib"]

Packaging All Platforms

Package each platform with its own command:

boltffi pack apple
boltffi pack android
boltffi pack wasm

Add --release for optimized builds:

boltffi pack apple --release
boltffi pack android --release
boltffi pack wasm --release

Or run the full pipeline (check, build, generate, pack) for all platforms at once:

boltffi release all

The output lands in dist/ with a subdirectory per platform:

dist/
├── apple/
│   ├── MyLib.xcframework/
│   │   ├── ios-arm64/
│   │   │   ├── Headers/
│   │   │   │   └── mylib.h
│   │   │   └── libmylib.a
│   │   ├── ios-arm64_x86_64-simulator/
│   │   │   ├── Headers/
│   │   │   │   └── mylib.h
│   │   │   └── libmylib.a
│   │   └── Info.plist
│   ├── Package.swift
│   └── Sources/
│       └── BoltFFI/
│           └── MyLibBoltFFI.swift
├── android/
│   ├── jniLibs/
│   │   ├── arm64-v8a/
│   │   │   └── libmylib.so
│   │   ├── armeabi-v7a/
│   │   │   └── libmylib.so
│   │   ├── x86/
│   │   │   └── libmylib.so
│   │   └── x86_64/
│   │       └── libmylib.so
│   └── kotlin/
│       └── com/example/mylib/
│           └── MyLib.kt
└── wasm/
    └── pkg/
        ├── mylib_bg.wasm
        ├── mylib.js
        ├── mylib.d.ts
        ├── bundler.js
        ├── web.js
        ├── node.js
        └── package.json

Step-by-Step Workflow

The boltffi pack command combines build, generate, and package steps. If you need more control, run each step separately:

Apple:

boltffi build apple --release
boltffi generate swift
boltffi generate header
boltffi pack apple --release --no-build

Android:

boltffi build android --release
boltffi generate kotlin
boltffi pack android --release --no-build

WASM:

boltffi build wasm --release
boltffi generate typescript
boltffi pack wasm --release --no-build

Use --no-build with pack when you’ve already built, to skip recompilation.

Apple Packaging

Package everything for iOS and iOS Simulator:

boltffi pack apple --release

This builds for arm64 (device) and arm64/x86_64 (simulator), generates Swift bindings and a C header, creates an xcframework, and generates a SwiftPM package.

Output Structure

dist/apple/
├── MyLib.xcframework/
│   ├── ios-arm64/
│   │   ├── Headers/
│   │   │   └── mylib.h
│   │   └── libmylib.a
│   ├── ios-arm64_x86_64-simulator/
│   │   ├── Headers/
│   │   │   └── mylib.h
│   │   └── libmylib.a
│   └── Info.plist
├── Package.swift
└── Sources/
    └── BoltFFI/
        └── MyLibBoltFFI.swift

The xcframework contains fat libraries for each platform slice. The SwiftPM package ties it all together with a binary target for the xcframework and a Swift target for the generated bindings.

Including macOS

To also build for macOS, add this to your boltffi.toml:

[targets.apple]
include_macos = true

Then run:

boltffi pack apple --release

The xcframework will include an additional macos-arm64_x86_64 slice.

SwiftPM Layouts

The layout option controls how the SwiftPM package is structured. Configure it in boltffi.toml:

[targets.apple.spm]
layout = "ffi-only"  # or "bundled" or "split"

ffi-only (default): Self-contained package with the xcframework and generated Swift. Import and use directly.

bundled: For existing Swift packages where you want to add generated bindings to your own wrapper target. Set wrapper_sources to your target’s source directory.

split: Binary-only package. The generated Swift is written to a separate location for you to include in your own package. Use this when you need full control over the Swift target.

See Configuration for the full list of options.

Using in Xcode

  1. In Xcode, go to File → Add Package Dependencies
  2. Click “Add Local…” and select the dist/apple directory
  3. Add the package to your target

Then import and use:

import MyLib

let result = someExportedFunction()

The package exposes a single module with your library name. All exported functions, classes, and types are available.

Remote Distribution

For distributing via GitHub releases or another host:

[targets.apple.spm]
distribution = "remote"
repo_url = "https://github.com/you/mylib/releases/download"

boltffi pack apple --release --version 1.0.0

This generates a Package.swift that points to a remote zip URL instead of a local path. Upload MyLib.xcframework.zip to your release, and consumers can add your package by URL.

Android Packaging

Package everything for Android:

boltffi pack android --release

This builds for all Android ABIs (arm64-v8a, armeabi-v7a, x86, x86_64), generates Kotlin bindings and JNI glue, and copies the shared libraries to jniLibs.

Output Structure

dist/android/
├── jniLibs/
│   ├── arm64-v8a/
│   │   └── libmylib.so
│   ├── armeabi-v7a/
│   │   └── libmylib.so
│   ├── x86/
│   │   └── libmylib.so
│   └── x86_64/
│       └── libmylib.so
└── kotlin/
    ├── com/
    │   └── example/
    │       └── mylib/
    │           └── MyLib.kt
    └── jni/
        └── jni_glue.c

The jniLibs folder follows the standard Android layout. Each ABI gets its own shared library. The Kotlin sources include your bindings and the JNI glue that connects them to the native code.

Using in Android Studio

  1. Copy dist/android/jniLibs to your app module’s src/main/ directory
  2. Copy the Kotlin sources from dist/android/kotlin/com/... to your source set
  3. Add the JNI glue to your native build (if using CMake or ndk-build)

Then import and use:

import com.example.mylib.*

val result = someExportedFunction()

Gradle Integration

If you’re using the Android Gradle Plugin with native support, point it at the jniLibs:

android {
    sourceSets {
        getByName("main") {
            jniLibs.srcDirs("src/main/jniLibs")
        }
    }
}

The shared libraries are loaded automatically when you first call into your Kotlin bindings.

WASM Packaging

Package everything for WebAssembly:

boltffi pack wasm --release

This compiles to wasm32-unknown-unknown, runs wasm-opt for size optimization, generates TypeScript bindings, and produces an npm package ready to publish or use locally.

Output Structure

dist/wasm/pkg/
├── wasm_demo_bg.wasm      # Compiled WASM binary
├── wasm_demo.js           # Generated bindings
├── wasm_demo.d.ts         # TypeScript declarations
├── bundler.js             # Entrypoint for bundlers (Vite, webpack)
├── web.js                 # Entrypoint for browsers
├── node.js                # Entrypoint for Node.js
├── package.json           # npm package manifest
└── README.md

Entrypoint Behavior

Each entrypoint handles WASM loading differently:

Core module (mylib.js):

  • Exports init(source: BufferSource | Response): Promise<void> for manual initialization
  • Exports all generated API functions
  • Functions throw Error if called before init() resolves

Loader entrypoints (bundler.js, web.js, node.js):

  • Export initialized: Promise<void> that resolves when WASM is ready
  • Export all generated API functions
  • Functions throw Error if called before initialized resolves

Loading strategy by entrypoint:

  • bundler.js - relies on bundler WASM asset handling (Vite, webpack)
  • web.js - loads WASM via fetch() from package-relative location
  • node.js - loads WASM via fs.readFile() from disk

Configuration

Set the npm package name in boltffi.toml:

[targets.wasm.npm]
package_name = "@myorg/mylib"
targets = ["bundler", "web", "nodejs"]

The targets array controls which entrypoints are generated. Include only what you need.

wasm-opt

By default, release builds run wasm-opt for size optimization:

[targets.wasm.optimize]
enabled = true
level = "s"          # optimize for size
strip_debug = true   # remove debug info

Set enabled = false during development for faster builds.

Using in a Bundler (Vite, webpack)

Install the package and import directly:

import { someExportedFunction, MyClass } from "@myorg/mylib";

const result = someExportedFunction();
const instance = MyClass.create();

Your bundler handles WASM loading automatically.

Using in Node.js

Import from the package and await initialization:

import { initialized, someExportedFunction } from "@myorg/mylib";

await initialized;
const result = someExportedFunction();

The initialized promise resolves once the WASM module is loaded and ready.

Using in a Browser (no bundler)

Use the web entrypoint with a script tag or dynamic import:

<script type="module">
  import init, { someExportedFunction } from "./pkg/web.js";
  
  await init();
  const result = someExportedFunction();
</script>

The init() function fetches the WASM file relative to the script location.

Package Exports

The generated package.json includes conditional exports for all enabled environments.

With all targets enabled (targets = ["bundler", "web", "nodejs"]):

{
  "name": "@myorg/mylib",
  "type": "module",
  "exports": {
    ".": {
      "types": "./mylib.d.ts",
      "browser": "./web.js",
      "node": "./node.js",
      "default": "./bundler.js"
    }
  }
}

With only Node.js (targets = ["nodejs"]):

{
  "exports": {
    ".": {
      "types": "./mylib.d.ts",
      "node": "./node.js",
      "default": "./node.js"
    }
  }
}

The default condition resolves to bundler.js if enabled, else web.js if enabled, else node.js.

Publishing to npm

Publish with:

cd dist/wasm/pkg
npm publish

Build Profiles

Debug builds are faster but produce larger, slower binaries:

boltffi pack apple           # debug
boltffi pack apple --release # optimized

Always use --release for distribution. Debug builds include symbols and skip optimizations, resulting in binaries 5-10x larger than release builds.

Skipping Steps

If you’ve already built and just want to repackage:

boltffi pack apple --no-build         # skip cargo build
boltffi pack apple --xcframework-only # skip SwiftPM package
boltffi pack apple --spm-only         # skip xcframework

Force regeneration of bindings:

boltffi pack apple --regenerate

These options are useful during development when iterating on specific parts of the pipeline.

Full Release Pipeline

For CI or final releases, run the complete pipeline:

boltffi release apple
boltffi release android
boltffi release wasm

Or build everything at once:

boltffi release all

The release command runs check, build, generate, and pack in sequence for the specified platform.