SDK 文档 / 11 · 版本与兼容

11 · 版本与兼容

这套 SDK 没有动态库、没有符号版本、没有 ABI 协商。它的"兼容性"完全是源码级的,所以这一章的核心结论很短:跟着头文件一起编译,别假设二进制能长期跑。

11.1 三个"版本"别搞混

名字 在哪 谁读 作用
BBAPP_API_VERSION sdk/bbapp.h 没人读(编译期常量) 源码层面的能力锚点,写条件编译用
abi app.json mkbbapp.py(要求 >=1 整数) 清单格式版本,bbui 不读
version app.json bbui(只显示)、你 应用自身版本,纯展示

换句话说:装到设备上的应用,没有任何运行时版本检查。bbui 只认目录里有没有app.json 和入口文件,然后直接 exec 它。

已经发过的 API 版本

版本 加了什么 老代码怎么办
1 初版:16 个符号(运行时 + 绘制 + 主题色) ——
2(2026-11-03) 输入 down/move/up/long_press、生命周期 pause/resume/destroy、bbapp_battery/charging/wifi/wall_now、KV 存储、异步 HTTP、控件层 bbapp_ui.c、文本输入/拼音键盘 bbapp_ime.c 源码不用改,但编译命令要加 sdk/bbapp_ui.c 和 sdk/bbapp_ime.c —— bbapp_run.c 引用控件层符号,只编前者会链接失败(不用输入法也要编,因为 bbapp_ui.c 没拆开)

v2 只加字段和函数,没有改任何已有符号的语义。bbapp_app 里新增的字段都是可选回调,用指定初始化器(.draw = ...)的老代码编出来这些字段是 NULL,SDK 侧全部判空。

11.2 为什么是源码分发

SDK 没有编译成 .so 或 .a,bbapp_run.c 是和你一起编译进可执行文件的。

好处:

代价:

11.3 运行时依赖兼容

依赖 设备提供 变化风险
glibc Debian 12 的 2.36;我们按 2.28 编译 低(向下兼容)
libcairo.so.2 1.16 低(soname 稳定)
libwayland-client.so.0 1.21 低
fontconfig / freetype 系统自带 低
weston(DJI 定制) 系统自带 高:wl_shell 的可用性、触摸设备名都可能随固件变
/blackbox/svc/app-run.sh 部署器 高:换了部署包就可能换行为
DJI 服务名(gui/sub_gui/dji_camera3) 固件 高:固件更新可能改名,脚本的压制就失效

结论:固件升级后要重新验一遍。要验的最小集合:能起、能点、能返回、相机不抢屏。

11.4 什么时候必须重新编译应用

变更 要不要重编
SDK 修了触摸/绘制 bug 要(SDK 是源码内置的)
bbapp.h 加了字段/函数 不必须(结构体前缀兼容),但建议重编
bbapp.h 删/改了函数签名 要(否则链接失败)
部署器换了 app-run.sh 的路径或参数 要(应用的入口约定变了)
设备固件升级 要(至少重验)
只改了 app.json 不要

11.5 结构体演进的约定

bbapp_app 未来要加字段(比如 move 回调、long_press)时,只允许在尾部追加:

typedef struct {
    const char *id;
    const char *name;
    int  (*init)(void);
    void (*draw)(cairo_t *, int, int);
    int  (*tap)(int, int);
    void (*tick)(double);
    /* ↓ 新字段只会加在这里 */
} bbapp_app;

因为应用一律用指定初始化器(.draw = ...)且是静态常量,未写的字段自动为 0(NULL),SDK 侧对每个可选回调都做了判空。于是旧源码 + 新 SDK 重新编译时,不需要改一行代码就能用上新版本;新字段只要不被赋值,就等于"没实现这个回调"。

static const bbapp_app g_app = {
    .id = "com.example.hello", .name = "示例",
    .draw = app_draw,          /* 其它字段省略 = NULL */
};

反面写法(不要用)——位置初始化,一加字段就全错位:

static const bbapp_app g_app = { "id", "名字", NULL, app_draw, NULL, NULL };

11.6 应用自己的版本管理

场景 建议
改了界面/行为 version 进位(1.0.0 → 1.0.1),重新打包
只是修 typo 也进位,省得"两个 1.0.0 不一样"
data/ 里的文件格式变了 在 data/ 里写 schema.txt,init 时读,版本不匹配就迁移或重置
想同时留旧版 换 id(等于另一个应用),不要在同一目录里覆盖

data/ 迁移的最小实现:

static void migrate(void) {
    char p[600], buf[32] = {0};
    snprintf(p, sizeof p, "%s/schema.txt", bbapp_data_dir());
    FILE *f = fopen(p, "r");
    if (f) { fgets(buf, sizeof buf, f); fclose(f); }
    if (atoi(buf) != 2) {
        bbapp_log("data schema %s -> 2,重置", buf[0] ? buf : "(空)");
        /* 这里做迁移或直接删旧文件 */
        f = fopen(p, "w");
        if (f) { fputs("2\n", f); fclose(f); }
    }
}

11.7 兼容性检查清单(发布前)


下一步 → 12 路线图。

bbui 第三方应用 SDK · API 1 · 本文档随仓库 docs/sdk 自动生成