8b27430ed1
Some checks failed
iOS CI/CD / Build & Test (push) Has been cancelled
- rust-ffi-update.md: FFI binding update workflow - app-store-submission-checklist.md: 9-section App Store review - ios-ci.yml: GitHub Actions build + test on macos-15 - firebase-crashlytics-integration.md: Crashlytics setup guide Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
145 lines
4.2 KiB
Markdown
145 lines
4.2 KiB
Markdown
# Rust FFI 绑定更新流程
|
||
|
||
## 1. 概述
|
||
|
||
iOS 通过 uniffi 生成的 Swift 绑定调用 Rust Document Runtime（zx_document_core）。
|
||
|
||
更新流程：修改 Rust 代码 → 重新生成 bindings → Xcode 重新编译
|
||
|
||
---
|
||
|
||
## 2. 文件结构
|
||
|
||
```
|
||
zhixi-document-runtime/
|
||
├── crates/
|
||
│ ├── zx_document_core/ # 核心 Rust 库
|
||
│ │ ├── src/
|
||
│ │ │ ├── document.rs # DocumentInfo + build_document_info
|
||
│ │ │ ├── material_type.rs
|
||
│ │ │ ├── markdown.rs # Markdown 解析
|
||
│ │ │ ├── pdf.rs # PDF 元数据/文本提取
|
||
│ │ │ ├── epub.rs # EPUB 元数据/章节/文本
|
||
│ │ │ ├── search.rs # 全文搜索
|
||
│ │ │ ├── anchors.rs # NoteAnchor
|
||
│ │ │ ├── events_v2.rs # V2 事件 buffer
|
||
│ │ │ ├── session_v2.rs # V2 Session 管理
|
||
│ │ │ └── image_meta.rs # 图片元数据
|
||
│ │ └── Cargo.toml
|
||
│ └── zx_document_ffi/ # FFI 绑定层
|
||
│ ├── src/
|
||
│ │ └── lib.rs # uniffi 导出定义
|
||
│ ├── src/zx_document.udl # UDL 接口定义
|
||
│ └── Cargo.toml
|
||
└── Cargo.toml # Workspace root
|
||
|
||
ios-projects/
|
||
└── AIStudyApp/
|
||
└── AIStudyApp/
|
||
└── Core/
|
||
├── ZxDocumentRuntime.xcframework/ # 预编译 Rust 库
|
||
└── zx_document.swift # uniffi 生成的 Swift 绑定
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 更新流程
|
||
|
||
### 3.1 修改 Rust 接口
|
||
|
||
1. 在 `zx_document_core/src/` 中修改或新增函数/类型
|
||
2. 在 `zx_document_ffi/src/lib.rs` 中导出新接口
|
||
3. 如需新增 UDL 定义，更新 `zx_document.udl`
|
||
|
||
### 3.2 重新生成 Swift 绑定
|
||
|
||
```bash
|
||
cd zhixi-document-runtime
|
||
cargo build --release -p zx_document_ffi
|
||
|
||
# 生成 Swift 绑定
|
||
uniffi-bindgen generate \
|
||
crates/zx_document_ffi/src/zx_document.udl \
|
||
--language swift \
|
||
--out-dir ../ios-projects/AIStudyApp/AIStudyApp/Core/
|
||
```
|
||
|
||
### 3.3 构建 xcframework
|
||
|
||
```bash
|
||
# iOS arm64
|
||
cargo build --release -p zx_document_ffi --target aarch64-apple-ios
|
||
|
||
# iOS Simulator arm64 (Apple Silicon Mac)
|
||
cargo build --release -p zx_document_ffi --target aarch64-apple-ios-sim
|
||
|
||
# iOS Simulator x86_64 (Intel Mac)
|
||
cargo build --release -p zx_document_ffi --target x86_64-apple-ios
|
||
|
||
# 打包 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 \
|
||
-output ZxDocumentRuntime.xcframework
|
||
```
|
||
|
||
### 3.4 更新 Xcode 项目
|
||
|
||
1. 替换 `AIStudyApp/Core/ZxDocumentRuntime.xcframework`
|
||
2. 替换 `AIStudyApp/Core/zx_document.swift`
|
||
3. 在 Xcode 中 Clean Build Folder（Cmd+Shift+K）
|
||
4. 重新编译
|
||
|
||
---
|
||
|
||
## 4. 新增接口 checklist
|
||
|
||
- [ ] Rust 类型实现 `Serialize + Deserialize + uniffi::Record/Enum`
|
||
- [ ] FFI 层 `pub extern "C"` 导出函数
|
||
- [ ] UDL 文件声明接口
|
||
- [ ] Swift 绑定重新生成
|
||
- [ ] xcframework 重新编译（至少 arm64 + sim）
|
||
- [ ] iOS 编译通过
|
||
- [ ] 单元测试通过（`cargo test -p zx_document_core`）
|
||
|
||
---
|
||
|
||
## 5. 常见问题
|
||
|
||
### 5.1 xcframework 架构缺失
|
||
|
||
**症状**：`While building for macOS, no library for this platform was found`
|
||
|
||
**原因**：xcframework 仅包含 iOS 架构，Mac Catalyst 构建试图链入
|
||
|
||
**处理**：确保 Scheme 仅勾选 iOS target，或为 Mac Catalyst 添加 `aarch64-apple-ios-macabi` 目标
|
||
|
||
### 5.2 uniffi 版本不匹配
|
||
|
||
**症状**：`uniffi::ffi::foreigncallbacks` not found
|
||
|
||
**处理**：确保 `Cargo.toml` 中 uniffi 版本与 `uniffi-bindgen` CLI 版本一致
|
||
|
||
### 5.3 Swift 类型不匹配
|
||
|
||
**症状**：`Cannot convert value of type 'X' to expected argument type 'Y'`
|
||
|
||
**处理**：重新生成 `zx_document.swift`（uniffi-bindgen 输出），确保与 xcframework 版本对应
|
||
|
||
---
|
||
|
||
## 6. 版本管理
|
||
|
||
| Rust crate | 当前版本 | FFI 接口数 |
|
||
|------------|:--:|:--:|
|
||
| zx_document_core | 0.1.0 | — |
|
||
| zx_document_ffi | 0.1.0 | 12 |
|
||
| uniffi | 0.28 | — |
|
||
|
||
---
|
||
|
||
## 7. 相关文档
|
||
|
||
- [V2 事件 Pipeline 架构](./v2-event-pipeline.md)
|
||
- [阅读信息采集接入文档](./reading-info-integration.md)
|