UniFFI Packaging and Versioning

Turn one UniFFI crate into Android and Apple artifacts. Keep the checked-in generated bindings and the compiled library at the same revision, so that a bindings/library mismatch never reaches a device.

Verify with these checks

A host cargo check or cargo test proves none of these claims.

Failure triage

Checksums and the record-field gap

Generated Kotlin and Swift embed one API checksum per exported function, constructor, and method, plus a contract version. When the comparison with the loaded library runs depends on the language:

• Swift checks at the first call into the library and calls fatalError on a mismatch.
• Kotlin on UniFFI 0.30.0–0.32.2 checks only inside uniffiEnsureInitialized(). A single-crate binding never calls it, so a stale binding runs without an error, and omit_checksums = false proves nothing. Call uniffiEnsureInitialized() from the generated package (default uniffi.<namespace>) once at startup, from the adapter module, before the first binding call. Upstream main fixes this, but no release has the fix as of 2026-09.
• Kotlin failure shape. The check throws in a static initializer. Read the cause of the first ExceptionInInitializerError; the later NoClassDefFoundError (triage table) is a follow-on, not R8 stripping and not a missing JNA.

A hard failure is the good case.

A record or enum enters a checksum only by its name. A field or variant change therefore leaves every checksum unchanged (uniffi-rs #1789). When new bindings expect an added field and the library is stale, deserialization runs out of RustBuffer data. In the other direction, stale bindings get an extra encoded field and reject or ignore it, depending on the generated reader. A reorder of two fields of the same type is the worst case: both sides read the same shape and assign values to the wrong fields, with no error.

Rule: a structural change to a record, enum, or error that crosses the boundary needs regenerated bindings and a rebuilt library in the same change. The --check gate enforces the bindings half. Ship the bindings and the library together for the other half.

Pin the generator to the runtime

uniffi-bindgen must come from the same uniffi version as the runtime that the FFI crate links. Checksums can change between versions even when the exported API does not. UniFFI 0.31.0 removed the self type from method checksums, so 0.30.x bindings fail against a 0.31.x library, and the reverse.

Build the generator from the FFI crate, behind a feature:

# Cargo.toml of the FFI crate
[dependencies]
uniffi = { workspace = true }   # workspace root: uniffi = "0.32.1"

[features]
# The default `cargo build/clippy/test --workspace` never compiles the CLI.
cli = ["uniffi/cli"]

[[bin]]
name = "uniffi-bindgen"         # src/bin/uniffi-bindgen.rs calls uniffi::uniffi_bindgen_main()
required-features = ["cli"]

Pin uniffi once at the workspace root and commit Cargo.lock. The generator links the same locked crate, so parity holds without an = requirement. Do not install uniffi-bindgen with cargo install. A global binary drifts from the lock file and fails on one machine only.

Use UniFFI 0.32.1 or later. Generated Kotlin can fail its checksum check on a device when bindings and library match: ARM32 release builds on 0.30.0–0.31.1 (JNA direct mapping, uniffi-rs #2740), and arm64-v8a on 0.31.2–0.32.0 (introduced in 0.31.2 by the ARM32 fix, reported as uniffi-rs #2939; fixed by PR #2935 in 0.32.1). No 0.30.x or 0.31.x release is safe on both, so do not pin a 0.31.x release as a workaround. Read the CHANGELOG for every version you skip, patch releases included, before you bump. Read references/binding-compat.md when you bump uniffi.

Generate the bindings

Pass the built library, not a UDL file, as the generator source. The generator reads the metadata that the UniFFI macros put into the binary, so only the exact library has the correct metadata when cfg changes the exports. Reject cfg and cfg_attr on exported functions, methods, records, enums, errors, and objects with a source gate. If target-dependent exports are unavoidable, generate and version separate bindings for each API.

# 1. Build the host library (no --target: the build machine).
cargo rustc --locked --profile release --crate-type cdylib -p <ffi-crate> --lib

# 2. Generate Kotlin and Swift. --no-format makes the output independent of
#    the ktlint and swift-format installs on this machine.
cargo run --locked -p <ffi-crate> --features cli --bin uniffi-bindgen -- \
  generate <host library> --language kotlin --language swift \
  --no-format --out-dir <tmp>

Since UniFFI 0.31 the generator detects a library path itself, and --library has no effect. Omit it. Since 0.32, --config takes a global config file. The generator ignores an old flat uniffi.toml-style file with only a warning.

Wrap generation in one checked-in script with two modes and an optional library-path argument (the default is the host library):

• --check (the default): generate into a temporary directory and diff against the checked-in files. Exit non-zero on any difference.
• --write: overwrite the checked-in files.

The generator reads ELF, Mach-O, and PE libraries and static archives on any host. To prove target independence, run the script in --check mode with each shipping library as its input; the raw generator output always differs from the checked-in files. Pass the unstripped target/<triple>/<profile>/lib<crate_name>.so or .a. The generator reads ELF metadata from the symbol table only, so a stripped .so, such as the one inside an APK or AAB, gives no metadata.

Check in the generated Kotlin file, Swift file, C header, and modulemap. They are the contract that consumers compile against, and their diff is the review signal for an FFI change. Do not hand-edit them, because the next regeneration discards the edit. Put a fix in the Rust crate or in the consumer adapter. Read references/binding-compat.md when you write or fix the script, review an FFI diff, or coordinate a breaking change.

Commit the regenerated files in the same commit as the Rust change. A split commit gives git bisect a broken state. Run --check in the Rust CI lane and make a diff block the merge.

Classify an FFI change

Treat "binary-compatible" as a claim to justify, not a default. When in doubt, classify the change as breaking and ship bindings and library together. A record field is additive only when the selected UniFFI version generates a default for it in every target language. The uniffi-boundary skill has the default-value attribute forms.

The artifact contract

Commit the generated glue. Do not commit the .so, .a, or .xcframework; the release job rebuilds them from the tagged revision. A committed artifact goes stale, and the --check gate does not catch it.

Keep one FFI crate. Put every platform-facing export in it, so there is one checksum set, one artifact name, and one version. The rust-ios-build skill, when it is installed, owns the one-staticlib-per-app rule. Two UniFFI libraries in one iOS app also define the same C types (uniffi-rs #2802).

The rust-panic-safety skill, when it is installed, owns the panic profile setting. Under panic = "abort", a panic in an export ends the process instead of reaching Kotlin or Swift as an internal error.

Select the crate type on the packaging command, not in the manifest:

# Cargo.toml of the FFI crate
[lib]
crate-type = ["lib"]   # the default. Do not add "cdylib" or "staticlib" here.
# Set no `name` key. The artifact name then follows the package name, with
# hyphens replaced by underscores.

# Android slice
cargo rustc --locked --profile android-jni --target aarch64-linux-android \
  --crate-type cdylib -p <ffi-crate> --lib

Reason: crate-type = ["cdylib", "staticlib", "lib"] in the manifest makes every cargo build, cargo clippy, and cargo test link all three artifacts, in every lane, including the lanes that never package.

Export IPHONEOS_DEPLOYMENT_TARGET once, as the "Set one deployment target" section of the rust-ios-build skill shows. Then build each Apple slice with the --crate-type staticlib command of that skill, which sets SDKROOT. If the deployment target is not set, the C objects and the Rust objects of one slice get different minimum iOS versions.

Declare the android-jni and ios-release profiles in the workspace Cargo.toml, as the rust-android-build and rust-ios-build skills show. Each one inherits release, keeps panic = "unwind", sets strip = "none", and adds line tables. The default release profile has no line tables, and Cargo then strips debug info, so native symbols and dSYMs get no Rust file or line data. Keep --profile release only for the host library that feeds the generator.

Android: one cdylib per ABI

Build each ABI with the Android slice command above, and copy target/<triple>/android-jni/lib<crate_name>.so into <generated>/jniLibs/<abi>/. Name each ABI directory with the Android ABI name exactly: arm64-v8a, not aarch64. The packager ignores a wrong directory name without an error, and the library is then missing at run time. The rust-android-build skill has the ABI-to-target table, the shipping ABI matrix rule, the NDK environment, and the Gradle task that fills jniLibs. Read references/platform-artifacts.md when you set up the jniLibs layout, the host library for the generator, or the consumer modules.

Apple: staticlib slices and the generated C module

Build one staticlib per Apple target in the support matrix. Follow the rust-ios-build skill for the target list, the slice environment, the simulator lipo merge, xcodebuild -create-xcframework, and SwiftPM binaryTarget wiring. This skill adds the UniFFI parts:

• Stage the generated <crate_name>FFI.h and the modulemap into the headers directory of every slice. Name the modulemap file module.modulemap. uniffi-bindgen generate writes <crate_name>FFI.modulemap, so rename it in the regeneration script, not by hand. Read references/platform-artifacts.md when you stage these files or need uniffi-bindgen-swift.
• A compile-only CI lane may build aarch64-apple-ios-sim alone. Put that behind an explicit mode flag, and make the release path fail when the flag is set. A one-slice release fails on every device.

Keep the generated layer internal

Put the generated bindings in their own module. Only an adapter module depends on it, and the adapter maps the generated types onto a port type that feature modules use. Make every when and switch over generated types exhaustive, with no wildcard arm: a drifted binding is then a compile error, not silent behavior. Keep the generated Swift target at the SwiftPM default nonisolated isolation (uniffi-rs #2818). Read the consumer-layering section of references/platform-artifacts.md when you set up the generated Gradle module, the JNA dependency, or the SwiftPM targets.

Prove a release

Read references/release-proof.md when you define the mobile support matrix, prove a release candidate on its final APK, AAB, AAR, or XCFramework, or record the release closure. Do not replace those lanes with tests against intermediate .so, .a, or generated source files.

Related skills

Other skills own the adjacent work. Use them when they are installed:

Sources

• https://github.com/mozilla/uniffi-rs/blob/main/CHANGELOG.md: breaking changes and fixes per release.
• https://github.com/mozilla/uniffi-rs/issues/1789: the record-field checksum gap.
• https://mozilla.github.io/uniffi-rs/latest/swift/uniffi-bindgen-swift.html: Swift-specific generation of sources, headers, and modulemaps.
• https://mozilla.github.io/uniffi-rs/latest/kotlin/gradle.html: the JNA dependency.