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"

三个注意点:

  1. data/ 一起没了。 要留用户数据就先 adb pull 出来;
  2. 如果应用正开着,先回桌面(应用跑的时候 bbui 不在,删目录不影响运行中的进程,但回桌面后会少一个图标);
  3. 只删目录里的一部分(比如只删入口)会让卡片变灰而不是消失——想彻底消失就删整个目录。

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"

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 生命周期:从点图标到回桌面,每个进程在等什么。

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