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 章展开):

  1. draw 不能省,没它 bbapp_main() 直接返回 2。
  2. 每帧都是全量重画,SDK 不保留上一帧,也不会帮你清屏之外的任何东西。
  3. 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 每个字段的准确语义和长度上限。

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