保姆级教程：在Ubuntu 22.04上为RK3568开发板交叉编译Qt 5.15.8（含完整配置脚本）

嵌入式开发中，Qt框架因其跨平台特性和丰富的UI组件库而广受欢迎。但对于RK3568这类ARM架构的开发板，直接在资源受限的设备上编译Qt既不现实也不高效。本文将手把手带你完成Ubuntu 22.04环境下Qt 5.15.8的交叉编译全流程，从工具链配置到最终部署，每个步骤都经过实测验证，并提供可直接复用的自动化脚本。

1. 环境准备与工具链配置

1.1 系统基础环境检查

首先确认你的Ubuntu 22.04系统已安装必要的开发工具。打开终端执行以下命令：

bash复制sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential git python3 cmake ninja-build \
    libgl1-mesa-dev libxcb-xinerama0-dev libxkbcommon-dev \
    libxkbcommon-x11-dev libxcb-icccm4-dev libxcb-image0-dev \
    libxcb-keysyms1-dev libxcb-render-util0-dev libxcb-xinput-dev

这些基础依赖包含编译器、调试工具和X11开发库，是后续Qt编译的基础。特别提醒：Ubuntu 22.04默认的gcc版本为11.3.0，经测试完全兼容本教程。

1.2 获取RK3568专用工具链

RK3568采用Arm Cortex-A55架构，需要对应的aarch64工具链。推荐使用Rockchip官方提供的prebuilt工具链：

bash复制mkdir -p ~/rk3568_toolchain && cd ~/rk3568_toolchain
wget https://repo.rock-chips.com/rk3568/toolchain/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu.tar.xz
tar xvf gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu.tar.xz
sudo mv gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu /opt/

将工具链加入系统PATH环境变量：

bash复制echo 'export PATH=/opt/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

验证工具链是否安装成功：

bash复制aarch64-none-linux-gnu-gcc --version

正确输出应显示gcc版本为10.3.1。如果遇到权限问题，可通过sudo chmod -R 755 /opt/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu解决。

2. Qt源码获取与配置

2.1 下载Qt 5.15.8源码

Qt 5.15是LTS版本，兼顾稳定性和新特性支持。建议在用户目录下创建工作空间：

bash复制mkdir ~/qt5-cross-build && cd ~/qt5-cross-build
wget https://download.qt.io/archive/qt/5.15/5.15.8/single/qt-everywhere-opensource-src-5.15.8.tar.xz
tar xvf qt-everywhere-opensource-src-5.15.8.tar.xz

源码解压后约3.2GB空间，确保磁盘有足够容量。对于国内用户，可以考虑使用清华镜像源加速下载：

bash复制wget https://mirrors.tuna.tsinghua.edu.cn/qt/archive/qt/5.15/5.15.8/single/qt-everywhere-opensource-src-5.15.8.tar.xz

2.2 配置编译参数

创建自动配置脚本configure.sh，内容如下：

bash复制#!/bin/bash

BUILD_DIR=$(pwd)/qt-build
INSTALL_DIR=$(pwd)/qt-5.15.8-rk3568
QT_SOURCE=$(pwd)/qt-everywhere-opensource-src-5.15.8

mkdir -p $BUILD_DIR && cd $BUILD_DIR

$QT_SOURCE/configure \
    -prefix $INSTALL_DIR \
    -release \
    -opensource -confirm-license \
    -xplatform linux-aarch64-gnu-g++ \
    -nomake examples \
    -nomake tests \
    -no-opengl \
    -no-icu \
    -no-pch \
    -qt-libjpeg \
    -qt-libpng \
    -qt-zlib \
    -skip qt3d \
    -skip qtwebengine \
    -skip qtdoc \
    -sysroot /opt/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu/aarch64-none-linux-gnu/libc \
    -no-glib \
    -no-cups \
    -no-iconv \
    -no-dbus \
    -linuxfb \
    -v

关键参数说明：

• -xplatform linux-aarch64-gnu-g++：指定目标平台配置
• -sysroot：指向工具链的sysroot目录
• -skip：跳过不需要的模块以加快编译速度
• -no-opengl：RK3568通常不带GPU加速

赋予执行权限并运行配置：

bash复制chmod +x configure.sh
./configure.sh

配置过程约10-15分钟，完成后会显示汇总信息。特别注意检查以下输出项是否匹配：

code复制Target ............ linux-aarch64-gnu-g++
Device ............ no
...
Qt Libraries:
  Qt D-Bus ............... no
  Qt Widgets ............. yes
  Qt GUI ................. yes

3. 编译与安装

3.1 启动编译进程

配置成功后，在build目录直接执行：

bash复制make -j$(nproc)

-j$(nproc)会自动根据CPU核心数启动并行编译。对于8核机器，编译过程约2-3小时。建议在screen或tmux会话中运行，防止网络中断导致失败。

常见问题处理：

• 内存不足：添加swap空间或减少并行数（如-j4）
• 依赖缺失：根据错误提示安装对应开发包
• 文件权限：使用普通用户编译，避免root权限问题

3.2 安装到目标目录

编译完成后执行安装：

bash复制make install

这会将编译好的Qt库和工具安装到qt-5.15.8-rk3568目录，约占用1.8GB空间。安装完成后，建议打包备份：

bash复制tar czvf qt-5.15.8-rk3568.tar.gz qt-5.15.8-rk3568

4. 开发环境配置

4.1 设置环境变量

创建env-setup.sh环境配置脚本：

bash复制#!/bin/bash

export RK3568_SYSROOT=/opt/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu/aarch64-none-linux-gnu/libc
export QT_ROOT=$(pwd)/qt-5.15.8-rk3568
export PATH=$QT_ROOT/bin:$PATH
export TOOLCHAIN_PATH=/opt/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu/bin

export CC=$TOOLCHAIN_PATH/aarch64-none-linux-gnu-gcc
export CXX=$TOOLCHAIN_PATH/aarch64-none-linux-gnu-g++
export AR=$TOOLCHAIN_PATH/aarch64-none-linux-gnu-ar
export LD=$TOOLCHAIN_PATH/aarch64-none-linux-gnu-ld
export STRIP=$TOOLCHAIN_PATH/aarch64-none-linux-gnu-strip
export RANLIB=$TOOLCHAIN_PATH/aarch64-none-linux-gnu-ranlib

echo "RK3568 Qt environment has been set up!"

使用前执行：

bash复制source env-setup.sh

4.2 验证交叉编译环境

创建测试程序test.cpp：

cpp复制#include <QCoreApplication>
#include <QDebug>

int main(int argc, char *argv[])
{
    QCoreApplication a(argc, argv);
    qDebug() << "Hello from RK3568!";
    return a.exec();
}

编写对应的test.pro：

qmake复制QT += core
TARGET = test
CONFIG += console
SOURCES += test.cpp

编译测试：

bash复制qmake && make
file test

正确输出应显示：

code复制test: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-aarch64.so.1, for GNU/Linux 3.7.0, not stripped

5. 部署到RK3568开发板

5.1 准备目标板运行环境

将以下目录打包传输到开发板：

• qt-5.15.8-rk3568/lib → /usr/local/qt5.15/lib
• qt-5.15.8-rk3568/plugins → /usr/local/qt5.15/plugins

在开发板上设置环境变量：

bash复制export QT_ROOT=/usr/local/qt5.15
export LD_LIBRARY_PATH=$QT_ROOT/lib:$LD_LIBRARY_PATH
export QT_QPA_PLATFORM_PLUGIN_PATH=$QT_ROOT/plugins/platforms
export QT_QPA_PLATFORM=linuxfb:fb=/dev/fb0

5.2 部署测试程序

将编译好的test程序拷贝到开发板，添加执行权限后运行：

bash复制chmod +x test
./test

预期输出：

code复制Hello from RK3568!

如果遇到库缺失错误，使用ldd test检查依赖关系，确保所有.so文件都能在LD_LIBRARY_PATH指定的路径中找到。

6. 高级配置与优化

6.1 自定义qmake.conf

针对RK3568的特定优化，可以修改qtbase/mkspecs/linux-aarch64-gnu-g++/qmake.conf：

qmake复制# 添加硬件加速选项
QMAKE_CFLAGS += -march=armv8-a+crc+crypto -mtune=cortex-a55
QMAKE_CXXFLAGS += $$QMAKE_CFLAGS

# 优化级别
QMAKE_CFLAGS_RELEASE += -O3 -pipe
QMAKE_CXXFLAGS_RELEASE += $$QMAKE_CFLAGS_RELEASE

# 链接优化
QMAKE_LFLAGS_RELEASE += -Wl,-O1 -Wl,--hash-style=gnu -Wl,--as-needed

6.2 选择性编译模块

如果需要添加初始跳过的模块（如QtSerialPort），可以单独编译：

bash复制cd ~/qt5-cross-build/qt-everywhere-opensource-src-5.15.8/qtserialport
~/qt5-cross-build/qt-5.15.8-rk3568/bin/qmake
make -j$(nproc)
make install

6.3 创建系统级打包

制作deb包便于分发：

bash复制mkdir -p pkg/DEBIAN pkg/usr/local/qt5.15
cp -r qt-5.15.8-rk3568/* pkg/usr/local/qt5.15/

cat > pkg/DEBIAN/control <<EOF
Package: qt5.15-rk3568
Version: 5.15.8
Architecture: arm64
Maintainer: Your Name <your.email@example.com>
Description: Qt 5.15.8 for RK3568 development board
EOF

dpkg-deb --build pkg qt5.15-rk3568.deb

7. 实际项目应用示例

7.1 交叉编译GUI应用

以简单的按钮应用为例，创建main.cpp：

cpp复制#include <QApplication>
#include <QPushButton>

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    
    QPushButton button("Click Me!");
    button.resize(200, 100);
    button.show();
    
    return app.exec();
}

对应的button.pro：

qmake复制QT += widgets
TARGET = button
SOURCES += main.cpp

编译命令：

bash复制qmake button.pro
make

7.2 部署到开发板

将编译产物和所需资源文件打包：

bash复制mkdir -p button-app/{bin,lib}
cp button button-app/bin/
ldd button-app/bin/button | grep "=> /" | awk '{print $3}' | xargs -I '{}' cp '{}' button-app/lib/

创建启动脚本run.sh：

bash复制#!/bin/sh
export LD_LIBRARY_PATH=$(dirname $0)/../lib:$LD_LIBRARY_PATH
$(dirname $0)/button

最终目录结构：

code复制button-app/
├── bin/
│   ├── button
│   └── run.sh
└── lib/
    ├── libQt5Core.so.5
    ├── libQt5Gui.so.5
    └── libQt5Widgets.so.5

8. 常见问题解决方案

8.1 编译错误处理

问题1：undefined reference to `FT_Init_FreeType'

bash复制sudo apt install libfreetype6-dev
重新执行configure

问题2：GL/gl.h: No such file or directory

bash复制在configure时添加 -no-opengl 参数
或安装Mesa开发包：sudo apt install libgl1-mesa-dev

8.2 运行时报错处理

问题1：无法加载平台插件"xcb"

code复制确保开发板上正确设置了QT_QPA_PLATFORM环境变量
对于无X11的环境使用：export QT_QPA_PLATFORM=linuxfb

问题2：库版本不匹配

code复制使用patchelf修改rpath：
patchelf --set-rpath '$ORIGIN/../lib' your_app

8.3 性能优化建议

• 启用RK3568的NEON指令集：在qmake.conf中添加-mfpu=neon-vfpv4
• 对于UI应用，使用-qt-libjpeg-turbo替代默认jpeg库
• 禁用调试符号：-strip和-no-debug参数
• 使用静态链接减少依赖：-static（注意许可证合规性）

9. 自动化脚本整合

将所有关键步骤整合到build-all.sh：

bash复制#!/bin/bash

set -e

# 1. 安装依赖
sudo apt update && sudo apt install -y build-essential git python3 cmake ninja-build \
    libgl1-mesa-dev libxcb-xinerama0-dev libxkbcommon-dev \
    libxkbcommon-x11-dev libxcb-icccm4-dev libxcb-image0-dev \
    libxcb-keysyms1-dev libxcb-render-util0-dev libxcb-xinput-dev

# 2. 设置工具链
mkdir -p ~/rk3568_toolchain && cd ~/rk3568_toolchain
wget -c https://repo.rock-chips.com/rk3568/toolchain/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu.tar.xz
tar xvf gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu.tar.xz
sudo mv gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu /opt/
echo 'export PATH=/opt/gcc-arm-10.3-2021.07-x86_64-aarch64-none-linux-gnu/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 3. 下载Qt源码
mkdir ~/qt5-cross-build && cd ~/qt5-cross-build
wget -c https://download.qt.io/archive/qt/5.15/5.15.8/single/qt-everywhere-opensource-src-5.15.8.tar.xz
tar xvf qt-everywhere-opensource-src-5.15.8.tar.xz

# 4. 配置编译
cat > configure.sh <<'EOF'
#!/bin/bash
... [内容同前文configure.sh]
EOF

chmod +x configure.sh
./configure.sh

# 5. 编译安装
make -j$(nproc)
make install

# 6. 打包
tar czvf qt-5.15.8-rk3568.tar.gz qt-5.15.8-rk3568

echo "Qt 5.15.8 for RK3568 has been successfully built!"

使用说明：

1. 保存为build-all.sh
2. 添加执行权限：chmod +x build-all.sh
3. 运行：./build-all.sh > build.log 2>&1 &
4. 查看进度：tail -f build.log

10. 进阶开发技巧

10.1 使用QtCreator进行交叉开发

1. 安装QtCreator：

bash复制sudo apt install qtcreator

2. 配置工具链：

   • 进入Tools → Options → Kits
   • 添加自定义编译器：指向aarch64-none-linux-gnu-g++
   • 创建新Kit，选择交叉编译器和Qt版本

3. 设置调试：

   • 安装gdbserver到开发板
   • 配置远程调试连接

10.2 性能分析工具

RK3568上的性能优化工具链：

• perf：系统级性能分析
• gprof：应用性能剖析
• Valgrind：内存检测（需交叉编译）

10.3 容器化编译环境

使用Docker创建可重复的编译环境：

dockerfile复制FROM ubuntu:22.04

RUN apt update && apt install -y build-essential git python3 cmake ninja-build \
    libgl1-mesa-dev libxcb-xinerama0-dev libxkbcommon-dev \
    libxkbcommon-x11-dev libxcb-icccm4-dev libxcb-image0-dev \
    libxcb-keysyms1-dev libxcb-render-util0-dev libxcb-xinput-dev \
    wget tar xz-utils

WORKDIR /root
COPY build-all.sh .
RUN chmod +x build-all.sh

CMD ["./build-all.sh"]

构建和使用：

bash复制docker build -t qt-rk3568-builder .
docker run -it --rm -v $(pwd)/output:/root/qt5-cross-build qt-rk3568-builder

11. 系统集成建议

11.1 与Buildroot集成

1. 在Buildroot配置中启用Qt5：

   code复制BR2_PACKAGE_QT5=y
   BR2_PACKAGE_QT5BASE=y
   BR2_PACKAGE_QT5BASE_LINUXFB=y
   

2. 使用SDK构建：

bash复制make sdk
./output/host/relocate-sdk.sh
source output/host/environment-setup
qmake && make

11.2 Yocto集成示例

创建自定义layer的recipe：

bitbake复制DESCRIPTION = "Qt 5.15 for RK3568"
LICENSE = "LGPL-3.0"

DEPENDS = "tslib"

SRC_URI = "https://download.qt.io/archive/qt/5.15/5.15.8/single/qt-everywhere-opensource-src-5.15.8.tar.xz"

inherit qmake5

EXTRA_QMAKEVARS_PRE += " \
    -no-opengl \
    -linuxfb \
    -no-xcb \
"

11.3 最小化部署方案

仅部署必要库的最小文件列表：

code复制Qt5Core.so.5
Qt5Gui.so.5
Qt5Widgets.so.5
platforms/liblinuxfb.so

使用strip减小体积：

bash复制aarch64-none-linux-gnu-strip --strip-unneeded *.so