97 lines
7.5 KiB
Markdown
97 lines
7.5 KiB
Markdown
# MeowOS SDK for HiBy R3 Pro II
|
||
|
||
MeowOS 应用框架 SDK 的**公开仓库**——面向第三方开发者，让你为运行 MeowOS 的 **HiBy R3 Pro II** 写自己的 App。
|
||
|
||
本仓库把 MeowOS 的 App 框架（`meow_ui`）与相关开发文档独立发布出来，自带示例与构建脚本，**自包含、开箱即构建**，不依赖 MeowOS 主仓。
|
||
|
||
> 快速上手见 [docs/APP_DEV_GUIDE.md](docs/APP_DEV_GUIDE.md)；SDK 设计全量见 [docs/MEOW_APP_SDK.md](docs/MEOW_APP_SDK.md)。
|
||
|
||
## 设备与平台
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 设备 | HiBy（海贝）R3 Pro II |
|
||
| 架构 | MIPS32r2（**mipsel**，little-endian，soft-float） |
|
||
| 屏幕 | 480×720，RGB565（代码里颜色统一 24-bit `0xRRGGBB`，SDK 内部转 RGB565） |
|
||
| 可执行格式 | **静态** MIPS32r2 ELF（编译 `-Os -static`） |
|
||
| 底层系统 | MeowOS（Linux 系，非 Android） |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
MeowOS-SDK/
|
||
├── sdk/ # meow_ui 应用框架静态库源码（自包含，可交叉 → sdk/meow_ui.a）
|
||
│ ├── meow_ui.h # 伞头（#include 聚合 include/ 子头；App 只 include 这个）
|
||
│ ├── include/ # 24 个模块子头（含 box/anim/scroll/str/lazygrid/select/cachegov/net 通道等）+ meow_ipc.h / meow_font.h / meow_notif.h（vendored）
|
||
│ ├── meow_font.c # 预渲染位图字体运行时（meow_font.a 源码，自包含）
|
||
│ ├── build_sdk.sh # 交叉编译 meow_ui.a（mipsel 静态库，内含 meow_font.o）
|
||
│ └── test_*.c # SDK 宿主逻辑测试（test_host_stub.c 打桩，无硬件可跑）
|
||
├── examples/hello/ # 最小示例 App（meow_view 框架，多文件分层）
|
||
│ ├── app.c # main + 装配 + 事件分发（把 meow_ui_run 回调路由到各页）
|
||
│ ├── ui/ # 每页一个 view 文件（home/demo/list/full/chrome）
|
||
│ ├── logic/ # 纯 C 业务逻辑（不依赖 meow_ui.h，宿主可裸测）
|
||
│ └── build_hello.sh # 构建 hello（链 meow_ui.a + libz.a + -lpthread）
|
||
└── docs/
|
||
├── APP_DEV_GUIDE.md # 第三方开发上手指南（环境 → 最小 App → 构建打包 → 签名安装 → 调试）
|
||
└── MEOW_APP_SDK.md # SDK 设计全量规范
|
||
```
|
||
|
||
## 快速上手
|
||
|
||
```sh
|
||
# 1) 构建 meow_ui.a（交叉）
|
||
cd sdk
|
||
./build_sdk.sh # 产出 sdk/meow_ui.a
|
||
|
||
# 2) 构建示例 App hello
|
||
cd ../examples/hello
|
||
./build_hello.sh # 产出 examples/hello/hello（静态 MIPS32r2 ELF）
|
||
```
|
||
|
||
## SDK 能力速览
|
||
|
||
统一控件 / 输入 / 主题 / 字体 / 通知 / 导航之外，本版 SDK 还提供（详见 [docs/MEOW_APP_SDK.md](docs/MEOW_APP_SDK.md)）：
|
||
|
||
- **布局引擎 `meow_box`**（§12.1）：线性布局纯计算器——固定/权重/wrap 尺寸、间隙/边距、主轴与交叉轴对齐、嵌套子 box；`meow_view_set_layout` 与视图框架 opt-in 集成。
|
||
- **动画基座 `meow_anim` / `meow_anim_tick`**（§12.2）：声明式 tween（linear/ease-out/ease-in-out/overshoot），静态池 ≤16，无动画零开销；只 flush 动画影响区。
|
||
- **滚动物理 `meow_scroll`**（§12.3）：速度采样 + 松手 fling + 边界 clamp/简单回弹 + snap 吸附；给 `meow_list`/`W_LIST`/`W_LISTVIEW` 加惯性滚动。
|
||
- **事件分发形式化**（§6.4）：单一仲裁者——z 序自顶向下命中、命中即消费、down 捕获整个手势、模态层隔离、唯一焦点（点外释放/滚动容器转移）。
|
||
- **ListView 虚拟化**（§5.5）：固定 item 池（视口+2）、多行富 item、段头、空态、完全自绘钩子；App 只提供「总数 + bind」回调，几千/上万行不卡。
|
||
- **ListView 左滑删除**（§5.5）：列表行横向手势 `meow_listview_swipe_begin/move/end` 三级喂入 + 删除/回弹动画；`meow_listview_set_swipe_delete` 绑删除回调，行自绘 `set_item_draw` 配合画右露删除区（主题 `error/onError`）。
|
||
- **圆形图标按钮 `meow_iconbtn_create`**（M7.0a）：圆形命中 + 位图图标（`sb_icons[]`/`MEOW_ICON_*`）+ 实时按压/按住态；供电源菜单/播放控制/锁屏件用。
|
||
- **字符串资源 / i18n**（§13）：`meow_str`/`meow_strf`/`meow_str_set_locale`——内嵌 `zh_cn`/`en_us` 双语表 + TF 卡覆盖表；UI 文案零硬编码，按 locale 取整串。
|
||
- **图标库 `sb_icons`**（§5.8）：30 个 MD3 Material Symbols 位图动作图标（`MEOW_ICON_*`），`meow_topappbar_set_item_icon` 把 TopAppBar 动作项换成位图图标（修复 ⚙↻⌕ 豆腐）。
|
||
- **图片降采样 `meow_img_downscale`**（`include/meow_ui_image.h`）：把解码图降到 ≤maxdim 边长省内存（封面/大图用，如 8.28MB→0.78MB）。
|
||
- **2 维虚拟化宫格 `meow_lazygrid`**（§12.4）：卡片/图标宫格二维虚拟化——只实例化可见行（固定 item 池 ≤96、视口行数+2×cols），`count+bind` 数据源、长列表不卡；命中 `meow_lazygrid_hit/tap_at` 把滚动+网格坐标映射回 item idx；滚动复用 `meow_scroll`（fling/snap）。
|
||
- **枚举/预设选择器 `meow_select`**（§5.8.6）：开箱即用下拉模态——BottomSheet（标题 + `meow_listview` SINGLE 单选列表）+ `meow_ui_modal_capture/restore` 背景快照（关闭无残影）；点选项=选中+`on_change` 回调，点面板外/左缘=取消。
|
||
- **磁盘页缓存治理 `meow_cachegov`**（OOM_PAGECACHE_GOVERNANCE）：App 登记缓存文件 + read_pos 回调，SDK 做 DONTNEED 治理（L0 曲终整文件丢 / L1 播放中丢已读前缀保 keep_hot 窗口）；refault 滚窗逐级回退（放大 keep_hot→降 L0→关 A）；`meow_cachegov_download/prefetch_paused` 提供给下载/预取方降载查询。
|
||
- **网络自愿通道 `meow_ui_net`**（netmgrd 期 4）：联网前 `meow_net_policy_check(host)` 自查是否被策略放行（netmgrd 不在/超时→乐观放行）；`meow_net_report(rx,tx)` 自愿上报本进程收发字节（best-effort，失败静默）。
|
||
|
||
## 构建要求
|
||
|
||
- **交叉工具链**（mipsel musl 静态）：MeowOS 开发机默认路径
|
||
`$HOME/Project/R3ProII/.tools/zig-mipsel-cc`（zig 包装，`--target=mipsel-linux-musleabi` soft-float）
|
||
与对应 sysroot（含 `libz.a`）。可用环境变量覆盖：`MEOW_CC` / `MEOW_SYSROOT`。
|
||
- GNU `ar`（归档 mipsel 对象，架构无关）。
|
||
- 宿主逻辑测试（无硬件，`gcc` + `test_host_stub.c` 打桩）：
|
||
```sh
|
||
cd sdk
|
||
gcc -I. -Iinclude test_umbrella.c <各 sdk 源 .c> test_host_stub.c -lpthread -o test_umbrella
|
||
./test_umbrella
|
||
```
|
||
参考 [docs/APP_DEV_GUIDE.md §1.2](docs/APP_DEV_GUIDE.md)。
|
||
- 注意：改 SDK 源码（尤其 `meow_ui_theme`/`meow_widget` 结构）即 ABI 变化，**必须同步重编 `meow_ui.a` 与你的 App**。
|
||
|
||
## 与 MeowOS 主仓的关系
|
||
|
||
本仓库由 MeowOS 主仓（`MeowOS-For-R3P2`）经 `git subtree split` 拆出，只含公开的 SDK / 示例 / 文档：
|
||
|
||
- `sdk/` 对应主仓 `patch_v2/sdk/`，`examples/hello/` 对应主仓 `patch_v2/hello_app/`，`docs/` 对应主仓 `docs/APP_DEV_GUIDE.md` + `MEOW_APP_SDK.md`。
|
||
- **不含**主仓的系统组件（launcher / amsd / audiod / svc_* / netmgrd 等）、固件、签名工具、**密钥**。
|
||
- 本仓库中的 `build_sdk.sh` / `build_hello.sh` 已改造为**自包含**（`meow_ipc.h`/`meow_font.h`/`meow_notif.h`/`meow_font.c` 一律在 `sdk/` 内 vendored，不再依赖主仓 `meow_launcherd/`），与主仓内的同名脚本存在差异。
|
||
- SDK 增量同步（主仓 `patch_v2/sdk` 更新后再推本仓）的方法见主仓 `devdocs/` 与 `scripts/` 中的拆分记录。
|
||
|
||
## 许可证
|
||
|
||
MIT License——版权 **"MeowOS contributors"**，见 [LICENSE](LICENSE)。
|