SuperAPI AI 工具集

verify-and-build

编程与开发

查看项目

更新于 10-26 09:19

技能介绍

用途

本技能面向 react-native-executorch 库的贡献者,提供在修改后编译、测试、验证与排查问题的操作指南,覆盖 JS/TS 与原生 C++ 两侧。

主要能力

TypeScript 构建与检查

  • 快速类型检查:yarn typecheck。
  • 运行 TypeScript API 测试:yarn workspace react-native-executorch test。Jest 套件针对公开的 src/ 接口(hooks、任务管道、核心原语、fetcher 与模型注册表),运行在模拟原生运行时上,无需模拟器、设备或 .pte 文件。
  • 构建产物:yarn prepare,清理目标目录并通过 react-native-builder-bob 构建到 lib/ 目录。

原生重新构建

iOS:修改 cpp/ 或 .podspec 后,在 apps/<domain-app>/ios 执行 pod install,再从对应 app 目录运行 yarn run ios;必要时在 Xcode 中 Clean Build Folder(Cmd+Shift+K)。Android:从 app 目录运行 yarn run android,缓存问题时执行 ./gradlew clean。

C++ 静态分析

  1. lint:cpp(clang-tidy):使用项目 .clang-tidy 规则集(bugprone / performance / clang-analyzer / llvm-include-order)检查 cpp/ 源码。需通过 Homebrew LLVM 安装 clang-tidy(Xcode 自带版本过旧),命令:CLANG_TIDY=$(brew --prefix llvm)/bin/clang-tidy yarn workspace react-native-executorch lint:cpp。任何发现都会导致失败(--warnings-as-errors);对有意且经审查的发现可用 // NOLINTNEXTLINE(check-name) 抑制,而不是放宽共享配置。Homebrew LLVM 比 CI 的 clang-tidy 更新,可能报告 CI 没有的检查项;在“修复”本地发现前,应先将未修改的基础分支版本以临时名称复制进来同样检查,以判断是否为既有问题。
  2. check-cpp-warnings.sh:使用与编辑器 clangd 相同的标志(compile_flags.txt + .clangd 中的 -W 标志)编译已暂存或显式传入的 cpp/ 源码,保持编辑器与 CI 同步。从包根目录运行;脚本以位置参数接收文件路径,无内置文件发现,需显式传入,例如:find cpp/ -path cpp/tests -prune -o \( -name '*.cpp' -o -name '*.h' \) -print | xargs ./scripts/check-cpp-warnings.sh。若无编译器、compile_flags.txt、.clangd 或预置头文件,脚本会优雅跳过(退出码 0),不阻塞不构建原生代码的贡献者。

调试与日志

  • Worklet 日志:在标注 'worklet'; 的函数内使用标准 console.log(...)。注意从 worklet 向 console.log 传递复杂循环对象可能失败或冻结,应改为字符串化或仅记录特定原始属性。
  • 原生 C++ 调试:iOS 在运行 app 目标时于 Xcode Console 查看输出;Android 使用 Android Studio logcat 或运行 adb logcat *:S ReactNative:V ReactNativeJS:V rnexecutorch:V。

常见 JSI 问题排查

  • 症状:Error: JSI global object '__rnexecutorch_jsi__' is not registered. 原因1:原生代码未链接或加载时 JSI 安装失败,需确认已在 cpp/RnExecutorch.cpp 注册新扩展/模块,并重跑 pod install(iOS)或 Gradle sync/clean(Android)。原因2:桥接未调用原生安装,需确保 JS 入口触发加载(见 src/native/bridge.ts)。
  • 症状:TypeError: Cannot read property '<extension>' of undefined。原因:在 C++ 添加了扩展但忘记在 TypeScript 桥接绑定中注册。需检查原生 install.cpp 中调用了 module.setProperty(rt, "<extension>", subModule),且 TS 包装在 rnexecutorchJsi.<extension> 下导出并引用它。

模型托管与下载缓存

项目不在 React Native 应用包内捆绑本地 .pte 模型文件。标准工作流:将编译/导出的 .pte 模型上传到 Hugging Face 存储桶,文件命名必须遵循 modelname_optionalsize_backend_precision.pte 约定,例如 efficientnet_v2_s_xnnpack_int8.pte、style_transfer_candy_xnnpack_fp32.pte。在 src/models.ts 中定义:新模型配置作为内部(私有)const 定义,不要单独导出模型配置常量,而应注册到导出的 models 注册表对象中相应类别下(models.ts 唯一导出符号为 models)。示例:内部定义 const MY_MODEL_XNNPACK_FP32: MyTaskModel = { ... };,再在 export const models = { ... myTask: { MY_MODEL: { XNNPACK_FP32: MY_MODEL_XNNPACK_FP32 } } }; 注册。运行时下载与缓存由自定义 hook useResourceDownload(config.modelPath) 处理:若模型文件不在设备缓存目录,则从 Hugging Face URL 下载到 RNFS.CachesDirectoryPath;若已存在则跳过下载并立即返回缓存本地路径用于加载模型。

使用方式

按上述命令与流程执行;核心原则是修改后先运行类型检查、API 测试与构建,原生 C++ 改动后必须重跑 pod install 或 Gradle 同步,提交前运行两项 C++ 静态检查。

适用场景

编译 TS/C++、重建 iOS pods、排查 JSI 运行时错误、调试原生崩溃、同步 Android Gradle,以及模型托管与下载缓存的配置。

限制与注意事项

  • 不要在未验证的情况下运行代码:TypeScript 更改需先通过 yarn typecheck、API 测试与 yarn prepare。
  • C++ 编辑后不要跳过原生重建。
  • 不要使用系统 clang-tidy 运行 lint:cpp,应使用 Homebrew LLVM 二进制。
  • 不要仅凭 macOS-only 语法检查判断平台条件编译的 C++ 是否正确。
  • 不要在 worklet 内记录复杂对象。
  • 不要将本地 .pte 文件提交到仓库,始终托管于 Hugging Face 并在 src/models.ts 注册元数据。

验证清单

  • TypeScript 类型检查通过(yarn typecheck)。
  • TypeScript API 测试通过,且新 src/ 行为被覆盖。
  • 产物构建成功(yarn prepare)。
  • 原生 C++ 编辑后在 apps/<domain-app>/ios/ 运行过 pod install。
  • lint:cpp 干净通过。
  • check-cpp-warnings.sh 干净通过。
  • 没有 .pte 文件被暂存或加入 git 历史。
  • 模型配置注册在 src/models.ts 的单一 models 对象注册表中。
  • 原生运行时问题已通过 Xcode Console 或 adb logcat 排查。