在Rockchip RV1126上跑通第一个QT程序：从WSL环境搭建到上机测试的完整避坑记录

第一次在嵌入式设备上点亮QT界面时，那种兴奋感至今难忘。作为从单片机转向Linux嵌入式开发的初学者，RV1126开发板搭配QT的图形化开发让我既期待又忐忑。本文将用真实项目经历，详解如何在WSL环境下为Rockchip RV1126构建QT开发环境，特别针对那些官方文档没有明确说明的"坑点"给出解决方案。

1. 环境准备：WSL与SDK的相爱相杀

选择WSL作为开发环境是个需要勇气的决定。虽然它提供了接近原生Linux的开发体验，但与嵌入式开发的交叉编译需求结合时，总会遇到些意想不到的问题。

1.1 WSL环境配置要点

在Windows 10/11上启用WSL2后，建议选择Ubuntu 20.04 LTS作为发行版。这个版本在软件包兼容性上表现最好，以下是必须安装的基础组件：

sudo apt update && sudo apt install -y build-essential git cmake \
    python3-dev python3-pip device-tree-compiler ncurses-dev \
    flex bison libssl-dev libelf-dev bc rsync

特别注意 ：WSL默认的 /mnt 目录下执行编译会出现权限问题，建议所有操作都在WSL原生文件系统（如 ~/workspace ）中进行。

1.2 SDK选择的血泪教训

RV1126的SDK管理是个大坑。我最初使用的SDK编译后始终无法生成正确的qmake工具，后来发现是SDK版本与开发板硬件修订版不匹配。关键检查点：

检查项	正确表现	错误表现
qmake --version	显示完整QT版本信息	提示找不到命令或版本异常
arm-linux-gnueabihf-gcc -v	显示6.5.0版本	版本号不匹配或报错
file 命令检查工具链	显示ELF 64-bit LSB	显示32-bit或其他架构

提示：完整的SDK编译可能需要6-12小时，建议在 screen 会话中运行避免中断

2. QT交叉编译的两种路径对比

实际测试发现，Buildroot集成编译和独立交叉编译各有优劣。下表对比了两种方案的特点：

特性	Buildroot集成	独立交叉编译
复杂度	低（自动处理依赖）	高（需手动编译组件）
编译速度	快（增量编译）	慢（全量编译）
调试支持	有限	完整（带调试符号）
适合场景	最终产品发布	开发调试阶段

2.1 Buildroot方案实操要点

在SDK的 buildroot/package/rockchip/ 下新建工程目录时， .mk 文件的这几个参数最容易出错：

define TEXTEDITOR_CONFIGURE_CMDS
    cd $(@D); \
    $(TARGET_MAKE_ENV) \
    $(HOST_DIR)/bin/qmake \  # 必须确认这个路径真实存在
    QT_SELECT=qt5 \          # 显式指定QT版本
    QMAKE_CXXFLAGS+="-fPIC"  # 解决某些链接错误
endef

常见错误 qmake: No such file or directory 的排查步骤：

1. 确认 output/[target]/host/bin/ 下是否存在qmake
2. 检查SDK是否完整编译（查看 output/[target]/build/ 日志）
3. 尝试使用绝对路径替代 $(HOST_DIR)

2.2 独立交叉编译的深度定制

当需要特定版本的QT或特殊模块时，独立编译是唯一选择。以下是关键配置参数解析：

./configure -prefix /opt/qt5.9-rv1126 \
    -xplatform linux-arm-gnueabi-g++ \  # 必须与工具链匹配
    -qt-libjpeg -qt-libpng -qt-zlib \   # 图形支持
    -no-opengl -linuxfb \               # RV1126显示配置
    -openssl-linked \                   # 安全连接必备
    -I /opt/openssl-arm/include \       # 自定义OpenSSL路径
    -L /opt/openssl-arm/lib

编译OpenSSL时最易出错的Makefile修改点：

CC=/opt/gcc-linaro-6.5.0/bin/arm-linux-gnueabihf-gcc
AR=/opt/gcc-linaro-6.5.0/bin/arm-linux-gnueabihf-ar $(ARFLAGS)
RANLIB=/opt/gcc-linaro-6.5.0/bin/arm-linux-gnueabihf-ranlib

3. 开发板部署的魔鬼细节

编译成功的程序在开发板上运行，还需要注意这些易忽略的环节。

3.1 文件传输的正确姿势

相比常见的scp方式，我推荐使用 rsync 进行文件同步，它能保持文件权限并支持增量更新：

rsync -avz --progress \
    --exclude='*.o' --exclude='moc_*.cpp' \
    ./app root@192.168.1.100:/userdata

3.2 环境变量设置的玄机

RV1126的显示驱动需要特殊的环境变量配置，以下是经过验证的有效组合：

export QT_QPA_PLATFORM=linuxfb:fb=/dev/fb0
export QT_QPA_FB_DRM=1
export QT_QPA_FB_HIDECURSOR=1
export QT_LOGGING_RULES=qt.qpa.*=true

注意：旋转屏幕需要修改 fbdev 参数而非 rotation ，这是Rockchip驱动层的特殊要求

3.3 权限问题的终极解决方案

开发板上的权限问题可能导致程序静默失败，一个可靠的解决方法是创建 /etc/udev/rules.d/99-qt.rules ：

SUBSYSTEM=="graphics", KERNEL=="fb[0-9]*", MODE="0666"
SUBSYSTEM=="input", KERNEL=="event*", MODE="0666"

4. 典型错误排查指南

在实际开发中，这些错误出现的频率最高，也最让人头疼。

4.1 链接错误：undefined reference to QSslSocket

这个问题通常源于OpenSSL链接配置不当，解决方法：

1. 确认QT编译时使用了 -openssl-linked 选项
2. 检查开发板上是否存在 libssl.so.1.0.0 和 libcrypto.so.1.0.0
3. 在 .pro 文件中显式指定库路径：

LIBS += -L/usr/local/ssl/lib -lssl -lcrypto
INCLUDEPATH += /usr/local/ssl/include

4.2 运行时报错：Could not load the Qt platform plugin "xcb"

在嵌入式环境常见于误用桌面环境的QT插件，解决方案：

export QT_PLUGIN_PATH=/usr/lib/qt/plugins
export QT_DEBUG_PLUGINS=1  # 启用插件调试信息

4.3 界面显示异常：花屏或错位

这往往与帧缓冲区配置有关，可以尝试：

1. 检查 /dev/fb0 设备是否存在
2. 确认内核启动参数中的 video= 设置正确
3. 使用 fbset 工具验证显示模式：

fbset -fb /dev/fb0 -i

5. 性能优化实战技巧

让QT应用在RV1126上流畅运行，还需要这些优化手段。

5.1 渲染加速配置

在 main.cpp 中添加这些设置可提升渲染性能：

QApplication::setAttribute(Qt::AA_UseOpenGLES);
QApplication::setAttribute(Qt::AA_UseSoftwareOpenGL);
QCoreApplication::setAttribute(Qt::AA_EnableHighDpiScaling);

5.2 内存占用优化

通过修改 .pro 文件减少不必要的模块：

QT -= gui widgets  # 按需移除模块
CONFIG += release  # 发布模式
DEFINES += QT_NO_DEBUG  # 禁用调试

5.3 启动速度提升

实测有效的启动加速方案：

1. 使用静态编译（需重新配置QT）
2. 预加载库到内存：

   LD_PRELOAD=/usr/lib/libQt5Core.so.5 ./app
   

3. 禁用不需要的插件：

   export QT_QPA_PLATFORM=linuxfb:noevdev
   

在项目收尾阶段，我发现最稳定的组合是：WSL2 + 官方推荐SDK + QT 5.9.4静态编译。虽然初始配置耗时较长，但后续开发效率显著提升。记得每次环境变更时做好备份，这个习惯帮我节省了至少50小时的重复劳动时间。