Buildroot Application Integration | LC Development Board Tech Document Center

Overview

Integrating a Qt application as a Buildroot package into the SDK offers the following advantages:

Single build: The application is built alongside the rootfs when running ./build.sh all, no manual copying required
Automatic integration: Binaries are automatically installed to target/usr/bin/ and packaged into the rootfs image
Version management: Application version is tied to the SDK version, making tracking and rollback easier

This chapter uses tspi-sysmonitor (a system information monitoring panel) as an example to demonstrate the complete integration process. This application uses Qt5 Widgets + Qt5 Network and refreshes CPU temperature, memory usage, system uptime, and network IP address every 2 seconds.

Prerequisite: Qt cross-compilation environment setup is complete. See Buildroot Qt Build Environment.

Application Package Organization in the SDK

In the LCSC-TaishanPi-3M-RK3576 SDK, Rockchip custom applications follow these directory conventions:

Type	Source location	SITE in .mk	Example
Applications	`app/<package-name>/` under SDK root	`$(TOPDIR)/../app/<package-name>`	`app/lvgl_demo`, `app/n4`
External libraries/services	`external/<package-name>/` under SDK root	`$(TOPDIR)/../external/<package-name>`	`external/rkwifibt-app`

Here $(TOPDIR) points to the buildroot/ directory, and $(TOPDIR)/../ is the SDK root directory.

Why not put source code inside buildroot/package/?

All Rockchip local applications in the SDK (lvgl_demo, n4, rkpartybox, etc.) place their source code in the app/ directory, separated from the Buildroot build system. The benefit is that source code is managed independently of the Buildroot version — upgrading Buildroot will not lose application code.

Creating Application Source Code

Placing Source Code

Create the application directory under the SDK root:

bash

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

Place the application source code inside:

/home/lckfb/TaishanPi-3-Linux/
├── app/
│   └── tspi-sysmonitor/          # Application source code
│       ├── main.cpp
│       ├── sysmonitor.h
│       ├── sysmonitor.cpp
│       └── tspi-sysmonitor.pro   # qmake project file
├── buildroot/
│   └── package/
│       └── rockchip/
│           └── tspi-sysmonitor/  # Buildroot package definition (Config.in + .mk only)
│               ├── Config.in
│               └── tspi-sysmonitor.mk
└── ...

.pro File Example

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 tells qmake the installation target path. Buildroot's qmake-package infrastructure will automatically execute make install INSTALL_ROOT=$(TARGET_DIR).

Creating the Buildroot Package Definition

Directory Structure

Create a package definition directory under buildroot/package/rockchip/ for the application (note: only build configuration goes here, not source code):

bash

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

Writing 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 ensures this option is only visible when Qt5 is enabled.

Writing the .mk File (qmake Method)

If the project uses qmake (.pro file), use the qmake-package infrastructure:

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))

Key field descriptions:

Field	Description
`TSPI_SYSMONITOR_SITE`	Source path; `$(TOPDIR)/../app/` points to the `app/` directory under the SDK root
`TSPI_SYSMONITOR_SITE_METHOD = local`	Use local source code, do not download from the network
`TSPI_SYSMONITOR_DEPENDENCIES`	Declare dependencies; Buildroot will compile qt5base first
`TSPI_SYSMONITOR_LICENSE`	License declaration (required by Buildroot conventions)
`$(eval $(qmake-package))`	Invoke the qmake build infrastructure, which automatically handles cross-compilation

What does qmake-package do?

qmake-package (defined in buildroot/package/pkg-qmake.mk) automatically:

Uses the Buildroot cross-compilation toolchain's qmake to generate a Makefile
Performs cross-compilation
Executes make install INSTALL_ROOT=$(TARGET_DIR) to install to the target rootfs

Writing the .mk File (CMake Method)

If the project uses CMake (CMakeLists.txt), use the cmake-package infrastructure:

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))

Choose one of the two methods. The rest of this chapter uses the qmake method.

Registering the Package in Buildroot

Edit buildroot/package/rockchip/Config.in and add the following at an appropriate location within the if BR2_PACKAGE_ROCKCHIP block:

kconfig

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

You can use grep to find the location of other packages as a reference:

bash

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

Add it before the final endif.

Enabling and Building in menuconfig

Enabling the Package

bash

# Enter the SDK root directory
cd /home/lckfb/TaishanPi-3-Linux

# Interactive selection (recommended)
./build.sh lunch
# Select tspi_3m_rk3576_buildroot_defconfig

# Open menuconfig directly
./build.sh bconfig

In the opened menuconfig interface, navigate to:

text

Target packages → Rockchip Platform → tspi-sysmonitor

Press space to select it, then save and exit.

Building the Package Individually

bash

# Build only tspi-sysmonitor (pass make target to Buildroot)
./build.sh bmake:tspi-sysmonitor

# Or use a full build (compile all packages + generate rootfs)
./build.sh all

After successful compilation, the binary will appear at:

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

Rebuilding (After Source Code Changes)

bash

# Force rebuild (clear build cache and rebuild)
./build.sh bmake:tspi-sysmonitor-rebuild

About Buildroot's Build Cache

Buildroot uses stamp files to track build state. For packages with SITE_METHOD = local, you must use the -rebuild suffix after modifying source code to trigger recompilation; otherwise Buildroot will consider the package up-to-date and skip it.

Configuring Auto-Start at Boot

Writing the init.d Startup Script

Create the script file 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

The number 99 in the S99 prefix determines the startup order — higher numbers start later, ensuring it runs after display services.

Packaging into the Image via rootfs Overlay

Place the script in Buildroot's overlay directory, which will be automatically merged into the rootfs during build:

bash

# Create the corresponding directory structure in the overlay
mkdir -p buildroot/board/rockchip/rk3576/fs-overlay/etc/init.d/

# Copy the script and grant execute permission
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 directory structure:

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

Confirm the Overlay is Registered

The SDK's defconfig already has BR2_ROOTFS_OVERLAY="board/rockchip/common/base board/rockchip/rk3576/fs-overlay/" configured — no additional action is needed. You can verify with:

bash

grep BR2_ROOTFS_OVERLAY buildroot/configs/rockchip_rk3576_defconfig

After rebuilding the rootfs, the script will be automatically included in the image:

bash

./build.sh all

Verification

Build Verification

bash

# Confirm the binary exists in the target directory
ls -la buildroot/output/rockchip_rk3576/target/usr/bin/tspi-sysmonitor

# Confirm the init script exists
ls -la buildroot/output/rockchip_rk3576/target/etc/init.d/S99tspi-sysmonitor

Flashing the Image

After compilation, flash the new image to the development board. See System Flashing.

Confirming on the Board

After flashing and booting, log in via serial console or SSH:

bash

# Confirm the program is installed
ls /usr/bin/tspi-sysmonitor

# Confirm the init script exists and has execute permission
ls -la /etc/init.d/S99tspi-sysmonitor

# Manual start test
/etc/init.d/S99tspi-sysmonitor start

# Check if the process is running
ps aux | grep tspi-sysmonitor

Pangniu Phone

Buildroot Route

Ubuntu24 Route

​

Overview ​

Application Package Organization in the SDK ​

Creating Application Source Code ​

Placing Source Code ​

.pro File Example ​

Creating the Buildroot Package Definition ​

Directory Structure ​

Writing Config.in ​

Writing the .mk File (qmake Method) ​

Writing the .mk File (CMake Method) ​

Registering the Package in Buildroot ​

Enabling and Building in menuconfig ​

Enabling the Package ​

Building the Package Individually ​

Rebuilding (After Source Code Changes) ​

Configuring Auto-Start at Boot ​

Writing the init.d Startup Script ​

Packaging into the Image via rootfs Overlay ​

Verification ​

Build Verification ​

Flashing the Image ​

Confirming on the Board ​

Overview

Application Package Organization in the SDK

Creating Application Source Code

Placing Source Code

.pro File Example

Creating the Buildroot Package Definition

Directory Structure

Writing Config.in

Writing the .mk File (qmake Method)

Writing the .mk File (CMake Method)

Registering the Package in Buildroot

Enabling and Building in menuconfig

Enabling the Package

Building the Package Individually

Rebuilding (After Source Code Changes)

Configuring Auto-Start at Boot

Writing the init.d Startup Script

Packaging into the Image via rootfs Overlay

Verification

Build Verification

Flashing the Image

Confirming on the Board