Rust FFI 与编译

IriX 通过 FFI 调用 Rust 编译出的动态库。理解编译与复制流程是日常开发的基础。

动态库一览

动态库	对应 crate	Dart 侧使用
xmc_backup.dll	backup	backup_ffi.dart
xmc_downloader.dll	downloader	downloader.dart（Downloader.downloadFile）
xmc_http_client.dll	http_client	http_ffi.dart（HttpFfiService）
xmc_file_ops.dll	file_ops	file_ops_ffi.dart
xmc_logger.dll	logger	logger_ffi.dart
xmc_db_client.dll	db_client	db_client_ffi.dart（DbClientFfi）
xmc_vector_store.dll	vector_store	knowledge 相关服务

完整的调用关系见 FFI 服务清单。

编译与复制

# 编译（Windows 也可直接双击 build_rust.bat）
cargo build --release --manifest-path rust/Cargo.toml

# Linux / macOS
./build_rust.sh

产物复制目标（脚本已处理）：

• Windows → windows/runner/（同时复制一份到项目根目录）
• Linux → linux/
• macOS → macos/

危险

修改任何 Rust 代码后，必须先重新编译并复制动态库到平台目录，否则运行与测试加载的是旧动态库——这是最常见的“改了没生效”原因。

新增 crate 检查清单

新增一个 Rust crate 时，需要同步更新以下 7 处：

1. rust/Cargo.toml 的 members 列表
2. build_rust.bat（Windows 构建脚本）
3. build_rust.sh（Linux/macOS 构建脚本）
4. linux/CMakeLists.txt（Linux .so 安装）
5. windows/runner/CMakeLists.txt（Windows 复制）
6. macos/Runner.xcodeproj/project.pbxproj（dylib 复制 + 签名脚本）
7. 两个 CI workflow：
   • .github/workflows/build-and-test.yml
   • .github/workflows/package.yml

注意

package.yml 极易漏改——新增 crate 后务必同时检查它。

Dart 侧封装模式

Rust 导出函数通过 FFI 调用，Dart 侧统一封装在 lib/services/*_ffi.dart：

Rust 导出函数  ←─  package:ffi 绑定  ←─  lib/services/*_ffi.dart  ←─  业务服务调用

典型封装示例：backup_ffi.dart、file_ops_ffi.dart、logger_ffi.dart、http_ffi.dart、db_client_ffi.dart。新增 API 服务遵循现有 *_api_service.dart / *_provider.dart 命名模式。