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 + 你的应用
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),回到桌面即可

所以:

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                                       ← 脚本

8.7 单实例与并发

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 部署会覆盖什么

跑一次部署器会:

所以升级 bbui/部署器不会丢应用,但会换掉 SDK 运行时的行为(如果是随 bbui 一起改的),重新编译一次应用最保险。


下一步 → 09 API 参考:逐个函数的完整签名、参数、返回值与示例。

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