1. 项目概述从零到一的嵌入式图形界面初体验在嵌入式开发的世界里第一次让图形界面在开发板上亮起来那种感觉就像亲手点亮了一盏灯。我最近在一块基于T113芯片的开发板上完成了第一个Qt程序的移植与运行。这不仅仅是让一个窗口弹出来那么简单它意味着你打通了从主机交叉编译、到库文件部署、再到目标板环境配置的完整链路。对于刚接触嵌入式Linux图形开发的朋友来说这第一步往往充满了困惑为什么主机上编译好的程序放到板子上就跑不起来那些动态库依赖到底该怎么处理Qt的编译选项又该如何配置才能适配这块板子今天我就以这次实战为例把整个流程掰开揉碎把踩过的坑和总结的技巧都分享出来。无论你手头是T113、RK3588、F1C100s还是其他ARM架构的开发板这套思路都是相通的。我们的目标很明确在开发板上成功运行一个最简单的“Hello Qt”窗口程序并理解其背后的每一个环节。2. 开发环境搭建与工具链选择工欲善其事必先利其器。在嵌入式开发中“环境”二字的分量极重它直接决定了后续所有步骤的顺畅程度。2.1 交叉编译工具链的获取与验证交叉编译工具链是连接x86主机和ARM开发板的桥梁。你的开发板供应商通常会提供适配其芯片和内核的专用工具链。以我使用的T113开发板为例厂商提供了一个名为arm-linux-gnueabihf-gcc的工具链。第一步不是急着安装而是验证其有效性。很多新手会直接从网上下载一个通用工具链结果编译出的程序无法在板子上运行问题就出在这里。你应该从开发板配套的SDK或资料包中寻找。拿到工具链压缩包后解压并设置环境变量# 假设解压到 /opt/toolchain/ export PATH/opt/toolchain/gcc-linaro-arm-linux-gnueabihf-4.9-2014.09_linux/bin:$PATH export CROSS_COMPILEarm-linux-gnueabihf- export ARCHarm设置完后立即在终端执行arm-linux-gnueabihf-gcc -v。这个命令会输出工具链的版本信息和内置的库路径。关键点来了请务必核对输出的Target:字段例如arm-linux-gnueabihf这需要与你开发板上uname -m输出的架构信息以及板子文件系统的库类型是gnueabi还是gnueabihf后者支持硬件浮点相匹配。不匹配是导致“Exec format error”错误的常见原因。2.2 Qt源码的获取与交叉编译配置Qt官方提供了丰富的版本对于嵌入式开发我们通常选择Qt for Embedded Linux。我选择的是Qt 5.15.2 LTS版本这是一个长期支持版社区资源丰富稳定性好。不要盲目追求最新版新版本可能对编译环境或硬件有更高要求。下载源码后配置是关键中的关键。Qt的配置通过configure脚本完成参数繁多但嵌入式开发的核心参数就那几个./configure \ -prefix /opt/qt-5.15.2-arm \ # 指定安装目录 -opensource \ # 使用开源协议 -confirm-license \ -xplatform linux-arm-gnueabi-g \ # 指定交叉编译的mkspec # 注意这里的 linux-arm-gnueabi-g 需要与你工具链的实际mkspec对应。 # 通常需要在qtbase/mkspecs目录下找到或创建对应的mkspec文件。 -sysroot /opt/sysroot \ # 指定目标板根文件系统镜像用于链接头文件和库 -no-opengl \ -qt-libjpeg \ -qt-libpng \ -qt-zlib \ -no-cups \ -no-glib \ -no-dbus \ -no-xcb \ -no-iconv \ -nomake examples \ -nomake tests \ -skip qtdoc \ -release \ # 发布模式优化体积和性能 -optimized-qmake \ -pch \这里有几个极易出错的实操心得-xplatform 参数这是最大的坑。Qt源码中的qtbase/mkspecs目录下存放着各种平台的编译规范。你需要检查是否存在与你工具链匹配的目录如linux-arm-gnueabi-g。如果没有最简单的办法是复制一个最接近的如linux-arm-gnueabihf-g并修改其中的qmake.conf文件将其中的编译器路径改为你的arm-linux-gnueabihf-g。-sysroot 参数强烈建议使用。它指向一个包含目标板根文件系统rootfs的目录。这样配置时Qt就会从这个目录下寻找usr/includeusr/lib等路径下的依赖库如zlib, libpng, libjpeg等确保编译出的Qt库与目标板环境完全兼容。你可以从开发板SDK中提取或使用构建好的根文件系统。功能裁剪嵌入式设备资源宝贵务必通过-no-参数禁用不需要的功能如OpenGL、DBus、X11等这能显著减小最终库文件的大小。配置成功后执行make -j$(nproc)进行编译make install后Qt的交叉编译版本就会安装到-prefix指定的目录中。2.3 主机开发环境配置在主机上我使用Qt Creator作为IDE。配置的关键在于添加我们刚刚编译好的Qt交叉编译版本。打开Qt Creator进入工具-选项-Kits。在“Qt版本”页手动添加/opt/qt-5.15.2-arm/bin/qmake。在“编译器”页添加C和C的交叉编译器路径指向你的arm-linux-gnueabihf-gcc和arm-linux-gnueabihf-g。在“构建套件(Kit)”页新建一个套件名称如“ARM Qt5.15.2”设备类型选择“通用Linux设备”编译器选择刚才添加的交叉编译器Qt版本选择刚才添加的Qt 5.15.2 (ARM)调试器可以选择arm-linux-gnueabihf-gdb如果已安装。注意很多教程会教你用scp或ftp手动传输可执行文件但Qt Creator的“设备”功能可以配置自动部署和运行。虽然对于真实硬件配置稍复杂但一旦配好开发效率会大幅提升。初期为了简化我们可以先采用手动传输的方式。3. 第一个Qt程序从创建到交叉编译环境就绪现在开始创造我们的第一个程序。这个程序越简单越好目标就是验证整个工具链和库是否工作正常。3.1 创建最简单的Qt Widgets项目在Qt Creator中使用我们刚刚配置好的“ARM Qt5.15.2”套件创建一个新的“Qt Widgets Application”项目。项目名称就叫HelloEmbeddedQt。在自动生成的main.cpp和mainwindow.ui基础上我们只做最微小的改动以确认程序确实运行在开发板上。例如在MainWindow的构造函数中设置窗口标题MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) , ui(new Ui::MainWindow) { ui-setupUi(this); this-setWindowTitle(Hello from ARM Board - T113); // 可以添加一个Label显示一些系统信息 QLabel *infoLabel new QLabel(this); infoLabel-setText(Qt 5.15.2 on Embedded Linux); infoLabel-setAlignment(Qt::AlignCenter); setCentralWidget(infoLabel); }3.2 关键项目文件(.pro)的交叉编译配置项目根目录下的.pro文件是指定构建规则的核心。为了让项目使用交叉编译我们需要在其中添加一些关键指令。# HelloEmbeddedQt.pro QT core gui greaterThan(QT_MAJOR_VERSION, 4): QT widgets CONFIG c11 # 指定目标平台为嵌入式Linux不使用X11 DEFINES QT_NO_FOREIGN_WINDOW DEFINES QT_QPA_DEFAULT_PLATFORMeglfs # 使用EGLFS平台插件适用于无X11的嵌入式环境 # 指定交叉编译器和sysroot QMAKE_CC $${CROSS_COMPILE}gcc QMAKE_CXX $${CROSS_COMPILE}g QMAKE_LINK $${CROSS_COMPILE}g # 这里假设你在环境变量中设置了 CROSS_COMPILEarm-linux-gnueabihf- # 也可以直接写死路径但不够灵活 # QMAKE_CC /opt/toolchain/bin/arm-linux-gnueabihf-gcc # 链接器标志指定动态链接器路径和sysroot QMAKE_LFLAGS -Wl,-rpath-link,/opt/sysroot/usr/lib QMAKE_LFLAGS --sysroot/opt/sysroot # 指定我们交叉编译好的Qt库的路径 QT_INSTALL_PREFIX /opt/qt-5.15.2-arm QT_INSTALL_LIBS $${QT_INSTALL_PREFIX}/lib # 告诉qmake去哪里找头文件和库 INCLUDEPATH $${QT_INSTALL_PREFIX}/include LIBS -L$${QT_INSTALL_PREFIX}/lib # 你可以注释掉下面这行以生成带调试信息的可执行文件方便后续排查问题 # CONFIG debug # 发布版本优化 CONFIG release配置完成后在Qt Creator中选择ARM套件直接点击“构建”即可。构建成功后在项目的构建目录如build-HelloEmbeddedQt-ARM_Qt5_15_2-Debug/下你会找到生成的可执行文件HelloEmbeddedQt。重要提示此时用file命令查看这个文件file HelloEmbeddedQt。输出应显示为ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked ...。这确认了它是一个ARM架构的可执行文件。如果显示是x86_64说明你的套件配置有误编译成了主机程序。4. 部署到开发板库依赖与运行环境将ARM版本的可执行文件拷贝到开发板使用scp、U盘或SD卡然后通过串口或ssh登录板子执行./HelloEmbeddedQt大概率会失败。最常见的错误是“找不到动态链接库”或“error while loading shared libraries”。4.1 解决动态库依赖问题我们的程序动态链接了Qt的核心库如libQt5Core.so.5, libQt5Gui.so.5, libQt5Widgets.so.5。这些库必须存在于开发板的文件系统中且路径能被动态链接器找到。方法一手动拷贝适用于简单测试这是最直接的方法。在主机上进入Qt的安装目录/opt/qt-5.15.2-arm/lib找到程序依赖的所有Qt库。可以使用arm-linux-gnueabihf-readelf -d HelloEmbeddedQt | grep NEEDED查看具体依赖了哪些库。然后将这些.so文件注意包括符号链接拷贝到开发板的/usr/lib或/lib目录下。但这种方法容易遗漏且污染了板子的系统目录。方法二使用脚本打包依赖推荐编写一个简单的部署脚本deploy.sh使用ldd命令需交叉编译版的ldd或使用$CROSS_COMPILE-readelf解析递归查找所有依赖库并拷贝到一个单独的目录如target-rootfs中保持其相对路径结构。#!/bin/bash # deploy.sh EXECUTABLEHelloEmbeddedQt TARGET_DIR./target-rootfs LIB_DIR/opt/qt-5.15.2-arm/lib # Qt库路径 SYSROOT/opt/sysroot # 系统库路径 mkdir -p $TARGET_DIR cp $EXECUTABLE $TARGET_DIR/ # 一个查找依赖库的简化函数实际应用需要更健壮的脚本处理循环依赖和绝对路径 function copy_deps() { local bin$1 $CROSS_COMPILE-readelf -d $bin | grep NEEDED | awk -F[][] {print $2} | while read lib do # 先在Qt目录找再在sysroot找 if [ -f $LIB_DIR/$lib ]; then cp --parents -n $LIB_DIR/$lib $TARGET_DIR/ copy_deps $LIB_DIR/$lib elif [ -f $SYSROOT/usr/lib/$lib ]; then cp --parents -n $SYSROOT/usr/lib/$lib $TARGET_DIR/ copy_deps $SYSROOT/usr/lib/$lib fi done } copy_deps $EXECUTABLE执行脚本后target-rootfs目录里就包含了可执行文件和它所有的依赖库。将这个目录整个拷贝到开发板例如放到/home/root/myapp。4.2 配置运行环境变量在开发板上运行前需要告诉系统去哪里找我们放在非标准路径下的库。有两种方式设置 LD_LIBRARY_PATH临时export LD_LIBRARY_PATH/home/root/myapp/lib:$LD_LIBRARY_PATH cd /home/root/myapp ./HelloEmbeddedQt这种方式只对当前终端会话有效。修改 Qt 平台插件环境关键步骤 对于嵌入式环境Qt需要知道使用哪个“平台插件”来渲染界面。我们编译时指定了eglfsEmbedded GL Full Screen。运行时需要通过环境变量QT_QPA_PLATFORM来指定。export QT_QPA_PLATFORMeglfs export QT_QPA_EGLFS_INTEGRATIONnone # 对于简单显示可以先尝试这个 # 如果你的板子有特定的触摸屏或显示设备可能需要更多参数 # export QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS/dev/input/event1 # export QT_QPA_EGLFS_PHYSICAL_WIDTH154 # export QT_QPA_EGLFS_PHYSICAL_HEIGHT86 export LD_LIBRARY_PATH/home/root/myapp/lib:$LD_LIBRARY_PATH ./HelloEmbeddedQt将上述环境变量设置和启动命令写成一个run.sh脚本放在应用目录以后每次执行./run.sh即可。5. 常见问题排查与实战技巧实录即便按照步骤操作第一次运行也难免遇到问题。下面是我在多次实践中总结的典型问题及排查思路。5.1 问题一执行程序时报 “No such file or directory”现象./HelloEmbeddedQt后提示此错误但文件明明存在。排查检查文件权限chmod x HelloEmbeddedQt。使用file HelloEmbeddedQt确认它是ARM架构的可执行文件而不是x86_64。最可能的原因动态链接器不对。使用readelf -l HelloEmbeddedQt | grep INTERP查看程序需要的解释器如/lib/ld-linux-armhf.so.3。然后到开发板上检查这个路径是否存在该文件。如果不存在说明你的根文件系统缺少关键的运行时库需要从工具链的sysroot中拷贝ld-linux系列文件到板子的/lib目录下。5.2 问题二 “error while loading shared libraries: libQt5Core.so.5: cannot open shared object file”现象这是最经典的库找不到错误。排查确认LD_LIBRARY_PATH是否已正确设置并且路径中确实包含libQt5Core.so.5。在开发板上使用find / -name libQt5Core.so.5 2/dev/null查找该库是否存在。检查库的架构是否匹配。在主机上用file命令检查你拷贝的.so文件也应该是ARM架构。有时不小心会混入x86的库。检查库的符号链接。Qt的库通常有一系列符号链接如libQt5Core.so - libQt5Core.so.5 - libQt5Core.so.5.15.2。确保完整的链接链都被拷贝到了开发板。5.3 问题三程序运行后无显示或黑屏然后退出现象程序启动后屏幕没有变化或者闪一下黑屏就退出了终端可能有关于平台插件的错误信息。排查检查平台插件首先确认QT_QPA_PLATFORMeglfs环境变量已设置。可以尝试换成linuxfb帧缓冲试试export QT_QPA_PLATFORMlinuxfb。如果linuxfb能显示但eglfs不能可能是你的板子或Qt编译时没有包含或正确配置OpenGL ES支持。查看详细日志设置QT_DEBUG_PLUGINS1环境变量再运行程序会输出详细的插件加载信息有助于定位问题。检查显示设备权限确保运行程序的用户通常是root有权限访问/dev/fb0帧缓冲设备或/dev/dri/card0DRM设备。可以尝试sudo chmod 666 /dev/fb0仅用于测试注意安全。检查Qt编译配置回顾你是否在编译Qt时禁用了必要的图形后端如-no-opengl或-no-eglfs。对于现代GPU通常需要开启-opengl es2。5.4 问题四触摸屏或鼠标键盘无响应现象界面显示正常但无法通过触摸或USB输入设备交互。排查检查输入设备节点在开发板上执行ls /dev/input/查看是否有eventX设备。连接鼠标或触摸屏时观察是否有新的event设备产生。配置Qt环境变量对于触摸屏可能需要指定设备节点export QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS/dev/input/event1:rotate0。对于鼠标键盘Qt的evdev插件通常能自动识别。可以设置QT_QPA_GENERIC_PLUGINSevdevmouse,evdevkeyboard来强制指定。编译时确保输入支持确认编译Qt时没有使用-no-evdev参数禁用了输入设备支持。5.5 实战技巧精简程序体积嵌入式设备存储空间有限最终发布时需要尽量减小程序体积。使用 release 模式编译在.pro文件中确保有CONFIG release这会进行优化并去掉调试符号。静态编译这是最有效的减容方法。在编译Qt源码时configure加上-static参数。这样编译出的Qt库是静态的最终的可执行文件会包含所有需要的Qt代码体积会变大但不再依赖动态库部署极其简单。注意静态编译可能需要处理一些额外的许可和依赖问题。使用 strip 工具对动态编译的可执行文件和库使用交叉编译工具链中的arm-linux-gnueabihf-strip命令去掉调试符号能显著减小文件大小。strip HelloEmbeddedQt。Qt 编译器裁剪Qt提供了一个名为qt.conf的配置文件可以控制运行时加载哪些插件。你可以只打包程序用到的插件如图像格式插件、平台插件而不是全部。当你在终端看到HelloEmbeddedQt进程启动屏幕上如期出现那个写着“Hello from ARM Board”的窗口时之前所有的繁琐配置和问题排查都值了。这个窗口不仅仅是一个程序界面它更像是一个信号证明你的交叉编译工具链、系统库、Qt库以及运行时环境形成了一个完美的闭环。对于更复杂的项目后续无非是在这个坚实的基础上添加业务逻辑、优化UI、处理硬件交互。掌握了从编译到部署的完整流程你就拥有了在嵌入式世界绘制图形界面的画笔。
嵌入式Linux Qt交叉编译实战：从环境搭建到开发板部署全流程
发布时间：2026/7/29 4:56:29
1. 项目概述从零到一的嵌入式图形界面初体验在嵌入式开发的世界里第一次让图形界面在开发板上亮起来那种感觉就像亲手点亮了一盏灯。我最近在一块基于T113芯片的开发板上完成了第一个Qt程序的移植与运行。这不仅仅是让一个窗口弹出来那么简单它意味着你打通了从主机交叉编译、到库文件部署、再到目标板环境配置的完整链路。对于刚接触嵌入式Linux图形开发的朋友来说这第一步往往充满了困惑为什么主机上编译好的程序放到板子上就跑不起来那些动态库依赖到底该怎么处理Qt的编译选项又该如何配置才能适配这块板子今天我就以这次实战为例把整个流程掰开揉碎把踩过的坑和总结的技巧都分享出来。无论你手头是T113、RK3588、F1C100s还是其他ARM架构的开发板这套思路都是相通的。我们的目标很明确在开发板上成功运行一个最简单的“Hello Qt”窗口程序并理解其背后的每一个环节。2. 开发环境搭建与工具链选择工欲善其事必先利其器。在嵌入式开发中“环境”二字的分量极重它直接决定了后续所有步骤的顺畅程度。2.1 交叉编译工具链的获取与验证交叉编译工具链是连接x86主机和ARM开发板的桥梁。你的开发板供应商通常会提供适配其芯片和内核的专用工具链。以我使用的T113开发板为例厂商提供了一个名为arm-linux-gnueabihf-gcc的工具链。第一步不是急着安装而是验证其有效性。很多新手会直接从网上下载一个通用工具链结果编译出的程序无法在板子上运行问题就出在这里。你应该从开发板配套的SDK或资料包中寻找。拿到工具链压缩包后解压并设置环境变量# 假设解压到 /opt/toolchain/ export PATH/opt/toolchain/gcc-linaro-arm-linux-gnueabihf-4.9-2014.09_linux/bin:$PATH export CROSS_COMPILEarm-linux-gnueabihf- export ARCHarm设置完后立即在终端执行arm-linux-gnueabihf-gcc -v。这个命令会输出工具链的版本信息和内置的库路径。关键点来了请务必核对输出的Target:字段例如arm-linux-gnueabihf这需要与你开发板上uname -m输出的架构信息以及板子文件系统的库类型是gnueabi还是gnueabihf后者支持硬件浮点相匹配。不匹配是导致“Exec format error”错误的常见原因。2.2 Qt源码的获取与交叉编译配置Qt官方提供了丰富的版本对于嵌入式开发我们通常选择Qt for Embedded Linux。我选择的是Qt 5.15.2 LTS版本这是一个长期支持版社区资源丰富稳定性好。不要盲目追求最新版新版本可能对编译环境或硬件有更高要求。下载源码后配置是关键中的关键。Qt的配置通过configure脚本完成参数繁多但嵌入式开发的核心参数就那几个./configure \ -prefix /opt/qt-5.15.2-arm \ # 指定安装目录 -opensource \ # 使用开源协议 -confirm-license \ -xplatform linux-arm-gnueabi-g \ # 指定交叉编译的mkspec # 注意这里的 linux-arm-gnueabi-g 需要与你工具链的实际mkspec对应。 # 通常需要在qtbase/mkspecs目录下找到或创建对应的mkspec文件。 -sysroot /opt/sysroot \ # 指定目标板根文件系统镜像用于链接头文件和库 -no-opengl \ -qt-libjpeg \ -qt-libpng \ -qt-zlib \ -no-cups \ -no-glib \ -no-dbus \ -no-xcb \ -no-iconv \ -nomake examples \ -nomake tests \ -skip qtdoc \ -release \ # 发布模式优化体积和性能 -optimized-qmake \ -pch \这里有几个极易出错的实操心得-xplatform 参数这是最大的坑。Qt源码中的qtbase/mkspecs目录下存放着各种平台的编译规范。你需要检查是否存在与你工具链匹配的目录如linux-arm-gnueabi-g。如果没有最简单的办法是复制一个最接近的如linux-arm-gnueabihf-g并修改其中的qmake.conf文件将其中的编译器路径改为你的arm-linux-gnueabihf-g。-sysroot 参数强烈建议使用。它指向一个包含目标板根文件系统rootfs的目录。这样配置时Qt就会从这个目录下寻找usr/includeusr/lib等路径下的依赖库如zlib, libpng, libjpeg等确保编译出的Qt库与目标板环境完全兼容。你可以从开发板SDK中提取或使用构建好的根文件系统。功能裁剪嵌入式设备资源宝贵务必通过-no-参数禁用不需要的功能如OpenGL、DBus、X11等这能显著减小最终库文件的大小。配置成功后执行make -j$(nproc)进行编译make install后Qt的交叉编译版本就会安装到-prefix指定的目录中。2.3 主机开发环境配置在主机上我使用Qt Creator作为IDE。配置的关键在于添加我们刚刚编译好的Qt交叉编译版本。打开Qt Creator进入工具-选项-Kits。在“Qt版本”页手动添加/opt/qt-5.15.2-arm/bin/qmake。在“编译器”页添加C和C的交叉编译器路径指向你的arm-linux-gnueabihf-gcc和arm-linux-gnueabihf-g。在“构建套件(Kit)”页新建一个套件名称如“ARM Qt5.15.2”设备类型选择“通用Linux设备”编译器选择刚才添加的交叉编译器Qt版本选择刚才添加的Qt 5.15.2 (ARM)调试器可以选择arm-linux-gnueabihf-gdb如果已安装。注意很多教程会教你用scp或ftp手动传输可执行文件但Qt Creator的“设备”功能可以配置自动部署和运行。虽然对于真实硬件配置稍复杂但一旦配好开发效率会大幅提升。初期为了简化我们可以先采用手动传输的方式。3. 第一个Qt程序从创建到交叉编译环境就绪现在开始创造我们的第一个程序。这个程序越简单越好目标就是验证整个工具链和库是否工作正常。3.1 创建最简单的Qt Widgets项目在Qt Creator中使用我们刚刚配置好的“ARM Qt5.15.2”套件创建一个新的“Qt Widgets Application”项目。项目名称就叫HelloEmbeddedQt。在自动生成的main.cpp和mainwindow.ui基础上我们只做最微小的改动以确认程序确实运行在开发板上。例如在MainWindow的构造函数中设置窗口标题MainWindow::MainWindow(QWidget *parent) : QMainWindow(parent) , ui(new Ui::MainWindow) { ui-setupUi(this); this-setWindowTitle(Hello from ARM Board - T113); // 可以添加一个Label显示一些系统信息 QLabel *infoLabel new QLabel(this); infoLabel-setText(Qt 5.15.2 on Embedded Linux); infoLabel-setAlignment(Qt::AlignCenter); setCentralWidget(infoLabel); }3.2 关键项目文件(.pro)的交叉编译配置项目根目录下的.pro文件是指定构建规则的核心。为了让项目使用交叉编译我们需要在其中添加一些关键指令。# HelloEmbeddedQt.pro QT core gui greaterThan(QT_MAJOR_VERSION, 4): QT widgets CONFIG c11 # 指定目标平台为嵌入式Linux不使用X11 DEFINES QT_NO_FOREIGN_WINDOW DEFINES QT_QPA_DEFAULT_PLATFORMeglfs # 使用EGLFS平台插件适用于无X11的嵌入式环境 # 指定交叉编译器和sysroot QMAKE_CC $${CROSS_COMPILE}gcc QMAKE_CXX $${CROSS_COMPILE}g QMAKE_LINK $${CROSS_COMPILE}g # 这里假设你在环境变量中设置了 CROSS_COMPILEarm-linux-gnueabihf- # 也可以直接写死路径但不够灵活 # QMAKE_CC /opt/toolchain/bin/arm-linux-gnueabihf-gcc # 链接器标志指定动态链接器路径和sysroot QMAKE_LFLAGS -Wl,-rpath-link,/opt/sysroot/usr/lib QMAKE_LFLAGS --sysroot/opt/sysroot # 指定我们交叉编译好的Qt库的路径 QT_INSTALL_PREFIX /opt/qt-5.15.2-arm QT_INSTALL_LIBS $${QT_INSTALL_PREFIX}/lib # 告诉qmake去哪里找头文件和库 INCLUDEPATH $${QT_INSTALL_PREFIX}/include LIBS -L$${QT_INSTALL_PREFIX}/lib # 你可以注释掉下面这行以生成带调试信息的可执行文件方便后续排查问题 # CONFIG debug # 发布版本优化 CONFIG release配置完成后在Qt Creator中选择ARM套件直接点击“构建”即可。构建成功后在项目的构建目录如build-HelloEmbeddedQt-ARM_Qt5_15_2-Debug/下你会找到生成的可执行文件HelloEmbeddedQt。重要提示此时用file命令查看这个文件file HelloEmbeddedQt。输出应显示为ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked ...。这确认了它是一个ARM架构的可执行文件。如果显示是x86_64说明你的套件配置有误编译成了主机程序。4. 部署到开发板库依赖与运行环境将ARM版本的可执行文件拷贝到开发板使用scp、U盘或SD卡然后通过串口或ssh登录板子执行./HelloEmbeddedQt大概率会失败。最常见的错误是“找不到动态链接库”或“error while loading shared libraries”。4.1 解决动态库依赖问题我们的程序动态链接了Qt的核心库如libQt5Core.so.5, libQt5Gui.so.5, libQt5Widgets.so.5。这些库必须存在于开发板的文件系统中且路径能被动态链接器找到。方法一手动拷贝适用于简单测试这是最直接的方法。在主机上进入Qt的安装目录/opt/qt-5.15.2-arm/lib找到程序依赖的所有Qt库。可以使用arm-linux-gnueabihf-readelf -d HelloEmbeddedQt | grep NEEDED查看具体依赖了哪些库。然后将这些.so文件注意包括符号链接拷贝到开发板的/usr/lib或/lib目录下。但这种方法容易遗漏且污染了板子的系统目录。方法二使用脚本打包依赖推荐编写一个简单的部署脚本deploy.sh使用ldd命令需交叉编译版的ldd或使用$CROSS_COMPILE-readelf解析递归查找所有依赖库并拷贝到一个单独的目录如target-rootfs中保持其相对路径结构。#!/bin/bash # deploy.sh EXECUTABLEHelloEmbeddedQt TARGET_DIR./target-rootfs LIB_DIR/opt/qt-5.15.2-arm/lib # Qt库路径 SYSROOT/opt/sysroot # 系统库路径 mkdir -p $TARGET_DIR cp $EXECUTABLE $TARGET_DIR/ # 一个查找依赖库的简化函数实际应用需要更健壮的脚本处理循环依赖和绝对路径 function copy_deps() { local bin$1 $CROSS_COMPILE-readelf -d $bin | grep NEEDED | awk -F[][] {print $2} | while read lib do # 先在Qt目录找再在sysroot找 if [ -f $LIB_DIR/$lib ]; then cp --parents -n $LIB_DIR/$lib $TARGET_DIR/ copy_deps $LIB_DIR/$lib elif [ -f $SYSROOT/usr/lib/$lib ]; then cp --parents -n $SYSROOT/usr/lib/$lib $TARGET_DIR/ copy_deps $SYSROOT/usr/lib/$lib fi done } copy_deps $EXECUTABLE执行脚本后target-rootfs目录里就包含了可执行文件和它所有的依赖库。将这个目录整个拷贝到开发板例如放到/home/root/myapp。4.2 配置运行环境变量在开发板上运行前需要告诉系统去哪里找我们放在非标准路径下的库。有两种方式设置 LD_LIBRARY_PATH临时export LD_LIBRARY_PATH/home/root/myapp/lib:$LD_LIBRARY_PATH cd /home/root/myapp ./HelloEmbeddedQt这种方式只对当前终端会话有效。修改 Qt 平台插件环境关键步骤 对于嵌入式环境Qt需要知道使用哪个“平台插件”来渲染界面。我们编译时指定了eglfsEmbedded GL Full Screen。运行时需要通过环境变量QT_QPA_PLATFORM来指定。export QT_QPA_PLATFORMeglfs export QT_QPA_EGLFS_INTEGRATIONnone # 对于简单显示可以先尝试这个 # 如果你的板子有特定的触摸屏或显示设备可能需要更多参数 # export QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS/dev/input/event1 # export QT_QPA_EGLFS_PHYSICAL_WIDTH154 # export QT_QPA_EGLFS_PHYSICAL_HEIGHT86 export LD_LIBRARY_PATH/home/root/myapp/lib:$LD_LIBRARY_PATH ./HelloEmbeddedQt将上述环境变量设置和启动命令写成一个run.sh脚本放在应用目录以后每次执行./run.sh即可。5. 常见问题排查与实战技巧实录即便按照步骤操作第一次运行也难免遇到问题。下面是我在多次实践中总结的典型问题及排查思路。5.1 问题一执行程序时报 “No such file or directory”现象./HelloEmbeddedQt后提示此错误但文件明明存在。排查检查文件权限chmod x HelloEmbeddedQt。使用file HelloEmbeddedQt确认它是ARM架构的可执行文件而不是x86_64。最可能的原因动态链接器不对。使用readelf -l HelloEmbeddedQt | grep INTERP查看程序需要的解释器如/lib/ld-linux-armhf.so.3。然后到开发板上检查这个路径是否存在该文件。如果不存在说明你的根文件系统缺少关键的运行时库需要从工具链的sysroot中拷贝ld-linux系列文件到板子的/lib目录下。5.2 问题二 “error while loading shared libraries: libQt5Core.so.5: cannot open shared object file”现象这是最经典的库找不到错误。排查确认LD_LIBRARY_PATH是否已正确设置并且路径中确实包含libQt5Core.so.5。在开发板上使用find / -name libQt5Core.so.5 2/dev/null查找该库是否存在。检查库的架构是否匹配。在主机上用file命令检查你拷贝的.so文件也应该是ARM架构。有时不小心会混入x86的库。检查库的符号链接。Qt的库通常有一系列符号链接如libQt5Core.so - libQt5Core.so.5 - libQt5Core.so.5.15.2。确保完整的链接链都被拷贝到了开发板。5.3 问题三程序运行后无显示或黑屏然后退出现象程序启动后屏幕没有变化或者闪一下黑屏就退出了终端可能有关于平台插件的错误信息。排查检查平台插件首先确认QT_QPA_PLATFORMeglfs环境变量已设置。可以尝试换成linuxfb帧缓冲试试export QT_QPA_PLATFORMlinuxfb。如果linuxfb能显示但eglfs不能可能是你的板子或Qt编译时没有包含或正确配置OpenGL ES支持。查看详细日志设置QT_DEBUG_PLUGINS1环境变量再运行程序会输出详细的插件加载信息有助于定位问题。检查显示设备权限确保运行程序的用户通常是root有权限访问/dev/fb0帧缓冲设备或/dev/dri/card0DRM设备。可以尝试sudo chmod 666 /dev/fb0仅用于测试注意安全。检查Qt编译配置回顾你是否在编译Qt时禁用了必要的图形后端如-no-opengl或-no-eglfs。对于现代GPU通常需要开启-opengl es2。5.4 问题四触摸屏或鼠标键盘无响应现象界面显示正常但无法通过触摸或USB输入设备交互。排查检查输入设备节点在开发板上执行ls /dev/input/查看是否有eventX设备。连接鼠标或触摸屏时观察是否有新的event设备产生。配置Qt环境变量对于触摸屏可能需要指定设备节点export QT_QPA_EVDEV_TOUCHSCREEN_PARAMETERS/dev/input/event1:rotate0。对于鼠标键盘Qt的evdev插件通常能自动识别。可以设置QT_QPA_GENERIC_PLUGINSevdevmouse,evdevkeyboard来强制指定。编译时确保输入支持确认编译Qt时没有使用-no-evdev参数禁用了输入设备支持。5.5 实战技巧精简程序体积嵌入式设备存储空间有限最终发布时需要尽量减小程序体积。使用 release 模式编译在.pro文件中确保有CONFIG release这会进行优化并去掉调试符号。静态编译这是最有效的减容方法。在编译Qt源码时configure加上-static参数。这样编译出的Qt库是静态的最终的可执行文件会包含所有需要的Qt代码体积会变大但不再依赖动态库部署极其简单。注意静态编译可能需要处理一些额外的许可和依赖问题。使用 strip 工具对动态编译的可执行文件和库使用交叉编译工具链中的arm-linux-gnueabihf-strip命令去掉调试符号能显著减小文件大小。strip HelloEmbeddedQt。Qt 编译器裁剪Qt提供了一个名为qt.conf的配置文件可以控制运行时加载哪些插件。你可以只打包程序用到的插件如图像格式插件、平台插件而不是全部。当你在终端看到HelloEmbeddedQt进程启动屏幕上如期出现那个写着“Hello from ARM Board”的窗口时之前所有的繁琐配置和问题排查都值了。这个窗口不仅仅是一个程序界面它更像是一个信号证明你的交叉编译工具链、系统库、Qt库以及运行时环境形成了一个完美的闭环。对于更复杂的项目后续无非是在这个坚实的基础上添加业务逻辑、优化UI、处理硬件交互。掌握了从编译到部署的完整流程你就拥有了在嵌入式世界绘制图形界面的画笔。
