DOC-FULL-033 P1 | 文档：FFI Troubleshooting 【status:todo】 #82

New Issue

wangdl · 2026-06-07T11:33:20+08:00

wangdl commented

2026-06-07 11:33:20 +08:00

UniFFI 版本/setup_scaffolding/library mode/bindgen/header/modulemap/XCFramework/undefined symbol/No such module/checksum mismatch

M-DOC-FULL 里程碑 issue。详见设计文档。

## UniFFI 版本/setup_scaffolding/library mode/bindgen/header/modulemap/XCFramework/undefined symbol/No such module/checksum mismatch M-DOC-FULL 里程碑 issue。详见设计文档。

wangdl added this to the M-DOC-FULL：Document Runtime 完整阅读内核与学习事件协议 milestone 2026-06-07 11:33:20 +08:00

wangdl changed title from ~~DOC-FULL-033 P1 | 文档：FFI Troubleshooting~~ to DOC-FULL-033 P1 | 文档：FFI Troubleshooting 【status:todo】

2026-06-07 19:15:08 +08:00

wangdl commented

2026-06-07 19:15:08 +08:00

审查结论：document runtime 当前有文件类型识别/MaterialType/PreviewMode/DocumentInfo(基本)/Markdown解析/Text解析/ImageMeta/Search(V1 Markdown+Text)/NoteAnchor(V1)/ReadingEvent(V1)/ReadingPosition(V1)/EventBuffer(V1基础)/iOS构建/UniFFI绑定/docs。但 V2 核心模型(ReadingSession/EventV2/ActiveTimeTracker)不存在，EventBuffer 缺 ack/failed，Position 缺 camelCase+clamp，PDF/EPUB/Office 为 stub，测试覆盖不足 V2。

本 Issue: 不存在。但之前遇到过 ARM64 struct-passing/undefined symbol 问题，经验可写入。

状态: status:todo
工作类型: work:docs

## 审查结论：document runtime 当前有文件类型识别/MaterialType/PreviewMode/DocumentInfo(基本)/Markdown解析/Text解析/ImageMeta/Search(V1 Markdown+Text)/NoteAnchor(V1)/ReadingEvent(V1)/ReadingPosition(V1)/EventBuffer(V1基础)/iOS构建/UniFFI绑定/docs。但 V2 核心模型(ReadingSession/EventV2/ActiveTimeTracker)不存在，EventBuffer 缺 ack/failed，Position 缺 camelCase+clamp，PDF/EPUB/Office 为 stub，测试覆盖不足 V2。 **本 Issue**: 不存在。但之前遇到过 ARM64 struct-passing/undefined symbol 问题，经验可写入。 **状态**: status:todo **工作类型**: work:docs

wangdl commented

2026-06-07 22:01:12 +08:00

完成报告

新增文档

docs/ffi-troubleshooting.md — FFI 排错指南：

13 个常见问题 + 解决：

No such module ZxDocumentRuntime
Undefined symbol ffi_zx_document_ffi*
Library not found -lzx_document_ffi
UniFFI checksum mismatch
setup_scaffolding!() not called
新增类型/函数后 Swift 不可见（完整接入步骤）
cargo build 目标平台不匹配
infer/comrak/zip crate 编译失败
XCFramework 构建注意事项
UDL 类型不支持（tuple/泛型/生命周期）
Rust 与 iOS 持有引用（值类型语义）
新增 type 的完整 FFI 接入步骤
modulemap 创建模板

验证清单：

cargo build device + simulator ✓
nm 验证符号 ✓
Swift binding 编译 ✓
XCFramework slices ✓
demo 链接 ✓

## 完成报告 ### 新增文档 `docs/ffi-troubleshooting.md` — FFI 排错指南： **13 个常见问题 + 解决：** 1. No such module ZxDocumentRuntime 2. Undefined symbol _ffi_zx_document_ffi_* 3. Library not found -lzx_document_ffi 4. UniFFI checksum mismatch 5. setup_scaffolding!() not called 6. 新增类型/函数后 Swift 不可见（完整接入步骤） 7. cargo build 目标平台不匹配 8. infer/comrak/zip crate 编译失败 9. XCFramework 构建注意事项 10. UDL 类型不支持（tuple/泛型/生命周期） 11. Rust 与 iOS 持有引用（值类型语义） 12. 新增 type 的完整 FFI 接入步骤 13. modulemap 创建模板 **验证清单：** - cargo build device + simulator ✓ - nm 验证符号 ✓ - Swift binding 编译 ✓ - XCFramework slices ✓ - demo 链接 ✓

wangdl closed this issue

2026-06-07 22:01:56 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/zhixi-document-runtime#82