SDK 文档 / 08 · 运行时环境
08 · 运行时环境
应用跑在什么 shell 里?有哪些环境变量?能碰哪些文件?会被谁杀掉?这一章是"部署/排障"视角,不涉及 API。
8.1 进程与单元
system.slice
├─ run-<id>.service ← ui-start.sh 用 systemd-run 起的临时单元,里面是 blackbox-ui(bbui)
└─ bbui-app-<pid>.service ← 点图标后由 systemd-run 起的临时单元,里面是 app-run.sh + 你的应用
- 两个单元平级,互不牵连:bbui 退出时它的 cgroup 被拆,
bbui-app-*不受影响; --collect表示单元退出即被 systemd 回收,不会堆积;- 查看:
adb shell "systemctl list-units --type=service --all | grep bbui"
adb shell "systemctl status bbui-app-12345 --no-pager"
为什么必须这样:如果应用和 bbui 在同一个 cgroup 里,bbui 退出时 cgroup 被拆,应用会被一起杀(实测活 1 秒,连 app-run.sh 的退出日志都来不及写)。
8.2 文件布局
/blackbox/
├── apps/ 第三方应用根目录(bbui 扫这里,mtime 变了重扫)
│ └── <id>/
│ ├── app.json
│ ├── <entry>
│ ├── assets/ 只读(包内带)
│ ├── data/ 可写(bbui 建,升级保留)
│ └── app.log 日志(脚本 + SDK)
├── opt/bin/
│ ├── bbui 短命令:exec ui-start.sh
│ ├── blackbox-ui bbui 本体
│ └── ui-start.sh 停 DJI 界面 → 起 blackbox-ui
├── svc/
│ └── app-run.sh 应用启动器(等 bbui 退、设环境、守 DJI、兜底)
├── fonts/ 字体(文泉驿微米黑 + 符号字体)
└── tmp/ 临时区(adb push 落点,重启不保证保留)
| 路径 | 谁创建 | 谁可以写 |
|---|---|---|
/blackbox/apps/<id>/ |
你(安装时) | root |
.../assets/ |
包内带来 | 你(升级时),运行期只读约定 |
.../data/ |
bbui(扫目录时 mkdir_p) |
应用自己 |
.../app.log |
app-run.sh 首次写入 |
脚本 + SDK |
约定:除了 data/,其它位置都可能在下次部署/升级中被覆盖。持久化数据一律写 data/。
8.3 环境变量
app-run.sh 会导出这些(bbui 也会继承一份,脚本里再兜一次默认值):
| 变量 | 值 | 谁用 |
|---|---|---|
XDG_RUNTIME_DIR |
/run/user/root |
wayland 客户端库 |
WAYLAND_DISPLAY |
wayland-1 |
同上 |
BBAPP_DATA |
<app>/data |
bbapp_data_dir() |
BBAPP_ASSETS |
<app>/assets |
bbapp_assets_dir() |
BBAPP_LOG |
<app>/app.log |
bbapp_log() |
LD_LIBRARY_PATH |
<app>(lib/ 存在时再加 <app>/lib) |
动态链接器找应用自带的 .so |
SDK 还认这些调试用覆盖(生产别设):
| 变量 | 作用 |
|---|---|
BBAPP_W / BBAPP_H |
强推画布尺寸 |
BBAPP_ROT |
0/90/180/270 |
BBAPP_OUTPUT |
只考虑指定名字的 output |
BBAPP_TOUCH |
指定触摸设备路径(/dev/input/eventN) |
BBAPP_NOGRAB |
有值则不 EVIOCGRAB(触摸与系统共享) |
注意:BBAPP_DATA 等变量如果缺失,SDK 会退化成当前目录("."),这是为了方便在电脑上跑逻辑;在设备上缺失会导致数据写到应用目录里,别依赖。
8.4 安全边界(请认真读)
| 项 | 事实 |
|---|---|
| 运行用户 | root(整个系统就是 root) |
| 沙箱 | 没有。没有 seccomp、没有 namespace、没有 SELinux 约束 |
| 能碰什么 | 全部。包括 /blackbox、/data、DJI 的服务、其它应用的数据 |
| 能杀什么 | 除 PID 1 之外的一切(bbui 自己的"任务管理"页就限制不许杀 PID 1) |
| 网络 | 有(和系统其它进程一样) |
| 崩溃影响 | 只影响自己(独立 cgroup),回到桌面即可 |
所以:
- 应用是可信代码。装一个应用 = 给它 root。只装你信任的
.bbapp; - 包里没有签名、没有校验清单,安装路径也不检查来源;
- 不要写"沙箱内测"之类的假设;
- 想做权限声明只能做展示("这个应用需要 shell 权限"),拦不住任何东西。
8.5 资源与限制
| 项 | 限制 | 说明 |
|---|---|---|
| 应用数量 | 64(BB_APPS_MAX) |
桌面最多显示 26 个内置 + 64 个第三方 |
app.json 大小 |
1 MB | 超过按"读不到"处理(灰卡片) |
| 字段长度 | id/name 63 B、version 23 B、entry 95 B | 超出静默截断 |
bbapp_toast 文本 |
191 B | 超出截断 |
| 帧缓冲 | 3 × 1.09 MB(712×400×4) | 三块轮转,防"画面停帧" |
| 内存 | 没有限制 | 但要和系统抢,OOM 时内核挑大的杀 |
| CPU | 没有限制 | 全屏重绘是纯 CPU 工作,别做无谓的每帧重绘 |
| 磁盘 | 没有配额 | /blackbox 分区容量有限,别写大文件 |
8.6 日志
一个 app.log 里混着两种时间戳,看的时候注意区分:
[20:11:03] === app-run 开始: /blackbox/apps/com.example.hello/hello === ← 脚本(HH:MM:SS)
[1762xxxxxx] [bbapp] 启动 com.example.hello (示例) 画布 712x400 ← SDK(epoch 秒)
hello: 我自己用 printf 打的 ← 应用的 stdout/stderr
[20:15:22] 应用退出 rc=0 -> 回 bbui ← 脚本
- 应用的
stdout/stderr都被重定向到app.log(脚本里>> "$LOG" 2>&1),所以printf调试也能看到; - 日志不会自动滚动,反复跑会一直变大。要清就
adb shell "> /blackbox/apps/<id>/app.log"; bbapp_log()同时写stderr和app.log,两种都能看到。
8.7 单实例与并发
- 单实例靠"同一时间只有一个前台"这个约束自然保证:bbui 在拉起应用前就退出了,用户没有机会点第二次;
- 但没有锁文件。如果有人从 adb 手动跑第二个实例,两个进程会抢同一个触摸设备(后启动的
EVIOCGRAB失败),画面也会打架; - 需要后台任务时用
bbapp_shell()起的子进程会在应用退出后继续存在(setsid),记得自己在下次启动时判断/清理,否则会越积越多。
8.8 设备端能用的东西
写应用时可以假设这些存在(都是系统自带的):
| 类别 | 可用的 |
|---|---|
| libc | glibc 2.36(编译时按 2.28 更保守) |
| 图形 | libcairo2(1.16)、libwayland-client0(1.21)、libpng、libfreetype、fontconfig |
| 字体 | /blackbox/fonts 里的文泉驿微米黑(WenQuanYi Micro Hei)+ 符号字体 |
| shell | Debian 的 /bin/sh(dash)、busybox、常见 coreutils |
| 服务管理 | systemctl、systemd-run、journalctl |
| 调试 | strace(部分镜像)、top、ps、dmesg |
不要假设存在:Python、Node、Qt/GTK、X11、GPU 加速的 cairo、网络工具(curl/wget 有,但 DNS 需要部署器配好的 114)。
8.9 部署会覆盖什么
跑一次部署器会:
- 覆盖
/blackbox/opt/bin/*、/blackbox/svc/*、/blackbox/fonts/*; - 不碰
/blackbox/apps/(你的应用和数据都在里面); - 重新注册字体缓存(
fc-cache)。
所以升级 bbui/部署器不会丢应用,但会换掉 SDK 运行时的行为(如果是随 bbui 一起改的),重新编译一次应用最保险。
下一步 → 09 API 参考:逐个函数的完整签名、参数、返回值与示例。