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 构建步骤

```bash
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 构建步骤（草案）

```bash
# 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 一次生成所有语言

```bash
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 |

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

---

## 7. 相关文档

- [UniFFI UDL 编写规范](./uniffi-udl-spec.md)
- [C-ABI out-pointer 模式](./c-abi-out-pointer-pattern.md)
- [iOS FFI 调用指南](./ios-ffi-integration-guide.md)
- [CI/CD Pipeline](../.github/workflows/ci.yml)