zhixi-document-runtime/docs/cross-platform-release.md

跨平台发布流程

1. 概述

Document Runtime 通过 UniFFI 生成多语言绑定，支持跨平台分发。

平台	产物	绑定语言	状态
iOS	.xcframework	Swift（uniffi）	✅ 生产
macOS (Catalyst)	.xcframework	Swift（uniffi）	🔄 计划中
Android	.aar	Kotlin（uniffi）	🔄 计划中

---

2. iOS .xcframework

2.1 目标架构

架构	Rust Target	用途
ios-arm64	aarch64-apple-ios	iPhone 真机
ios-arm64-sim	aarch64-apple-ios-sim	Apple Silicon Mac 模拟器
ios-x86_64-sim	x86_64-apple-ios	Intel Mac 模拟器

2.2 构建步骤

cd zhixi-document-runtime

# 1. 安装 targets
rustup target add aarch64-apple-ios \
                 aarch64-apple-ios-sim \
                 x86_64-apple-ios

# 2. 构建各架构
cargo build --release -p zx_document_ffi --target aarch64-apple-ios
cargo build --release -p zx_document_ffi --target aarch64-apple-ios-sim
cargo build --release -p zx_document_ffi --target x86_64-apple-ios

# 3. 打包 xcframework
xcodebuild -create-xcframework \
  -library target/aarch64-apple-ios/release/libzx_document_ffi.a \
  -library target/aarch64-apple-ios-sim/release/libzx_document_ffi.a \
  -library target/x86_64-apple-ios/release/libzx_document_ffi.a \
  -output ZxDocumentRuntime.xcframework

# 4. 校验
xcodebuild -check-xcframework ZxDocumentRuntime.xcframework
# Expected: ios-arm64, ios-arm64-sim, ios-x86_64-sim ✅

# 5. 生成 Swift 绑定
uniffi-bindgen generate \
  crates/zx_document_ffi/src/zx_document.udl \
  --language swift \
  --out-dir ./generated/swift/

# 6. 打包发布资产
zip -r ZxDocumentRuntime.xcframework.zip ZxDocumentRuntime.xcframework/
cp generated/swift/zx_document.swift ./release-assets/

2.3 集成到 Xcode

1. 将 ZxDocumentRuntime.xcframework 拖入 Xcode → Embed & Sign
2. 将 zx_document.swift 添加到项目
3. Build Settings → FRAMEWORK_SEARCH_PATHS 包含 xcframework 路径

---

3. Android .aar（计划中）

3.1 目标架构

架构	Rust Target
arm64-v8a	aarch64-linux-android
armeabi-v7a	armv7-linux-androideabi
x86_64	x86_64-linux-android
x86	i686-linux-android

3.2 构建步骤（草案）

# 1. 安装 NDK + targets
rustup target add aarch64-linux-android \
                 armv7-linux-androideabi \
                 x86_64-linux-android

# 2. 构建各架构
cargo build --release -p zx_document_ffi --target aarch64-linux-android
# ... (repeat for each target)

# 3. 生成 Kotlin 绑定
uniffi-bindgen generate \
  crates/zx_document_ffi/src/zx_document.udl \
  --language kotlin \
  --out-dir ./generated/kotlin/

# 4. 打包 .aar
# 标准 Android 库打包流程：
# - jniLibs/<abi>/libzx_document_ffi.so
# - generated/kotlin/**/*.kt
# - AndroidManifest.xml
# 使用 gradle / android-maven-plugin 打包为 .aar

3.3 注意事项

• Android 需要 JNI 兼容的符号导出（#[no_mangle] pub extern "C"）
• NDK 版本 ≥ r26
• ANDROID_NDK_HOME 环境变量需设置
• 需要 libunwind 链接（-lunwind）

---

4. UniFFI 多语言绑定生成

4.1 一次生成所有语言

for lang in swift kotlin python ruby; do
  uniffi-bindgen generate \
    crates/zx_document_ffi/src/zx_document.udl \
    --language "$lang" \
    --out-dir "generated/$lang/"
done

4.2 生成的产物

generated/
├── swift/
│   └── zx_document.swift        # Swift 绑定
├── kotlin/
│   └── zx_document.kt           # Kotlin 绑定（Android 用）
├── python/
│   └── zx_document.py           # Python 绑定（CLI 工具用）
└── ruby/
    └── zx_document.rb           # Ruby 绑定

---

5. 版本管理

5.1 版本号同步

文件	字段	示例
Cargo.toml (workspace)	workspace.package.version	0.1.0
ZxDocumentRuntime.xcframework/Info.plist	CFBundleVersion	0.1.0
Git tag	—	v0.1.0
zx_document.swift	注释头部	// UniFFI 0.28, zx_document v0.1.0

5.2 发布 Checklist

tag vX.Y.Z
  ├── [ ] Cargo.toml version bumped
  ├── [ ] cargo test --workspace ✅
  ├── [ ] CI release job passes
  ├── [ ] xcframework.zip uploaded to GitHub Release
  ├── [ ] zx_document.swift uploaded to GitHub Release
  ├── [ ] CHANGELOG.md updated
  └── [ ] iOS app built with new xcframework ✅

---

6. CI 自动化

发布流程已集成到 .github/workflows/ci.yml：

Step	触发	产物
Build (matrix)	tag v*	libzx_document_ffi.a per target
Package xcframework	tag v*	ZxDocumentRuntime.xcframework.zip
GitHub Release	tag v*	自动 release notes + 上传 zip

# 手动触发发布
git tag v0.1.0
git push origin v0.1.0
# CI 自动执行 release + package-xcframework jobs

---

7. 相关文档

• UniFFI UDL 编写规范
• C-ABI out-pointer 模式
• iOS FFI 调用指南
• CI/CD Pipeline