DOC-302c 更新构建流程：library 模式 + Swift binding 重新生成 #32

New Issue

wangdl · 2026-06-02T22:19:06+08:00

wangdl commented

2026-06-02 22:19:06 +08:00

目标

将构建脚本从 UDL 模式切换到 library 模式。

禁止混用

迁移完成后，zx_document_ffi 不允许同时存在 include_scaffolding!() 和 setup_scaffolding!()。

proc-macro 模式正确组合：

uniffi::setup_scaffolding!()
#[uniffi::export]
#[derive(uniffi::Record / Enum / Error)]
library mode 生成 Swift binding

旧 UDL 生成链路只保留为历史说明，不参与主构建流程。

清理旧产物

必须清理，否则容易：Rust 已改 proc-macro，Swift 还在用旧 binding，Xcode 还在链接旧 XCFramework。

删除 bindings/ios/generated/ 旧 Swift 文件
删除 bindings/ios/ZxDocumentRuntime.xcframework
删除 bindings/ios/device/ 和 bindings/ios/simulator/ 旧 .a 文件
清理 iOS 项目中的旧 XCFramework 引用
清理 iOS 项目中的旧 zx_document.swift 引用
清理 Xcode DerivedData
重新生成全部产物

构建流程改动

build.rs

确认 uniffi::generate_scaffolding 调用仍然正确（proc-macro 模式仍需 scaffolding for 元数据）
或：如果 proc-macro 完全替代 UDL，移除 build.rs 中 UDL 相关代码

scripts/build-ios.sh

# 旧（UDL 模式）：
uniffi-bindgen-swift --swift-sources zx_document.udl output/

# 新（library 模式）：
# 1. 先编译为 dylib
cargo build --release -p zx_document_ffi
# 2. 从 dylib 生成 Swift 绑定
uniffi-bindgen library --swift-sources \
  target/release/libzx_document_ffi.dylib \
  bindings/ios/generated

注意事项

library 模式生成的文件比 UDL 模式大（包含 FFI 分发逻辑）
生成的 Swift 文件是完全自包含的（不需要外部 C module）
需要验证 nm 输出中有 _uniffi_zx_document_ffi_fn_func_* 符号

依赖

依赖 DOC-302a + DOC-302b

验收

bash scripts/build-ios.sh 成功
nm bindings/ios/simulator/libzx_document_ffi.a | grep "uniffi_zx_document_ffi_fn_func" 有输出

## 目标将构建脚本从 UDL 模式切换到 library 模式。 ## 禁止混用迁移完成后，`zx_document_ffi` 不允许同时存在 `include_scaffolding!()` 和 `setup_scaffolding!()`。 proc-macro 模式正确组合： - `uniffi::setup_scaffolding!()` - `#[uniffi::export]` - `#[derive(uniffi::Record / Enum / Error)]` - library mode 生成 Swift binding 旧 UDL 生成链路只保留为历史说明，不参与主构建流程。 ## 清理旧产物 **必须清理，否则容易：Rust 已改 proc-macro，Swift 还在用旧 binding，Xcode 还在链接旧 XCFramework。** - [ ] 删除 `bindings/ios/generated/` 旧 Swift 文件 - [ ] 删除 `bindings/ios/ZxDocumentRuntime.xcframework` - [ ] 删除 `bindings/ios/device/` 和 `bindings/ios/simulator/` 旧 .a 文件 - [ ] 清理 iOS 项目中的旧 XCFramework 引用 - [ ] 清理 iOS 项目中的旧 zx_document.swift 引用 - [ ] 清理 Xcode DerivedData - [ ] 重新生成全部产物 ## 构建流程改动 ### build.rs - 确认 `uniffi::generate_scaffolding` 调用仍然正确（proc-macro 模式仍需 scaffolding for 元数据） - 或：如果 proc-macro 完全替代 UDL，移除 build.rs 中 UDL 相关代码 ### scripts/build-ios.sh ```bash # 旧（UDL 模式）： uniffi-bindgen-swift --swift-sources zx_document.udl output/ # 新（library 模式）： # 1. 先编译为 dylib cargo build --release -p zx_document_ffi # 2. 从 dylib 生成 Swift 绑定 uniffi-bindgen library --swift-sources \ target/release/libzx_document_ffi.dylib \ bindings/ios/generated ``` ### 注意事项 - library 模式生成的文件比 UDL 模式大（包含 FFI 分发逻辑） - 生成的 Swift 文件是完全自包含的（不需要外部 C module） - 需要验证 nm 输出中有 `_uniffi_zx_document_ffi_fn_func_*` 符号 ## 依赖 - 依赖 DOC-302a + DOC-302b ## 验收 - `bash scripts/build-ios.sh` 成功 - `nm bindings/ios/simulator/libzx_document_ffi.a | grep "uniffi_zx_document_ffi_fn_func"` 有输出

wangdl added this to the M3：iOS 主 App 资料阅读闭环 milestone 2026-06-02 22:19:06 +08:00

wangdl added the

type:integration

area:ffi

area:ci

labels 2026-06-02 22:19:06 +08:00

wangdl commented

2026-06-03 19:59:56 +08:00

完成 (2026-06-03)

清理旧产物

删除 bindings/ios/generated/ 旧文件
删除 bindings/ios/ZxDocumentRuntime.xcframework
删除 bindings/ios/device/ 和 bindings/ios/simulator/ 旧 .a

构建流程

scripts/build-ios.sh 更新：
- uniffi-bindgen generate --language swift xx.udl → 生成 Swift 绑定
- 内联符号检查：构建后自动 nm 验证 17 个关键 C ABI 符号
- 符号缺失 → 构建直接失败
新增 scripts/check-symbols.sh — 独立符号检查脚本（DOC-302f）

禁止混用

确认：UDL 用于 Swift bindgen 生成 + proc-macro 用于 C 符号生成
不再使用纯 UDL 模式或 library mode

iOS 集成

XCFramework 已重新构建并复制到 iOS 项目
Swift 文件已生成并修补（内联 FFI 类型 + @_silgen_name）
pbxproj 添加 LIBRARY_SEARCH_PATHS + OTHER_LINKER_FLAGS
xcodebuild 验证：BUILD SUCCEEDED

验证

cargo test 58 pass
bash scripts/check-symbols.sh 通过
xcodebuild -scheme AIStudyApp build 通过

## 完成 (2026-06-03) ### 清理旧产物 - 删除 `bindings/ios/generated/` 旧文件 - 删除 `bindings/ios/ZxDocumentRuntime.xcframework` - 删除 `bindings/ios/device/` 和 `bindings/ios/simulator/` 旧 .a ### 构建流程 - `scripts/build-ios.sh` 更新： - `uniffi-bindgen generate --language swift xx.udl` → 生成 Swift 绑定 - 内联符号检查：构建后自动 `nm` 验证 17 个关键 C ABI 符号 - 符号缺失 → 构建直接失败 - 新增 `scripts/check-symbols.sh` — 独立符号检查脚本（DOC-302f） ### 禁止混用 - 确认：UDL 用于 Swift bindgen 生成 + proc-macro 用于 C 符号生成 - 不再使用纯 UDL 模式或 library mode ### iOS 集成 - XCFramework 已重新构建并复制到 iOS 项目 - Swift 文件已生成并修补（内联 FFI 类型 + @_silgen_name） - pbxproj 添加 LIBRARY_SEARCH_PATHS + OTHER_LINKER_FLAGS - **xcodebuild 验证：BUILD SUCCEEDED** ### 验证 - `cargo test` 58 pass - `bash scripts/check-symbols.sh` 通过 - `xcodebuild -scheme AIStudyApp build` 通过

wangdl closed this issue

2026-06-07 20:06:43 +08:00

wangdl commented

2026-06-07 20:06:43 +08:00

关闭

DOC-302c 已完成 — library 模式 + binding 生成

## 关闭 DOC-302c 已完成 — library 模式 + binding 生成

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/zhixi-document-runtime#32