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 是和你一起编译进可执行文件的。
好处:
- 设备上不需要放 SDK 运行时文件,部署包少一个组件;
- 你用的 SDK 版本永远和你编译时看到的一致,不会出现"设备上的 libbbapp 比头文件旧";
- 出问题只有一个二进制要看。
代价:
- SDK 修了 bug,你的应用必须重新编译才会拿到修复;
- 你的应用和 SDK 是同一个进程,SDK 的崩溃就是你的崩溃。
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 兼容性检查清单(发布前)
- [ ] 用当前仓库的
sdk/bbapp.h+bbapp_run.c重新编译 - [ ]
python sdk/mkbbapp.py . --check通过 - [ ] 包里没有
.c/.sh/.so(unzip -l看一眼) - [ ] 真机上走完:起 → 点 → 返回 → 再起一次
- [ ] 应用运行期间
gui/sub_gui/dji_camera3是 inactive - [ ]
app.log里没有EVIOCGRAB 失败 - [ ]
data/在重启后仍然可读
下一步 → 12 路线图。