librime_koreader 构建模块

本模块为 KOReader Rime 输入法插件（rime.koplugin）构建设备相关的 native wrapper：交叉编译 librime_koreader.so、组装随插件发布的 Rime schema 与 OpenCC 数据，并提供工具链与 ABI 验证。它只负责设备相关的构建、验证和产物生成；插件 Lua 层通过稳定的 C ABI 消费产物，不包含任何设备相关代码。

目录结构

路径	用途
build/downloads/	第三方源码与下载缓存，可重新获取；删除后下次构建需联网
build/<target>/staging/	Zig 交叉编译依赖的头文件与静态库安装目录，可重新生成
build/<target>/	Zig/CMake 中间产物与 ABI probe，可重新生成
dist/<target>/	最终产物：librime_koreader.so、smoke_native、rime/shared/
targets/	每个 KOReader target 的 Zig target、CPU、float ABI 与 GLIBC 上限
toolchain/	Zig cc/c++/ar/ranlib 包装器与通用 CMake toolchain
scripts/	Zig 构建入口、ELF 校验与数据准备脚本
src/krime.cpp	librime 的 C++ 实现及异常边界
include/krime.h	提供给 LuaJIT FFI 的稳定、定长 C ABI
krime.map	限制动态符号，只导出版本化的 krime_* API
tests/	zig_probe.c（ABI gate）与 smoke_native.cpp（真机 native smoke）
patches/	固定版本依赖的兼容补丁
tools/	不参与正常构建的真机调试和传输辅助工具（模拟点击 uinput_tap.c/uinput_tapd.c、截图 fbdump.c），用法见真机调试指南

build/ 与 dist/ 均已被 .gitignore 排除。磁盘空间不足时可以关闭正在运行的 构建后删除这些目录；下一次完整构建会重新下载和编译依赖。

构建约束

• 构建后端是 Zig，可在 macOS Apple Silicon 或 Linux 上直接交叉编译，不需要 容器或 Linux 虚拟机。
• Zig 后端统一使用 Zig 自带的 libc++，并把 C++ runtime 静态链接进 wrapper；所有 C++ 依赖必须由同一次 Zig 构建生成，不可混入其他工具链或 libstdc++ 产物。
• Kindle 的旧 ARM 动态加载器不能可靠处理 Zig/LLD 默认的 BIND_NOW 大型 DSO， Zig 构建会强制使用 lazy PLT binding，并补上 Zig 未提供的 DSO C++ 析构终结钩子； 不要移除 KRIME_ZIG_COMPAT 或 src/zig_dso_fini.c。
• kindlepw2 为 ARMv7/EABI5 softfp，GLIBC 上限 2.12；kindlehf 为 ARMv7/EABI5 hard-float，GLIBC 上限 2.20。float ABI 与 GLIBC 上限均由 target 配置决定，不能混用产物。
• librime、Boost.Regex、LevelDB、Marisa、OpenCC 和 yaml-cpp 必须静态链接进 wrapper；运行时只允许依赖 Kindle 提供的基础系统库。
• include/krime.h 是稳定 C ABI，修改时必须同步插件侧 rime.koplugin/ffi/krime_h.lua 与 rime_ime.lua 的 ABI_VERSION，并重新完成 真机验收。

构建

安装 Zig、CMake 和 LLVM readelf（macOS/Homebrew）：

brew install zig cmake llvm

在 macOS 或 Linux 上直接构建：

./scripts/build.sh kindlepw2
./scripts/build.sh kindlehf
# 等价于：./scripts/build-zig.sh <target>

完整构建会同时生成 native 测试程序、插件需要的共享库和 Rime 数据到 dist/<target>/。如果同级存在 ../rime.koplugin 插件仓库（或设置了 KRIME_PLUGIN_DIR），构建结束后会把 .so 同步到插件树的 lib/、把 shared 数据同步到插件树的 rime/shared/；否则跳过同步并提示。

可配置环境变量：

变量	默认	用途
ZIG	zig	Zig 可执行文件路径
KRIME_JOBS	最多 4	并行编译任务数；可按主机内存手动调整
KRIME_PLUGIN_DIR	../rime.koplugin	插件仓库根目录，用于构建后同步
KRIME_SYNC_PLUGIN	1	设为 0 时只生成 target 产物，不覆盖插件树中的当前 .so 与数据

脚本说明

文件	类型	用途
build.sh	默认入口	按 target 调用 Zig 构建。
build-zig.sh	Zig 入口	先构建 ABI probe，再交叉编译全部静态依赖、librime、wrapper 和 smoke。
verify-elf.sh	公共校验	从 targets/<target>.env 读取 ABI 规则，检查 ARM/EABI、float ABI、GLIBC 与动态依赖。
prepare-rime-data.sh	内部辅助	由主构建脚本调用；获取固定版本的 Rime 数据仓库，复制 schema、词典及 OpenCC 数据。通常不单独执行。
versions.sh	配置文件	保存依赖仓库、不可变 commit、Boost 下载地址和 SHA-256。它由其他脚本 source，不是独立命令。

当前定义了 kindlepw2 与 kindlehf。增加 target 时应新增配置并复用 build-zig.sh，不要在公共逻辑中写死 CPU、float ABI 或 GLIBC 上限。Boost 中间产物按 target 放在 build/<target>/boost-build/，避免 softfp 与 hard-float 对象互相污染。

项目没有单独的 QEMU static smoke 脚本。最终产物涉及旧版 Kindle 用户空间、动态 加载和 KOReader LuaJIT FFI，native smoke 应使用完整构建生成的 dist/<target>/smoke_native 在目标设备执行。kindlehf 当前只完成开发机交叉构建 与静态 ABI 检查，尚未进行真机运行验证。

数据准备与插件同步

• prepare-rime-data.sh 从 versions.sh 固定的不可变 revision 拉取数据，组装 prelude、luna-pinyin、essay、stroke、double-pinyin 与 OpenCC 数据。
• schema_list 等插件配置来自插件仓库的 rime/default.custom.yaml.template （路径可通过 KRIME_PLUGIN_DIR 指向其他插件 checkout）。
• 数据变更后需要把新的 dist/<target>/rime/shared/ 同步进插件树的 rime/shared/，并更新插件仓库的 rime/bundle.version 触发 full maintenance。

ABI 契约与升级

• include/krime.h 是插件与 native 之间的稳定契约；插件侧 rime.koplugin/ffi/krime_h.lua 保存同一份声明，rime_ime.lua 的 ABI_VERSION 与 krime.h 的 KRIME_ABI_VERSION 必须一致（当前为 3）。
• 修改 struct 布局、函数签名或语义时：同步更新 krime.h 的 KRIME_ABI_VERSION、krime_h.lua 的声明与 rime_ime.lua 的 ABI_VERSION，并在插件发版时保持两边版本一致。
• 插件启动时校验 krime_abi_version() 与 krime_state_sizeof()，不匹配会安全 回退到 KOReader 原生输入法并在 crash.log 记录错误。
• schema switches API（krime_get_option/krime_set_option/ krime_get_schema_switches/krime_get_session_switches）是纯追加：不改变 既有符号与 struct 布局。插件侧通过运行期符号探测 （RimeIME:hasSwitchesSupport()）兼容不含这组接口的旧产物——旧 .so 不显示 选项 UI，输入功能不受影响。

测试

• build/<target>/zig-probe/libzig_probe.so：每次 Zig 构建最先执行的 ABI gate。
• scripts/verify-elf.sh <target> <ELF>：对任意产物重复执行 target-aware 校验。
• dist/<target>/smoke_native：上传目标设备后执行的 native API smoke。
• 插件仓库的 rime.koplugin/tests/smoke_*.lua：FFI、IME、schema 与用户学习 集成 smoke，需要本模块产物配合运行。

产物

• dist/<target>/librime_koreader.so：最终 native wrapper。
• dist/<target>/smoke_native：上传目标设备后执行的 native smoke test。
• dist/<target>/rime/shared/：构建得到的共享 Rime 数据。

不要把 build/、dist/ 内的测试程序或主机工具放进插件发布包。