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"] }

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 }

开启后:

细节与失败兜底见 05 生命周期。

icon — 自定义图标(可选,2026-11-03 起已生效)

{ "icon": "assets/icon.png" }

3.3 目录布局与"可写区"

/blackbox/apps/<id>/
    app.json      清单
    <entry>       可执行文件
    assets/       只读资源(SDK 通过 bbapp_assets_dir() 给出路径)
    data/         可写数据(bbui 扫目录时自动 mkdir,跨次保留)
    app.log       SDK 与 app-run.sh 写的日志

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 的确切格式、白名单、安装/卸载/升级的完整流程。

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