Buildroot 应用内置 | 立创开发板技术文档中心

概述

将 Qt 应用以 Buildroot 包的形式内置到 SDK，有以下优势：

一次编译：执行 ./build.sh all 时应用随 rootfs 一起构建，无需手动拷贝
自动集成：二进制自动安装到 target/usr/bin/，打包进 rootfs 镜像
版本管理：应用版本与 SDK 版本绑定，便于追踪和回滚

本章以 tspi-sysmonitor（系统信息监控面板）为例，演示完整的内置流程。该应用使用 Qt5 Widgets + Qt5 Network，每 2 秒刷新一次 CPU 温度、内存使用、系统运行时间和网络 IP 地址。

前置条件：已完成 Qt 交叉编译环境搭建，参见 Buildroot Qt 编译环境。

SDK 中应用包的组织方式

在泰山派 RK3576 SDK 中，Rockchip 自定义应用遵循以下目录约定：

类型	源码位置	.mk 中的 SITE 写法	示例
应用程序	SDK 根目录下 `app/<包名>/`	`$(TOPDIR)/../app/<包名>`	`app/lvgl_demo`、`app/n4`
外部库/服务	SDK 根目录下 `external/<包名>/`	`$(TOPDIR)/../external/<包名>`	`external/rkwifibt-app`

其中 $(TOPDIR) 指向 buildroot/ 目录，$(TOPDIR)/../ 即 SDK 根目录。

为什么不把源码放在 buildroot/package/ 里？

SDK 中所有 Rockchip 本地应用（lvgl_demo、n4、rkpartybox 等）都将源码放在 app/ 目录，与 buildroot 构建系统分离。这样做的好处是：源码独立于 Buildroot 版本管理，升级 Buildroot 时不会丢失应用代码。

创建应用源码

放置源码

bash

cd /home/lckfb/TaishanPi-3-Linux
mkdir -p app/tspi-sysmonitor

将应用源码放入：

/home/lckfb/TaishanPi-3-Linux/
├── app/
│   └── tspi-sysmonitor/          # 应用源码
│       ├── main.cpp
│       ├── sysmonitor.h
│       ├── sysmonitor.cpp
│       └── tspi-sysmonitor.pro   # qmake 项目文件
├── buildroot/
│   └── package/
│       └── rockchip/
│           └── tspi-sysmonitor/  # Buildroot 包定义（仅 Config.in + .mk）
│               ├── Config.in
│               └── tspi-sysmonitor.mk
└── ...

.pro 文件示例

qmake

QT += widgets network
TARGET = tspi-sysmonitor
TEMPLATE = app
SOURCES += main.cpp sysmonitor.cpp
HEADERS += sysmonitor.h
target.path = /usr/bin
INSTALLS += target

target.path = /usr/bin 告诉 qmake 安装目标路径，Buildroot 的 qmake-package 基础设施会自动执行 make install INSTALL_ROOT=$(TARGET_DIR)。

创建 Buildroot 包定义

目录结构

在 buildroot/package/rockchip/ 下为应用创建包定义目录（注意：这里只放构建配置，不放源码）：

bash

mkdir -p buildroot/package/rockchip/tspi-sysmonitor

编写 Config.in

kconfig

config BR2_PACKAGE_TSPI_SYSMONITOR
    bool "tspi-sysmonitor"
    depends on BR2_PACKAGE_QT5
    depends on BR2_PACKAGE_QT5BASE_WIDGETS
    help
      System monitor panel for TaishanPi RK3576.
      Displays CPU temperature, memory usage, uptime and IP address.

depends on BR2_PACKAGE_QT5 确保 Qt5 已启用时才显示此选项。

编写 .mk 文件（qmake 方式）

如果项目使用 qmake（.pro 文件），使用 qmake-package 基础设施：

makefile

################################################################################
#
# tspi-sysmonitor
#
################################################################################

TSPI_SYSMONITOR_VERSION = 1.0.0
TSPI_SYSMONITOR_SITE = $(TOPDIR)/../app/tspi-sysmonitor
TSPI_SYSMONITOR_SITE_METHOD = local

TSPI_SYSMONITOR_DEPENDENCIES = qt5base

TSPI_SYSMONITOR_LICENSE = MIT
TSPI_SYSMONITOR_LICENSE_FILES = LICENSE

$(eval $(qmake-package))

关键字段说明：

字段	说明
`TSPI_SYSMONITOR_SITE`	源码路径，`$(TOPDIR)/../app/` 指向 SDK 根目录下的 `app/`
`TSPI_SYSMONITOR_SITE_METHOD = local`	使用本地源码，不从网络下载
`TSPI_SYSMONITOR_DEPENDENCIES`	声明依赖，Buildroot 会先编译 qt5base
`TSPI_SYSMONITOR_LICENSE`	许可证声明（Buildroot 规范要求）
`$(eval $(qmake-package))`	调用 qmake 构建基础设施，自动处理交叉编译

qmake-package 做了什么？

qmake-package（定义在 buildroot/package/pkg-qmake.mk）会自动：

使用 Buildroot 交叉编译工具链的 qmake 生成 Makefile
执行交叉编译
执行 make install INSTALL_ROOT=$(TARGET_DIR) 安装到目标 rootfs

编写 .mk 文件（cmake 方式）

如果项目使用 CMake（CMakeLists.txt），使用 cmake-package 基础设施：

makefile

################################################################################
#
# tspi-sysmonitor
#
################################################################################

TSPI_SYSMONITOR_VERSION = 1.0.0
TSPI_SYSMONITOR_SITE = $(TOPDIR)/../app/tspi-sysmonitor
TSPI_SYSMONITOR_SITE_METHOD = local

TSPI_SYSMONITOR_DEPENDENCIES = qt5base

TSPI_SYSMONITOR_LICENSE = MIT
TSPI_SYSMONITOR_LICENSE_FILES = LICENSE

TSPI_SYSMONITOR_CONF_OPTS = \
    -DCMAKE_BUILD_TYPE=Release

$(eval $(cmake-package))

两种方式选其一即可。本章后续以 qmake 方式为主。

注册包到 Buildroot

编辑 buildroot/package/rockchip/Config.in，在 if BR2_PACKAGE_ROCKCHIP 块内合适位置添加：

kconfig

source "package/rockchip/tspi-sysmonitor/Config.in"

可以用 grep 找到其他包的位置作为参考：

bash

grep -n "source.*Config.in" buildroot/package/rockchip/Config.in | tail -10

在末尾的 endif 之前添加即可。

在 menuconfig 中启用并编译

启用包

bash

# 进入 SDK 根目录
cd /home/lckfb/TaishanPi-3-Linux

# 交互式选择（推荐）
./build.sh lunch
# 选择 tspi_3m_rk3576_buildroot_defconfig

# 直接打开 menuconfig
./build.sh bconfig

在打开的 menuconfig 界面中导航到：

text

Target packages → Rockchip Platform → tspi-sysmonitor

按空格勾选，保存退出。

单独编译包

bash

# 仅编译 tspi-sysmonitor（传递 make target 给 Buildroot）
./build.sh bmake:tspi-sysmonitor

# 或使用完整构建（编译所有包 + 生成 rootfs）
./build.sh all

编译成功后，二进制会出现在：

buildroot/output/rockchip_rk3576/target/usr/bin/tspi-sysmonitor

重新编译（修改源码后）

bash

# 强制重新编译（清除构建缓存后重新构建）
./build.sh bmake:tspi-sysmonitor-rebuild

关于 Buildroot 的构建缓存

Buildroot 使用 stamp 文件跟踪构建状态。对于 SITE_METHOD = local 的包，修改源码后必须使用 -rebuild 后缀才能触发重新编译，否则 Buildroot 会认为包已经是最新的而跳过。

配置开机自启

编写 init.d 启动脚本

创建脚本文件 S99tspi-sysmonitor：

bash

#!/bin/sh
#
# Start tspi-sysmonitor at boot
#

DAEMON=/usr/bin/tspi-sysmonitor
PIDFILE=/var/run/tspi-sysmonitor.pid

case "$1" in
    start)
        echo "Starting tspi-sysmonitor..."
        export QT_QPA_PLATFORM=eglfs
        export QT_QPA_EGLFS_INTEGRATION=eglfs_kms
        export QT_QPA_EGLFS_KMS_CONFIG=/etc/qt-eglfs-kms.conf
        export QT_QPA_FONTDIR=/usr/share/fonts/dejavu
        export QT_QPA_EGLFS_HIDECURSOR=1
        start-stop-daemon -S -b -m -p $PIDFILE -x $DAEMON
        ;;
    stop)
        echo "Stopping tspi-sysmonitor..."
        start-stop-daemon -K -p $PIDFILE
        ;;
    restart)
        $0 stop
        $0 start
        ;;
    *)
        echo "Usage: $0 {start|stop|restart}"
        exit 1
        ;;
esac

exit 0

S99 前缀中的数字 99 决定启动顺序，数字越大越晚启动，确保在显示服务之后运行。

通过 rootfs overlay 打包进镜像

将脚本放入 Buildroot 的 overlay 目录，构建时会自动合并到 rootfs：

bash

# 创建 overlay 中对应的目录结构
mkdir -p buildroot/board/rockchip/rk3576/fs-overlay/etc/init.d/

# 复制脚本并赋予可执行权限
cp S99tspi-sysmonitor buildroot/board/rockchip/rk3576/fs-overlay/etc/init.d/
chmod +x buildroot/board/rockchip/rk3576/fs-overlay/etc/init.d/S99tspi-sysmonitor

overlay 目录结构：

buildroot/board/rockchip/rk3576/fs-overlay/
├── etc/
│   └── init.d/
│       └── S99tspi-sysmonitor
└── ...

确认 overlay 已注册

SDK 的 defconfig 中已配置 BR2_ROOTFS_OVERLAY="board/rockchip/common/base board/rockchip/rk3576/fs-overlay/"，无需额外操作。可通过以下命令确认：

bash

grep BR2_ROOTFS_OVERLAY buildroot/configs/rockchip_rk3576_defconfig

重新构建 rootfs 后脚本会自动包含在镜像中：

bash

./build.sh all

验证

编译验证

bash

# 确认二进制存在于 target 目录
ls -la buildroot/output/rockchip_rk3576/target/usr/bin/tspi-sysmonitor

# 确认 init 脚本存在
ls -la buildroot/output/rockchip_rk3576/target/etc/init.d/S99tspi-sysmonitor

烧录镜像

编译完成后将新镜像烧录到开发板，参见系统烧录。

板子上确认

烧录启动后，通过串口或 SSH 登录：

bash

# 确认程序已安装
ls /usr/bin/tspi-sysmonitor

# 确认 init 脚本存在且有执行权限
ls -la /etc/init.d/S99tspi-sysmonitor

# 手动启动测试
/etc/init.d/S99tspi-sysmonitor start

# 查看进程是否运行
ps aux | grep tspi-sysmonitor

胖妞手机

Android13系统

kernel4.9 Buildroot系统

kernel6.1 三 Linux 系统

Qt-5.15开发指南

Buildroot 路线

Ubuntu24 路线

​

概述 ​

SDK 中应用包的组织方式 ​

创建应用源码 ​

放置源码 ​

.pro 文件示例 ​

创建 Buildroot 包定义 ​

目录结构 ​

编写 Config.in ​

编写 .mk 文件（qmake 方式） ​

编写 .mk 文件（cmake 方式） ​

注册包到 Buildroot ​

在 menuconfig 中启用并编译 ​

启用包 ​

单独编译包 ​

重新编译（修改源码后） ​

配置开机自启 ​

编写 init.d 启动脚本 ​

通过 rootfs overlay 打包进镜像 ​

验证 ​

编译验证 ​

烧录镜像 ​

板子上确认 ​

概述

SDK 中应用包的组织方式

创建应用源码

放置源码

.pro 文件示例

创建 Buildroot 包定义

目录结构

编写 Config.in

编写 .mk 文件（qmake 方式）

编写 .mk 文件（cmake 方式）

注册包到 Buildroot

在 menuconfig 中启用并编译

启用包

单独编译包

重新编译（修改源码后）

配置开机自启

编写 init.d 启动脚本

通过 rootfs overlay 打包进镜像

验证

编译验证

烧录镜像

板子上确认