SDK 文档 / 04 · 打包与安装
04 · 打包与安装
.bbapp就是个 zip,没有任何私货格式。这一章讲清楚包里允许有什么、不允许有什么,以及装/卸/升级在设备上到底动了哪些文件。
4.1 包格式
.bbapp = ZIP(deflate),根目录即应用根:
com.example.hello-1.0.0.bbapp
├── app.json 必需
├── hello 必需(名字 = app.json 的 entry)
├── assets/ 可选,只读资源
│ └── icon.png
└── bin/ 可选,用 files[] 声明的其它文件
| 规则 | 说明 |
|---|---|
| 没有顶层目录 | 直接是 app.json,不是 xxx/app.json |
不含 data/ |
可写区由设备创建,包里永远不带(否则升级会覆盖用户数据) |
| 不含源码 | 白名单机制保证 app.c / build.sh 不会误进包 |
| 不保留执行位 | zip 不存 Linux 权限位,由 bbui 扫描时自动补 0755 |
| 不签名 | 没有签名机制,也没有校验和清单(见 11) |
| 编码 | 包内路径用 /;文件名避免中文和空格 |
4.2 白名单:包里到底收什么
mkbbapp.py 不做全目录打包,只收四类:
| 来源 | 是否必需 | 说明 |
|---|---|---|
app.json |
是 | |
app.json 里 entry 指向的文件 |
是 | 允许是子路径 bin/app |
assets/** 递归全部文件 |
否 | 跳过 data/、app.log、__pycache__、.git |
app.json 里 files[] 列出的文件/目录 |
否 | 写目录名就整目录递归收(bin、lib) |
为什么这么严:早期版本做过全目录打包,结果 app.c、build.sh、.so 中间产物一起进了安装包,多出几 MB 还泄露源码。现在的规则是"默认不收,要收就显式列"。
4.3 mkbbapp.py 参考
python sdk/mkbbapp.py <dir> [-o <输出目录>] [--check]
| 参数 | 说明 |
|---|---|
<dir> |
应用目录(必须含 app.json) |
-o, --out |
输出目录,默认与应用目录相同 |
--check |
只校验并列出将要打包的文件,不产出 zip |
退出码:0 成功;1 失败(清单缺失/非法/缺字段/abi 非法/version 非字符串/ entry 文件不存在/files[] 里列了不存在的文件)。
输出示例:
应用: 示例 (com.example.hello) v1.0.0 abi=1
入口: hello
+ app.json
+ hello
共 2 个文件 / 14.2 KB
打包完成: /path/com.example.hello-1.0.0.bbapp
14528 B (14.2 KB) sha256=9f2c...
最后三行安装提示是给你复制粘贴的,直接可用于 adb。
校验规则一览:
| 检查 | 失败信息 |
|---|---|
app.json 存在 |
没有 app.json: <path> |
| 是合法 JSON | app.json 不是合法 JSON(第 N 行): ... |
| 四个必填字段非空 | app.json 缺字段: <key> |
abi 是 >=1 整数 |
abi 必须是 >=1 的整数 |
version 是字符串 |
version 必须是字符串,例如 "1.0.0" |
entry 文件存在 |
entry 指向的文件不存在: <entry> |
files[] 每项存在 |
清单 files[] 里列了不存在的文件: <rel> |
files[] 路径不越界 |
清单 files[] 里不能用 .. 跳出应用目录: <rel> |
--check 会逐个文件打印执行位标记(x = 包内带 755,- = 644),发布前扫一眼有没有该可执行的文件是 -:
- app.json
x bin/myapp
x bin/helper
- lib/libfoo.so
4.4 安装
开发期(adb,当前唯一方式)
adb push com.example.hello-1.0.0.bbapp /blackbox/tmp/
adb shell "mkdir -p /blackbox/apps/com.example.hello && \
cd /blackbox/apps/com.example.hello && \
unzip -o /blackbox/tmp/com.example.hello-1.0.0.bbapp && \
chmod 755 hello"
chmod 其实可以不写(bbui 会补),但显式写一句能省掉"为什么第一次点它没反应"的排查。
装完为什么不用重启
bbui 每次画桌面之前会 stat("/blackbox/apps"),mtime 变了就重扫(最多 0.25 秒延迟)。所以新增/删除应用目录 = 增删图标。注意:只盯父目录的 mtime,改动 app.json 内容(目录 mtime 不变)不会触发重扫,得重启 bbui:
adb shell "bbui-stop; sleep 0.3; bbui"
安装后自检
adb shell "ls -l /blackbox/apps/com.example.hello"
# 期望看到 app.json / hello / data / app.log,hello 是 -rwxr-xr-x
adb shell "head -c 200 /blackbox/apps/com.example.hello/app.json"
图形化安装(bbui 内置,2026-11-03)
不用开电脑也能装。bbui 桌面第 2 页有一个「应用」图标(IC_FOLDER),进去就是应用管理:
桌面 → 应用
├─ 右上「安装」 → 列出 /blackbox/tmp/*.bbapp 和 /blackbox/tmp/apps/ 下的目录
│ 点一个包 → 直接装 → 自动回列表
├─ 点一行 → 右栏详情:id / 版本 / 入口 / 占用 / 能力声明 / 运行状态
│ [打开] [卸载(点两下确认)] [停止后台进程]
└─ 右上「刷新」→ 重扫目录(装完/卸载后也会自动重扫)
要点:
| 项 | 说明 |
|---|---|
| 包放哪 | .bbapp 推到 /blackbox/tmp/;或者把解开的目录放到 /blackbox/tmp/apps/<任意名>/(里面要有 app.json) |
| 依赖 | 依次尝试 /usr/bin/unzip、/bin/busybox unzip、/system/bin/busybox unzip、PATH 里的 unzip;全失败才提示"用电脑安装"。不会假装成功(真机验证过:Android 侧 + Debian 侧两条路都在) |
| 升级 | 装同 id 的包会替换旧目录,data/ 自动保留(先挪走再放回) |
| 卸载 | 删整个 /blackbox/apps/<id>,连 data/ 一起删,两步确认 |
| 失败提示 | 包没有 app.json、id 不合法(只允许字母数字 ._-)、解压失败,都会在底栏写原因 |
安装是同步的:包很大时界面会卡住一两秒,装完自动刷新列表。
4.5 卸载
图形化:桌面「应用」→ 选应用 → 点两次「卸载」。
命令行一条命令删目录:
adb shell "rm -rf /blackbox/apps/com.example.hello"
三个注意点:
data/一起没了。 要留用户数据就先adb pull出来;- 如果应用正开着,先回桌面(应用跑的时候 bbui 不在,删目录不影响运行中的进程,但回桌面后会少一个图标);
- 只删目录里的一部分(比如只删入口)会让卡片变灰而不是消失——想彻底消失就删整个目录。
4.6 多文件应用
一个应用不是只能有一个可执行文件。包里可以有任意层目录、辅助程序、自带的 .so,只要:清单里声明、执行位正确、库路径能找着。
推荐布局
myapp/
├── app.json
├── bin/
│ ├── myapp 主程序(entry = "bin/myapp")
│ └── helper 辅助程序(被主程序 fork/exec)
├── lib/
│ └── libfoo.so 自带的库
├── assets/
│ └── logo.png 只读资源
└── data/ 不进包
{
"id": "com.example.myapp",
"name": "多文件应用",
"version": "1.0.0",
"entry": "bin/myapp",
"files": ["bin", "lib"],
"exec": ["bin/helper"]
}
files 里写目录名就整目录递归收(bin = bin/**),不用一个个列。
三个必要条件
| 条件 | 谁保证 | 不满足会怎样 |
|---|---|---|
| 文件进包 | files[] 声明 |
设备上目录里没有这个文件 |
| 执行位 | 打包器写进 zip 的 external_attr;app-run.sh 再 chmod -R 755 bin/ 兜一次 |
Permission denied,主程序正常但辅助功能坏 |
| 库能被找到 | app-run.sh 设 LD_LIBRARY_PATH=$APP_DIR/lib:$APP_DIR |
error while loading shared libraries: libfoo.so |
关于执行位:Windows 上没有 Unix 执行位,chmod +x 在 Git Bash 里也读不到。打包器的规则是「有执行位 / .sh|.py|.pl 后缀 / 无后缀且 ELF 头」三者之一即可,其余必须写进 exec[]。辅助程序建议直接带 .sh 后缀,最省事。
关于库路径:app-run.sh 会把应用根目录和 lib/ 塞进 LD_LIBRARY_PATH(根目录在前,lib/ 在后),所以 libfoo.so 放哪都行。注意这是进程级的,不会影响系统其它程序。
主程序调用辅助程序
/* 主程序里:用绝对路径,别依赖 PATH 和当前目录 */
char cmd[700];
snprintf(cmd, sizeof cmd, "%s/bin/helper", bbapp_data_dir()); /* 不对!data_dir 是 data/ */
正确写法是拿应用根目录。SDK 没有提供"应用根目录",因为它是 <data_dir>/..:
char root[600], cmd[700];
snprintf(root, sizeof root, "%s", bbapp_data_dir());
char *slash = strrchr(root, '/');
if (slash) *slash = 0; /* 去掉 /data */
snprintf(cmd, sizeof cmd, "%s '%s/bin/helper' --job 1", root, root);
bbapp_shell(cmd);
app-run.sh 启动应用前会 cd "$APP_DIR",所以相对路径 ./bin/helper 也能用,但用完之后当前目录可能被你自己的代码改掉,建议一开始就拼绝对路径。
限制
| 项 | 限制 |
|---|---|
entry 长度 |
95 字节(含子目录路径),太深就超了 |
| 目录深度 | 没有限制(但要算进 entry 的长度) |
| 符号链接 | 不支持:打包器按普通文件读内容(等于把目标内容复制进去) |
| 文件数 | 没有限制;几百个小文件也能装,只是 unzip 会慢一点 |
| 白名单 | files[] 里写了什么就收什么——别把 .c / build.sh 写进去,白名单不检查内容 |
| 单文件大小 | 没有限制;但每次升级都要重新解压,大文件会拉长安装时间 |
4.7 升级
adb push new.bbapp /blackbox/tmp/
adb shell "cd /blackbox/apps/com.example.hello && unzip -o /blackbox/tmp/new.bbapp"
unzip -o覆盖同名文件,不会删旧版本里已经不存在的文件(比如你删掉了一个 assets);要干净升级就rm -rf后重装,代价是丢data/;- 版本号变了但目录名别变(目录名就是应用身份);
- 升级后如果 bbui 已经开着,重启它(原因同 4.4)。
4.8 包大小与构成
| 项 | 参考值 |
|---|---|
| 空应用(json + 一个静态链接的小程序) | 12~20 KB |
| 示例秒表 | 约 20 KB(含 cairo 绘制代码) |
| 带字体的应用 | 别带字体,设备 /blackbox/fonts 已有文泉驿,用 bbapp_text* 即可 |
| 带大资源 | 图片先压成 PNG;assets/ 里的大文件直接影响启动延迟(要解压) |
cairo 和 wayland-client 不打包:设备上由 Debian 提供(/usr/lib/aarch64-linux-gnu)。
4.9 还没有的东西
| 能力 | 状态 |
|---|---|
| 图形化安装/卸载 | ✅ 桌面「应用」屏(见 4.5) |
| 应用图标 | ✅ 清单 icon(或 assets/icon.png)直接画进卡片 |
| 包签名 / 完整性校验 | 没有,也不会加(这台机器是单用户设备) |
依赖声明(needs: [shell, camera]) |
【未实现】只有约定,见 12 |
| 应用商店 / 在线分发 | 没有 |
下一步 → 05 生命周期:从点图标到回桌面,每个进程在等什么。