SDK 文档 / 03 · 应用清单 app.json
03 · 应用清单 app.json
清单是 bbui 唯一读的文件。读不懂它,图标就变灰。这一章给出每个字段的准确语义、长度上限、出错时会发生什么,以及解析器的怪癖。
3.1 完整示例
{
"id": "com.example.hello",
"name": "示例应用",
"version": "1.0.0",
"entry": "hello",
"author": "you",
"description": "一句话说明这个应用干什么",
"abi": 1,
"files": []
}
最小可用清单只有 4 个字段:
{ "id": "com.example.hello", "name": "示例", "version": "1.0.0", "entry": "hello" }
3.2 字段参考
id — 应用标识(必填)
| 项 | 值 |
|---|---|
| 类型 | 字符串 |
| 上限 | 63 字节(UTF-8,超出静默截断) |
| 格式 | 建议反向域名:com.<作者>.<应用>,只用 [a-z0-9._-] |
| 缺省 | 目录名 |
用途:日志里的标识、bb_apps_find() 的查找键。注意它和安装目录名可以不同——桌面卡片按目录扫到的顺序显示,不按 id 排序。安装脚本建议让目录名 = id,否则将来做"卸载某个应用"时容易对不上。
name — 显示名(必填)
| 项 | 值 |
|---|---|
| 类型 | 字符串 |
| 上限 | 63 字节 |
| 缺省 | 回退成 id |
桌面卡片上用这个(中文 OK),卡片左边那个圆形图标取它的第一个字符(英文自动转大写,中文取第一个 UTF-8 字符)。超长不会换行,会画到卡片外面,别超 6 个字。
version — 版本(必填)
| 项 | 值 |
|---|---|
| 类型 | 必须是字符串("1.0" 对,1.0 错) |
| 上限 | 23 字节 |
| 缺省 | 空字符串(卡片下方不显示版本号) |
bbui 不比较版本,只显示。mkbbapp.py 会在 version 不是字符串时直接拒绝打包。
entry — 入口可执行文件(必填)
| 项 | 值 |
|---|---|
| 类型 | 字符串 |
| 上限 | 95 字节 |
| 语义 | 相对应用目录的文件名,或绝对路径(以 / 开头) |
| 缺省 | bbui 侧回退成 run;mkbbapp.py 侧视为错误 |
三种情况:
| 写法 | 实际路径 |
|---|---|
"entry": "hello" |
/blackbox/apps/<dir>/hello |
"entry": "bin/app" |
/blackbox/apps/<dir>/bin/app(包里需要有 bin/,用 files[] 声明) |
"entry": "/usr/bin/python3" |
设备上的绝对路径(此时应用目录里可以不放可执行文件) |
入口不存在 → 卡片变灰 + 点击提示"应用装坏了:<name>"。入口存在但没有执行位 → bbui 自动补 0755,不用你 chmod。
author / description — 可选
只给人看,bbui 目前不读(将来应用详情页会显示)。长度别超过 200 字节。
abi — 清单格式版本(可选)
| 项 | 值 |
|---|---|
| 类型 | 整数 |
| 默认 | 1 |
| 校验 | mkbbapp.py 要求 >= 1 的整数,否则拒绝打包 |
【重要】bbui 不读这个字段。 它只是给打包器/将来的应用商店用的格式版本号。真正决定"这个应用能不能在这台机器上跑"的是它链接了什么(见 11)。
files — 额外要打包的文件 / 目录(可选)
mkbbapp.py 白名单之外的东西(bin/、lib/、数据表……)列在这里:
{ "files": ["bin", "lib", "assets/font.ttf", "data/seed.db"] }
- 路径相对应用目录,用
/分隔; - 写目录会整目录递归收(
bin=bin/**),方便带辅助程序和自带库; - 不允许
..跳出应用目录、不允许绝对路径(会直接拒绝打包); - 列了不存在的文件 → 打包失败;
- 已经会被自动收进去的(
app.json、entry、assets/**)重复列不会报错,只会去重。
bbui 完全不读这个字段——它只是打包清单。多文件的运行期支持见 04。
exec — 额外标可执行的包里文件(可选)
{ "exec": ["bin/helper", "lib/run.sh"] }
zip 里每个文件的权限位由打包器写进 external_attr,unzip 会照它还原。打包器自动判断可执行的规则:源文件有执行位 → 可执行;后缀 .sh/.py/.pl → 可执行;无后缀且文件头是 \x7fELF → 可执行。Windows 上开发时前两条常常不成立(NTFS 没有执行位),所以要么让辅助程序带 .sh 后缀,要么在这里显式列出来。
entry 永远被视为可执行,不用写进 exec。
needs — 能力声明(可选,只做展示)
{ "needs": ["shell", "camera", "network"] }
| 项 | 值 |
|---|---|
| 类型 | 字符串数组 |
| bbui 怎么用 | 解析成 shell, camera, network,在桌面「应用 → 详情」里显示 |
| 有没有强制力 | 没有。应用以 root 跑,能碰什么就是能碰什么(见 08) |
建议用的词(非强制,只是给人看):shell camera network storage audio input http background。从 API v2 起这些能力大多有对应 API(存储 / HTTP / 电量),清单里声明只是为了在管理页告诉用户。数组里非字符串的项会被忽略;不支持嵌套对象(解析器只认平铺字符串)。
background — 后台常驻(可选,默认 false)
{ "background": true }
开启后:
- 点「返回」不结束进程:释放触摸、销毁 surface、写
<app>/run.pid,进程继续跑(tick照常); - 桌面「应用」详情显示「后台中」,可一键「停止后台进程」;
- 再点桌面图标 = 给后台实例发
SIGUSR1,让它重建 surface 重新上屏,不会起第二个实例; - 后台期间没有 surface,
draw不会被调用,别再往屏幕上画。
细节与失败兜底见 05 生命周期。
icon — 自定义图标(可选,2026-11-03 起已生效)
{ "icon": "assets/icon.png" }
- 相对应用目录的路径,也接受绝对路径;没写就自动找
assets/icon.png; - 建议 96×96 PNG(卡片最大画到 40×40,按设备像素);透明背景可以,圆角由宿主裁;
- 加载失败(文件不在/不是 PNG)→ 回退成"名字首字 + 版本"的色块,不会白块;
- 图标只加载一次并缓存,扫描目录(装/卸/刷新)时重建。
3.3 目录布局与"可写区"
/blackbox/apps/<id>/
app.json 清单
<entry> 可执行文件
assets/ 只读资源(SDK 通过 bbapp_assets_dir() 给出路径)
data/ 可写数据(bbui 扫目录时自动 mkdir,跨次保留)
app.log SDK 与 app-run.sh 写的日志
data/由 bbui 创建(slot_load()里的mkdir_p()),不是 SDK 建的,也不是你建的;app.log由app-run.sh追加,SDK 也往里面写(两种时间戳格式,见 10);- 其它任何位置都可能被下一次部署覆盖,别往
/blackbox/apps/<id>以外的地方写数据。
3.4 出错时会发生什么
| 情况 | bbui 的行为 | 桌面表现 |
|---|---|---|
没有 app.json |
用目录名当 id 和 name,标记 failed |
灰卡片,点了提示"应用装坏了" |
app.json 不是合法 JSON |
同上(极简解析器读到哪个算哪个) | 同上 |
app.json > 1 MB |
直接视为读不到 | 同上 |
缺 id |
用目录名 | 正常显示 |
缺 name |
用 id |
正常显示,卡片上是 id |
缺 version |
空字符串 | 正常显示,卡片下方无版本号 |
缺 entry |
回退 run;文件不在 → failed |
灰卡片 |
entry 文件不存在 / 不是普通文件 |
标记 failed | 灰卡片 |
entry 没有执行位 |
自动 chmod 0755 |
正常 |
| 目录里有非目录文件 | 忽略 | —— |
| 应用数超过 64 | 只加载前 64 个(BB_APPS_MAX) |
后面的不显示 |
灰卡片仍然可以点,点了给 toast 提示——这是故意的,比"图标凭空消失"好排查。
3.5 解析器的四个怪癖(会咬人)
bbui 里没有 JSON 库,src/apps.c:js_get() 就是一个 strstr + 手写扫描。它足够快、零依赖,但有明确的行为边界:
① 键是"全局搜索第一个匹配",不认层级
{ "description": "这个 \"name\" 只是举例", "name": "真名" }
js_get("name") 会先命中 description 里的 "name",值变成 只是举例。👉 不要在描述/其它字段的文本里写带双引号的键名。
② 反斜杠转义只"跳过"下一个字符
{ "name": "第一行\n第二行" }
结果是 第一行n第二行 —— \n 不会变成换行,因为解析器把 \ 和 n 当成"转义后的字符 n"。👉 要换行就直接用真的换行(JSON 字符串里不允许)或干脆别换行。
③ 重复键:bbui 取第一个,Python 打包器取最后一个
{ "version": "1.0.0", "version": "2.0.0" }
bbui 显示 1.0.0,mkbbapp.py 打出的包名是 -2.0.0.bbapp。👉 不要写重复键。
④ 文件必须是 UTF-8 且不带 BOM
Python 侧的 mkbbapp.py 遇到 BOM 会报"不是合法 JSON";bbui 侧能读但也别赌。👉 用编辑器保存成 "UTF-8 (无 BOM)",换行 LF 或 CRLF 都可以(bbui 的扫描会跳过 \r)。
3.6 命名与版本约定(建议)
| 场景 | 约定 |
|---|---|
| 应用目录名 | 与 id 一致:/blackbox/apps/com.example.hello |
| 包文件名 | mkbbapp.py 自动生成:<id>-<version>.bbapp |
| 版本号 | 语义化三段 1.2.3;改了界面/行为就进位 |
| 升级 | 解压覆盖同目录即可(unzip -o);data/ 不会被覆盖,因为包里没有 data/ |
下一步 → 04 打包与安装:.bbapp 的确切格式、白名单、安装/卸载/升级的完整流程。