SDK 文档 / 02 · 快速开始
02 · 快速开始
目标:30 分钟内做出一个能装到机器上、点得动、退得回来的应用。假定你在 Windows + Git Bash 下操作(仓库里所有脚本都是 POSIX sh,Linux/macOS 同样可用)。
2.1 需要什么
| 组件 | 版本 / 位置 | 干什么 |
|---|---|---|
| zig | 0.13.0,~/Downloads/zig-extract/zig-windows-x86_64-0.13.0/zig.exe |
交叉编译器(不用装整个 GCC 工具链) |
| sysroot | <repo>/sysroot(20 MB,.gitignore 忽略) |
aarch64 的 cairo / wayland 头文件和 lib*.so.2 |
| adb | 能连上设备即可 | 推文件、看日志 |
| 设备 | 已部署 bbui(/blackbox/opt/bin/bbui 存在) |
运行容器 |
zig 不在上面那个路径时,用环境变量指定:ZIG=/path/to/zig ./build.sh。
生成 sysroot(第一次,或删了以后)
sysroot 不进版本库,从 15 个 arm64 deb 里拼出来:
python tools/build_sysroot.py --debs /path/to/sysroot-debs
需要的包(Debian 12 bookworm,arm64):
libcairo2-dev libcairo2 libfontconfig1 libfreetype6 libglib2.0-0
libpixman-1-0 libpixman-1-dev libpng16-16 libwayland-client0
libwayland-dev libx11-6 libxcb1 libxext6 libxrender1 zlib1g
脚本会做一件容易被忽略的事:deb 里的 libcairo.so.2 / libwayland-client.so.0是符号链接,Windows 解包出来是死链,脚本会用真身复制一份补齐——否则-l:libcairo.so.2 会直接报"找不到"。
成功时最后四行都是 OK:
OK usr/include/cairo/cairo.h
OK usr/include/wayland-client.h
OK usr/lib/aarch64-linux-gnu/libcairo.so.2
OK usr/lib/aarch64-linux-gnu/libwayland-client.so.0
sysroot 就绪: .../sysroot
2.2 建一个应用目录
sdk/example-hello/
app.json
app.c
app.json(清单,字段细节见 03):
{
"id": "com.example.hello",
"name": "示例",
"version": "1.0.0",
"entry": "hello",
"author": "you",
"description": "最小可运行应用"
}
app.c:
#include "bbapp.h"
/* draw 必填:每帧从干净背景开始,你负责把整个画面画出来 */
static void app_draw(cairo_t *cr, int w, int h)
{
bbapp_text_c(cr, "你好,bbui", w / 2.0, h * 0.40, 32, 1,
BB_C_TXT_R, BB_C_TXT_G, BB_C_TXT_B);
bbapp_text_c(cr, "点屏幕任意位置", w / 2.0, h * 0.40 + 40, 14, 0,
BB_C_DIM_R, BB_C_DIM_G, BB_C_DIM_B);
}
/* tap 可选:返回 1 表示吃掉了这次点击(SDK 会重画) */
static int app_tap(int x, int y)
{
bbapp_toast("你点了 %d,%d", x, y);
return 1;
}
static const bbapp_app g_app = {
.id = "com.example.hello",
.name = "示例",
.draw = app_draw,
.tap = app_tap,
};
BBAPP_MAIN(&g_app)
关于这两个回调,先记住三件事(第 05 章展开):
draw不能省,没它bbapp_main()直接返回 2。- 每帧都是全量重画,SDK 不保留上一帧,也不会帮你清屏之外的任何东西。
tap的坐标已经是画布坐标(0..711, 0..399),你不用做任何换算。
2.3 编译
抄一份 sdk/example-stopwatch/build.sh 改两行最省事。核心就一条命令:
ZIG=~/Downloads/zig-extract/zig-windows-x86_64-0.13.0/zig.exe
SYS=<repo>/sysroot
"$ZIG" cc -O2 -Wall \
-target aarch64-linux-gnu.2.28 \
-I <repo>/sdk \
-I "$SYS/usr/include" -I "$SYS/usr/include/cairo" \
-L "$SYS/usr/lib/aarch64-linux-gnu" \
app.c <repo>/sdk/bbapp_run.c <repo>/sdk/bbapp_ui.c \
-o hello \
-l:libcairo.so.2 -l:libwayland-client.so.0 -lm
逐段解释:
| 参数 | 为什么 |
|---|---|
-target aarch64-linux-gnu.2.28 |
目标是 glibc 2.28 的 aarch64(设备是 Debian 12,2.36;用 2.28 更保守) |
-I sdk |
找 bbapp.h |
-I $SYS/usr/include -I $SYS/usr/include/cairo |
cairo 的头文件是 #include <cairo/cairo.h> 风格,两个都得给 |
-L $SYS/usr/lib/aarch64-linux-gnu |
链接时找 .so.2 |
bbapp_run.c + bbapp_ui.c 一起编译 |
SDK 是源码分发,没有 libbbapp.a;运行时和控件层直接编进你的程序(只编 bbapp_run.c 会缺符号) |
-l:libcairo.so.2 |
用 -l: 精确指定带版本号的 soname(sysroot 里只有这个名字) |
-lm |
cairo 的圆弧/矩阵会用到数学库 |
产物是一个静态链接了你自己的代码、动态依赖设备上的 cairo/wayland 的可执行文件。设备上这两个库由 Debian 提供,不用你带。
编译成功后检查一下架构,别把 x86 的东西推上去:
file hello # 期望: ELF 64-bit LSB executable, ARM aarch64
2.4 打包
python <repo>/sdk/mkbbapp.py .
输出会列清楚包里有什么,并给出安装命令:
应用: 示例 (com.example.hello) v1.0.0 abi=1
入口: hello
+ app.json
+ hello
共 2 个文件 / 14.2 KB
打包完成: .../com.example.hello-1.0.0.bbapp
14528 B (14.2 KB) sha256=...
包是 zip,结构极简,只收 app.json + entry + assets/** + 清单里 files[] 列的东西。app.c 这种源码永远不会进包(04 有白名单的完整规则)。
2.5 装到设备
开发期用 adb(图形化安装页还没做,见 12):
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:bbui 扫目录时发现入口没有执行位会自己补 0755(src/apps.c:slot_load)。
装完 bbui 会在 0.25 秒内自动多出一个图标——它盯的是 /blackbox/apps 的 mtime,不需要重启。
2.6 跑起来、看到什么
点图标 → 屏幕黑一下 → 应用出现 → 点任意位置出现 toast → 点左上「返回」回桌面。
跑起来后,三条命令就能确认它是不是健康:
# 1) 应用日志(SDK 和 app-run.sh 都往这里写)
adb shell tail -f /blackbox/apps/com.example.hello/app.log
正常的一次启动长这样(时间戳 [...] 是 epoch,前面 [HH:MM:SS] 是脚本加的):
[20:11:03] === app-run 开始: /blackbox/apps/com.example.hello/hello ===
[20:11:03] exec /blackbox/apps/com.example.hello/hello
[1762...] [bbapp] touch /dev/input/event2 'fts_ts_3269' MT 400x712 -> 有匹配屏 score=1000
[1762...] [bbapp] 主屏 712x400(面板 400x712, 输出 'DSI-1' mode 400x712, rot=0)
[1762...] [bbapp] 触摸独占成功 (0..399, 0..711)
[1762...] [bbapp] 启动 com.example.hello (示例) 画布 712x400
四行分别代表:找到触摸设备且匹配到了屏 → 算出了画布尺寸 → 抢到了触摸 → 起来了。
# 2) 确认应用进程活着,且 DJI 的相机界面没抢屏
adb shell "ps -A | grep hello; for u in gui sub_gui dji_camera3; do \
echo \$u=\$(systemctl is-active \$u); done"
# 3) 点屏幕,看日志里有没有 tap
adb shell tail -5 /blackbox/apps/com.example.hello/app.log
# 期望: [bbapp] tap 356,314
没等到 tap 就是没点中,去 10 调试与排错。
2.7 第一个应用常踩的五个坑
| 现象 | 原因 | 处理 | |
|---|---|---|---|
| 图标灰的,点了提示"应用装坏了" | entry 指向的文件不在 / app.json 坏了 |
adb shell ls -l /blackbox/apps/<id>/,看 app.json 里的 entry 名字对不对 |
|
| 图标有,点了黑屏然后回桌面 | 应用启动即崩(最常见:连不上 wayland、段错误) | tail app.log,看 [bbapp] 最后一行 |
|
| 画面是竖的 / 整体转了 90° | 直接用了 wl_output.mode 的尺寸当画布 |
别自己开窗口,用 SDK;或检查是否设了 BBAPP_ROT |
|
| 点哪儿都偏一截 | 拿 342×342 的副屏算了坐标 | BBAPP_OUTPUT / BBAPP_TOUCH 指到后屏,见 07 |
|
| 中文是方块 | 设备上 /blackbox/fonts 没字体 |
重跑部署器;`fc-list \ | grep -i wenquanyi` 应有一条 |
下一步 → 03 应用清单:app.json 每个字段的准确语义和长度上限。