事情得从一块ARM64板子说起。手里这块板子带四核A55跑的是Linux 4.19内核打算做成工业HMI设备界面用Qt来画。Qt版本我定在5.14.2理由后面细讲。真正上手之后才发现交叉编译只是第一步部署才是真正折磨人的环节目标板上没有编译器根文件系统总共就2GB缺一个共享库就得重新打包整个折腾一晚上。所以我把方案锁定在Qt5.14.2的aarch64静态交叉编译上——在x86主机上把Qt编成ARM64静态库产出的应用单独一个可执行文件直接往板子上一拷就能跑不依赖目标板上的Qt动态库、第三方运行库和七七八八的插件文件。这篇文章就是我从零开始搭环境、写configure、跑脚本到最终出包的完整记录中间踩过的坑一个不落全写出来。适合正在做ARM64嵌入式Linux、工控HMI、边缘网关项目的同学参考看完你也能在半天之内把整套工具链跑通。1. 为什么非要用静态交叉编译不可1.1 ARM64设备上的Qt部署痛点很多人一开始的想法是交叉编译一个动态链接的Qt然后放到目标板上运行。这个思路没错但在实际项目里往往会变成一场灾难。目标板上的系统是BusyBox裁剪过的为了省空间连glibc都做了精简更别说Qt运行库和一堆插件了。等你把Qt动态库、platforms插件、字体插件、图片格式插件一个个拷上去再配置LD_LIBRARY_PATH和QT_PLUGIN_PATH最后一个不小心版本没对齐整个应用直接起不来。静态编译能从根本上解决这套依赖搬运问题。把Qt核心库、必要插件和第三方库全部编进你的可执行文件里拷到任何同架构、同内核版本的Linux上都能直接运行。对于产量不高的非标工控设备来说这种“一个文件搞定”的交付方式效率极高省去现场调试依赖的时间。1.2 静态编译到底“静”到什么程度这里得先说明白一个特别容易混淆的概念。网上说“Qt静态编译”通常指的是Qt库本身编成.a静态库你的应用程序链接后不再需要Qt的动态库运行时不依赖libQt5Widgets.so这些东西。但请注意程序最终还是要依赖libc、libstdc、libm这些底层系统库的。如果你连这些底层库都想彻底摆脱那就得做完全静态链接把glibc或者musl也编进去。在aarch64上做完全静态链接一个绕不开的麻烦是glibc的NSS模块、locale数据、DNS解析这类机制需要动态加载完全静态化之后非常容易出问题。所以我的建议很明确做交叉静态编译先把Qt静态化链接libstdc和libgcc的时候用静态方式但保留libc动态链接。这是嵌入式Linux下最稳的方案也是我这篇手册采用的路线。1.3 选择Qt 5.14.2的几个现实理由Qt 5.14.2是LTS之前比较成熟的一个版本发布之后过了这么久各种交叉编译的问题在网上几乎都有答案。相比Qt 65.14.2对老式ARM GPU、Framebuffer、嵌入式显示设备的兼容性更好很多工业HMI方案到今天依然锁死在Qt 5.14。另外官方提供了qt-everywhere-opensource-src-5.14.2.tar.xz这种一站式源码包解压后所有模块都在里面离线环境下也能构建这一点对我们这种保密网络环境下的项目尤其友好。2. 交叉编译环境与工具链准备工作2.1 宿主机环境建议交叉编译对宿主机的配置要求不高我在四核八线程的x86_64 Ubuntu 20.04上完整编译过一次Qt耗时不到四十分钟。建议宿主机使用Debian系Linux发行版因为ARM64交叉工具链在软件源里开箱即用不需要自己从头编GCC。磁盘空间预留至少15GB我实测Qt静态库安装完之后体积大概在2GB左右但源码目录加构建目录再加中间文件峰值空间占用会到10GB以上。内存方面如果make的并行任务数开得太高GCC编C的大文件时内存很容易吃紧。我建议并行数设为CPU核心数减1避免编译到一半Killed。2.2 安装aarch64交叉编译器Ubuntu 20.04直接安装工具链即可sudo apt update sudo apt install -y gcc-aarch64-linux-gnu g-aarch64-linux-gnu装完之后确认版本aarch64-linux-gnu-gcc --versionGCC版本在9到10之间都没问题Qt 5.14.2的代码在这个范围里不会出现编译兼容性毛病。如果你用的是Ubuntu 22.04默认的GCC 11也能用但编译过程中可能会有个别模块因为警告被当作错误处理我后面会在问题排查章节讲怎么绕过。2.3 没有sysroot也能编译的底层逻辑交叉编译嵌入式项目一般要准备一个sysroot里面放着目标板的完整头文件和系统库否则编译器找不到目标板的glibc和内核头文件。不过在Qt的交叉编译里我们可以用另一种方式降低sysroot的依赖把Qt依赖的第三方库全部换成Qt源码自带的内部实现。Qt 5.14.2在configure阶段提供了若干-qt-*参数比如-qt-zlib、-qt-libpng、-qt-libjpeg、-qt-freetype、-qt-pcre。这些参数让Qt在编译时直接使用源码里捆绑的第三方库而不是去sysroot里找主机版本。这样配置好之后我们只需要保证基础编译器可用不需要额外建一个庞大的sysroot。这个设计极大简化了Qt交叉编译的起步阶段也是后面所有步骤能一次跑通的前提。3. Qt 5.14.2源码下载与模块裁剪3.1 下载源码包官方归档目录下载qt-everywhere-opensource-src-5.14.2.tar.xz大概700多MB。下载后用MD5或者SHA256校验一下避免源站镜像损坏。我习惯放到/opt/src下集中管理wget https://download.qt.io/archive/qt/5.14/5.14.2/qt-everywhere-opensource-src-5.14.2.tar.xz tar -xf qt-everywhere-opensource-src-5.14.2.tar.xz解压后的目录结构里qtbase是核心qtdeclarative、qtquickcontrols这些是Qt Quick相关。如果你只做QWidget传统桌面风格的应用很多模块是用不到的。3.2 模块裁剪该扔的扔该留的留qt-everywhere把Qt所有模块打包在一起默认全量编译耗时极长而且交叉编译时部分重量级模块还会带来一堆额外的依赖检查。我建议在configure之前先整理一个“黑名单”。首选要跳过的是qtwebengine这个模块要做完整Chromium内核的交叉编译链到自己怀疑人生基本没人在裸板环境里需要它。然后是qt3d、qtcharts、qtquick3d这些和OpenGL有暧昧关系的模块只要不搞3D界面直接skip。工控场景如果用不到Qt SerialBus和Qt SerialPort以外的高级网络模块也尽量裁剪。我实际使用的跳过清单是这样的-skip qtwebengine -skip qtwebview -skip qtwebchannel -skip qtwebsockets \ -skip qt3d -skip qtcharts -skip qtdatavis3d -skip qtgamepad \ -skip qtlocation -skip qtmqtt -skip qtnetworkauth -skip qtopcua \ -skip qtremoteobjects -skip qtscript -skip qtscxml -skip qtsensors \ -skip qtwayland -skip qtwebengine注意qtserialport和qtserialbus我没有跳因为工控HMI基本都要用串口。你根据自己项目的实际需求来增减原则很简单不用到的模块就别编。4. configure参数逐条拆解4.1 一段可以直接用的configure命令cross-compile配置是整个流程的核心参数非常多我先把一段实测可用的完整命令贴出来再一条一条解释里面的逻辑cd /opt/src mkdir build-qt-aarch64-static cd build-qt-aarch64-static ../qt-everywhere-opensource-src-5.14.2/configure \ -prefix /opt/Qt/5.14.2/aarch64-static \ -opensource -confirm-license \ -release -static \ -xplatform linux-aarch64-gnu-g \ -qt-zlib -qt-libpng -qt-libjpeg -qt-freetype -qt-pcre \ -no-icu -no-dbus \ -no-opengl \ -no-xcb -no-xkbcommon \ -linuxfb \ -no-cups -no-gtk \ -nomake examples -nomake tests -nomake benchmarks \ -skip qtwebengine -skip qtwebview -skip qtwebchannel -skip qtwebsockets \ -skip qt3d -skip qtcharts -skip qtdatavis3d -skip qtgamepad \ -skip qtlocation -skip qtmqtt -skip qtnetworkauth -skip qtopcua \ -skip qtremoteobjects -skip qtscript -skip qtscxml -skip qtsensors \ -skip qtwayland4.2 关键参数背后的原理与选择-static这个参数决定了Qt库以静态库形式输出。不加它后面一切免谈。-release是发布模式去掉调试符号和附加调试信息能显著缩小最终可执行文件体积。-xplatform linux-aarch64-gnu-g告诉Qt使用哪个交叉编译平台配置文件。这里展开讲一下-xplatform。Qt的mkspecs目录里放着很多平台配置linux-aarch64-gnu-g这个目录在Qt 5.14.2源码中是默认带了的。它会自动把编译器设置成aarch64-linux-gnu-g不需要手动修改。但如果你下载的是修改过的源码包或者自定义的工具链就需要检查一下这个目录是否存在。不存在的话最简单的办法是复制linux-g改名然后手动编辑qmake.conf里几个编译器的变量。-qt-zlib -qt-libpng -qt-libjpeg -qt-freetype -qt-pcre这几个参数前面说过了是为了避免依赖宿主机或sysroot里的第三方库统一使用Qt捆绑版本并且这些库会以静态方式编入Qt库。-no-icu和-no-dbus是我个人强烈推荐的。ICU是个巨大的国际化库交叉编译时依赖特别多QWidget传统界面完全不需要它D-Bus在嵌入式系统上也是可选的阉割掉能减少不少麻烦。-no-opengl、-no-xcb、-no-xkbcommon这三个是为了把Graphics和Windowing相关的依赖全部关掉。工控HMI如果用Framebuffer驱动屏幕根本不需要X11也不需要OpenGL。这一套组合拳下来configure阶段最常见的“找不到GL库”“找不到xcb库”问题就从根源上消失了。4.3 显示后端到底选什么linuxfb / minimal / eglfsQt 5.14在嵌入式Linux下的显示后端主要有三个linuxfb直接写Framebufferminimal不碰任何显示设备eglfs基于OpenGL ES驱动显示。适合大多数工控场景的是linuxfb。它直接操作/dev/fb0不依赖X11、不依赖Wayland普通LCD屏、HDMI转RGB屏都能支持。configure参数里加上-linuxfb就能编出linuxfb平台插件。如果目标板带GPU加速器而且你会写OpenGL ES代码那可以考虑eglfs但它要额外准备GPU驱动对应的libEGL和libGLESv2交叉编译配置复杂度高一个档次。minimal平台插件默认也会编译它不做任何显示输出主要用来做无头环境下的冒烟测试。比如在x86主机上用qemu运行aarch64程序时没有实际Framebuffer可用就可以用-platform minimal先验证程序能正常走完初始化流程。4.4 裁剪Qt库模块减掉一半编译时间刚才那串-skip参数直接决定了configure阶段要处理哪些模块。还有一个细节要注意-nomake examples -nomake tests -nomake benchmarks能阻止构建系统编译大量的示例程序。这些示例对正式项目没有用处在交叉编译时只会白白消耗几十分钟。另外-no-cups -no-gtk是关闭打印支持和GTK主题插件。如果你确定设备上没有打印机也不需要通过GTK方式拉取桌面外观这两个功能就是纯负担。4.5 configure阶段需要重点检查的输出跑完configure命令后屏幕末尾会输出一份摘要展示Qt将要构建的模块列表以及各个特性是enabled还是disabled。你一定要花两分钟扫一遍这页内容重点看这几个位置Qt Print Support 是否为 no如果意外变成yes说明-no-cups没生效。X11/XCB Support 是否为 no。OpenGL 相关是否都为 no。LinuxFB 是否为 yes。如果发现某项和你预期不符先别急着make回头检查对应参数。否则等到编到一半才报错排查代价就大多了。5. 从configure到install的一键构建5.1 完整的自动构建脚本每次手工敲configure参数容易出错我习惯把整个流程写成一个shell脚本放在构建目录里方便反复执行。脚本内容如下#!/bin/bash set -e QT_SRC/opt/src/qt-everywhere-opensource-src-5.14.2 BUILD_DIR/opt/src/build-qt-aarch64-static PREFIX/opt/Qt/5.14.2/aarch64-static JOBS$(nproc --ignore1) mkdir -p $BUILD_DIR cd $BUILD_DIR $QT_SRC/configure \ -prefix $PREFIX \ -opensource -confirm-license \ -release -static \ -xplatform linux-aarch64-gnu-g \ -qt-zlib -qt-libpng -qt-libjpeg -qt-freetype -qt-pcre \ -no-icu -no-dbus \ -no-opengl -no-xcb -no-xkbcommon \ -linuxfb \ -no-cups -no-gtk \ -nomake examples -nomake tests -nomake benchmarks \ -skip qtwebengine -skip qtwebview -skip qtwebchannel -skip qtwebsockets \ -skip qt3d -skip qtcharts -skip qtdatavis3d -skip qtgamepad \ -skip qtlocation -skip qtmqtt -skip qtnetworkauth -skip qtopcua \ -skip qtremoteobjects -skip qtscript -skip qtscxml -skip qtsensors \ -skip qtwayland make -j$JOBS make install脚本里我用nproc --ignore1把并行编译任务数设为物理CPU数减1避免内存被吃满。如果你在虚拟机里编译建议直接固定make -j4稳很多。5.2 构建耗时与资源消耗我实测下来上面这套裁剪配置在8核16GB的机器上完整构建时间大约35到40分钟。如果你不裁剪模块直接全量编译时间奔着3小时以上去了。所以说模块裁剪不只是省硬盘空间更是在省你的时间。编译过程最怕的就是中途磁盘空间耗尽我建议每编译十分钟看一眼磁盘df -h /opt/src构建目录里会堆积大量中间对象文件峰值空间很容易到10GB以上别让开发分区成为瓶颈。5.3 验证安装产物是否正常make install完成之后到安装目录里检查一下文件结构ls /opt/Qt/5.14.2/aarch64-static/bin/qmake find /opt/Qt/5.14.2/aarch64-static -name *.a | head -20如果能看到大量的.a静态库文件说明Qt确实是按照静态模式编译出来的。再重点确认一下平台插件文件的位置正常情况下应该在这里ls /opt/Qt/5.14.2/aarch64-static/plugins/platforms/里面应该有libqminimal.a和libqlinuxfb.a这两个静态库文件这是后面应用能否正常跑起来的关键。如果你在目录里看到了.so后缀的动态库那说明configure时-static没生效需要回头检查参数。5.4 给qmake配置交叉链接环境虽然Qt安装完带了独立的qmake但有些交叉编译环节还是需要手动指定编译环境。最好在/opt/Qt/5.14.2/aarch64-static/bin/qmake同目录下放一个环境变量文件例如env.shexport PATH/opt/Qt/5.14.2/aarch64-static/bin:/usr/bin:/bin export CCaarch64-linux-gnu-gcc export CXXaarch64-linux-gnu-g export SYSROOT/usr/aarch64-linux-gnu每次编译应用之前先source env.sh确保qmake和编译器都在PATH里避免把x86宿主机自带的qmake误用了。6. 用静态Qt构建一个真正的GUI应用6.1 创建第一个QWidget工程先写一个最小可用的Qt Widgets程序。创建hello目录里面放三个文件。hello.proQT core gui widgets TARGET hello TEMPLATE app SOURCES main.cpp QTPLUGIN qlinuxfb qminimal qjpeg qgif CONFIG static QMAKE_LFLAGS -static-libgcc -static-libstdcmain.cpp#include QApplication #include QPushButton int main(int argc, char *argv[]) { QApplication app(argc, argv); QPushButton button(Hello from aarch64); button.resize(320, 200); button.show(); return app.exec(); }这个程序逻辑很简单但里面埋了一个静态交叉编译最容易踩的大坑插件链接。Qt 5的QPA架构里创建窗口必须依赖平台插件。动态编译时插件是独立so文件运行时从目录加载静态编译时插件变成了静态库如果不在编译阶段链进主程序运行时就会报“could not find or load the Qt platform plugin”。QTPLUGIN qlinuxfb qminimal qjpeg qgif这一行就是解决这个问题。qmake在静态模式下看到QTPLUGIN会去安装目录的plugins/platforms和plugins/imageformats下面找对应的静态库并链接进来。少写这个程序大概率起不来。6.2 用aarch64静态qmake编译环境变量准备好之后进入hello目录直接编译source /opt/Qt/5.14.2/aarch64-static/bin/env.sh qmake hello.pro make -j4编译完成后用file命令检查产物file hello如果输出里包含ELF 64-bit LSB executable, ARM aarch64说明交叉编译成功。再用ldd查看依赖aarch64-linux-gnu-readelf -d hello | grep NEEDED你会发现依赖列表里没有Qt的库只剩下libc.so.6、libm.so.6、libstdc.so.6、libgcc_s.so.1这几个底层系统库。这正是静态Qt应用该有的样子。6.3 静态插件与静态库的链接顺序问题有时候make链接阶段会报一堆“undefined reference”错误指向QPlatformIntegrationPlugin、QPlatformScreenPlugin这类符号。这通常不是Qt本身的问题而是链接顺序不对。qmake生成的Makefile默认生成的链接命令是合理的但如果你手动加-l参数或者调整了LIBS配置很容易把插件库放在Qt库之前导致链接器先处理libQt5Widgets.a时找不到插件符号。遇到这种问题检查你.pro文件里的LIBS和QTPLUGIN顺序尽量让QTPLUGIN放在最后或者干脆别手动干预插件库的链接。6.4 部署到开发板运行实测把编译好的hello文件通过scp拷到ARM64板子上直接执行chmod x ./hello export QT_QPA_PLATFORMlinuxfb ./hello如果你的板子有真实的/dev/fb0接口屏幕上应该能看到一个“Hello from aarch64”按钮窗口。如果板子是SSH连接的没有接屏可以用minimal平台做无显示冒烟测试./hello -platform minimal能正常退出不报错就说明Qt库本身在目标系统上工作正常。要是这一步能过后面接真屏的时候基本不会有阴暗问题。7. 高频问题与排查技巧实录7.1 configure阶段的两个经典误报第一个是“找不到xcb”相关错误。很多新手明明加了-no-xcbconfigure还是会因为检查系统库失败而中止。原因多半是在-skip或-no-xcb之外还有一个模块强制开启了xcb支持。我的经验是与其一个一个参数排查不如直接在configure命令里同时加上-no-xcb -no-xkbcommon -no-xcb-xlib把X11相关的检查彻底封印起来。第二个是“ICU not found”或者“xkbcommon not found”。Qt 5.14的configure脚本对某些库的检测有优先级即使你后面加了-no-icu如果前面的顺序写错了检测程序还是会去跑一遍。解决办法是确认-no-icu -no-dbus -no-xkbcommon这几个参数都出现在configure命令行中而不是只靠环境变量。7.2 链接阶段报找不到GL库如果configure阶段-no-opengl没有正确生效编译Qt某个模块时就会尝试链接libGL.so而交叉编译环境里没有ARM64版的OpenGL库。排查思路是先回看configure摘要里OpenGL是enabled还是disabled如果是enabled把-no-opengl放到configure命令靠前的位置重新执行。另一种情况是虽然configure摘要里OpenGL是no但某个第三方模块编译时还是会找GL。这种情况直接把对应模块加入-skip列表或者干脆不编译那个模块一劳永逸。7.3 运行时提示找不到platform plugin这是静态Qt最经典的问题出现频率极高。错误信息一般是“This application failed to start because no Qt platform plugin could be initialized”。先说结论99%的原因是QTPLUGIN没有配置正确。请检查hello.pro里有没有QTPLUGIN qlinuxfb并且确认安装目录下的plugins/platforms/libqlinuxfb.a文件真实存在。还有一个隐蔽的原因如果你在configure阶段没有加-linuxfblinuxfb插件压根不会被编译那么就算你写了QTPLUGIN qlinuxfb链接的时候也会因为找不到库而失败。所以项目规划时就要想清楚目标板用哪种显示后端configure阶段就定下来后面改起来比较麻烦。7.4 完全静态libc的坑与实测教训我试过一次用-static把整个产物做成完全静态可执行文件当时觉得“一个文件哪里都能跑”很爽。实测跑起来才发现程序里用QNetworkAccessManager访问域名解析时直接卡死后面一查才知道是因为glibc的NSS模块和/etc/nsswitch.conf那一套机制没法在纯静态环境下正常工作。另外locale、时区这类依赖动态加载数据的功能也全部退化成C默认行为中文路径、中文字符串在这种环境下极易出乱码。所以要再强调一次做静态Qt链接的libstdc和libgcc可以用静态libc请保留动态方式。这个方案既保住了Qt的“一键拷贝部署”优势又不牺牲glibc的基础能力。对部署体验要求高的项目可以考虑用musl工具链做完全静态但那套方案需要所有依赖库都用musl重新编译工作量完全另一个量级不适合作为入门首选。7.5 静态可执行文件体积优化Qt静态编译出来的GUI应用体积一般在10MB左右文件系统紧张的话可以做两步优化。第一步是用strip去掉符号aarch64-linux-gnu-strip hello实测可以减掉20%到30%体积。第二步是检查你是不是不小心链接了用不上的Qt模块例如QT - network只用QWidget的界面程序完全可以去掉Network体积降幅非常明显。7.6 中文字体与Framebuffer显示优化linuxfb本身不做字体渲染Qt会通过freetype引擎读取系统里的字体文件。如果你的目标板是个精简rootfs里面没有中文字体那么界面上所有中文都会变成方块。解决方法是把wqy-microhei.ttc或者NotoSansCJK-Regular.ttc放到板子/usr/share/fonts目录下然后设置环境变量export QT_QPA_FONTDIR/usr/share/fonts再有就是linuxfb模式下如果界面有闪烁感可以尝试启用双缓冲。在程序启动参数里加-plugin linuxfb:fb/dev/fb0:transform0同时在内核启动参数里确认fbcon驱动正常工作帧缓冲设备的刷新策略不理想时还可以在main.cpp里用QCoreApplication::setAttribute(Qt::AA_UseSoftwareOpenGL)捧一把软件渲染。7.7 GCC版本与编译告警的处理在Ubuntu 22.04上使用GCC 11编译Qt 5.14.2偶尔会遇到因为C标准变化导致的编译错误典型现象是某个头文件报deprecated或cannot convert。遇到这种问题最快的修复方式是在configure之前设置环境变量export CXXFLAGS-Wno-deprecated-copy -Wno-errordeprecated-copy如果某个模块始终编不过去先看它是不是你项目里必需的非必需模块直接skip不要在一个不用的模块上浪费半天时间。最后再分享一个我实际维护这套工具链的小技巧建议把构建目录整体打包留档不要编完就删。我自己的习惯是编译成功后把整个/opt/src/build-qt-aarch64-static目录连同Qt安装目录一起备份到外部存储里以后换电脑、开新项目、升级目标板内核时不需要重新花四十分钟跑一遍编译直接把备份解出来就能用。这套Qt 5.14.2的aarch64静态交叉编译方案我用了快两个项目周期期间只因为目标板换了内核版本重新编过一次其他时间基本是“拷贝即用”的状态。希望这份手册能帮你少走几步弯路顺利把ARM64板子上的Qt界面跑起来。
ARM64嵌入式Linux下Qt 5.14.2静态交叉编译实战：从零搭建到一键部署
事情得从一块ARM64板子说起。手里这块板子带四核A55跑的是Linux 4.19内核打算做成工业HMI设备界面用Qt来画。Qt版本我定在5.14.2理由后面细讲。真正上手之后才发现交叉编译只是第一步部署才是真正折磨人的环节目标板上没有编译器根文件系统总共就2GB缺一个共享库就得重新打包整个折腾一晚上。所以我把方案锁定在Qt5.14.2的aarch64静态交叉编译上——在x86主机上把Qt编成ARM64静态库产出的应用单独一个可执行文件直接往板子上一拷就能跑不依赖目标板上的Qt动态库、第三方运行库和七七八八的插件文件。这篇文章就是我从零开始搭环境、写configure、跑脚本到最终出包的完整记录中间踩过的坑一个不落全写出来。适合正在做ARM64嵌入式Linux、工控HMI、边缘网关项目的同学参考看完你也能在半天之内把整套工具链跑通。1. 为什么非要用静态交叉编译不可1.1 ARM64设备上的Qt部署痛点很多人一开始的想法是交叉编译一个动态链接的Qt然后放到目标板上运行。这个思路没错但在实际项目里往往会变成一场灾难。目标板上的系统是BusyBox裁剪过的为了省空间连glibc都做了精简更别说Qt运行库和一堆插件了。等你把Qt动态库、platforms插件、字体插件、图片格式插件一个个拷上去再配置LD_LIBRARY_PATH和QT_PLUGIN_PATH最后一个不小心版本没对齐整个应用直接起不来。静态编译能从根本上解决这套依赖搬运问题。把Qt核心库、必要插件和第三方库全部编进你的可执行文件里拷到任何同架构、同内核版本的Linux上都能直接运行。对于产量不高的非标工控设备来说这种“一个文件搞定”的交付方式效率极高省去现场调试依赖的时间。1.2 静态编译到底“静”到什么程度这里得先说明白一个特别容易混淆的概念。网上说“Qt静态编译”通常指的是Qt库本身编成.a静态库你的应用程序链接后不再需要Qt的动态库运行时不依赖libQt5Widgets.so这些东西。但请注意程序最终还是要依赖libc、libstdc、libm这些底层系统库的。如果你连这些底层库都想彻底摆脱那就得做完全静态链接把glibc或者musl也编进去。在aarch64上做完全静态链接一个绕不开的麻烦是glibc的NSS模块、locale数据、DNS解析这类机制需要动态加载完全静态化之后非常容易出问题。所以我的建议很明确做交叉静态编译先把Qt静态化链接libstdc和libgcc的时候用静态方式但保留libc动态链接。这是嵌入式Linux下最稳的方案也是我这篇手册采用的路线。1.3 选择Qt 5.14.2的几个现实理由Qt 5.14.2是LTS之前比较成熟的一个版本发布之后过了这么久各种交叉编译的问题在网上几乎都有答案。相比Qt 65.14.2对老式ARM GPU、Framebuffer、嵌入式显示设备的兼容性更好很多工业HMI方案到今天依然锁死在Qt 5.14。另外官方提供了qt-everywhere-opensource-src-5.14.2.tar.xz这种一站式源码包解压后所有模块都在里面离线环境下也能构建这一点对我们这种保密网络环境下的项目尤其友好。2. 交叉编译环境与工具链准备工作2.1 宿主机环境建议交叉编译对宿主机的配置要求不高我在四核八线程的x86_64 Ubuntu 20.04上完整编译过一次Qt耗时不到四十分钟。建议宿主机使用Debian系Linux发行版因为ARM64交叉工具链在软件源里开箱即用不需要自己从头编GCC。磁盘空间预留至少15GB我实测Qt静态库安装完之后体积大概在2GB左右但源码目录加构建目录再加中间文件峰值空间占用会到10GB以上。内存方面如果make的并行任务数开得太高GCC编C的大文件时内存很容易吃紧。我建议并行数设为CPU核心数减1避免编译到一半Killed。2.2 安装aarch64交叉编译器Ubuntu 20.04直接安装工具链即可sudo apt update sudo apt install -y gcc-aarch64-linux-gnu g-aarch64-linux-gnu装完之后确认版本aarch64-linux-gnu-gcc --versionGCC版本在9到10之间都没问题Qt 5.14.2的代码在这个范围里不会出现编译兼容性毛病。如果你用的是Ubuntu 22.04默认的GCC 11也能用但编译过程中可能会有个别模块因为警告被当作错误处理我后面会在问题排查章节讲怎么绕过。2.3 没有sysroot也能编译的底层逻辑交叉编译嵌入式项目一般要准备一个sysroot里面放着目标板的完整头文件和系统库否则编译器找不到目标板的glibc和内核头文件。不过在Qt的交叉编译里我们可以用另一种方式降低sysroot的依赖把Qt依赖的第三方库全部换成Qt源码自带的内部实现。Qt 5.14.2在configure阶段提供了若干-qt-*参数比如-qt-zlib、-qt-libpng、-qt-libjpeg、-qt-freetype、-qt-pcre。这些参数让Qt在编译时直接使用源码里捆绑的第三方库而不是去sysroot里找主机版本。这样配置好之后我们只需要保证基础编译器可用不需要额外建一个庞大的sysroot。这个设计极大简化了Qt交叉编译的起步阶段也是后面所有步骤能一次跑通的前提。3. Qt 5.14.2源码下载与模块裁剪3.1 下载源码包官方归档目录下载qt-everywhere-opensource-src-5.14.2.tar.xz大概700多MB。下载后用MD5或者SHA256校验一下避免源站镜像损坏。我习惯放到/opt/src下集中管理wget https://download.qt.io/archive/qt/5.14/5.14.2/qt-everywhere-opensource-src-5.14.2.tar.xz tar -xf qt-everywhere-opensource-src-5.14.2.tar.xz解压后的目录结构里qtbase是核心qtdeclarative、qtquickcontrols这些是Qt Quick相关。如果你只做QWidget传统桌面风格的应用很多模块是用不到的。3.2 模块裁剪该扔的扔该留的留qt-everywhere把Qt所有模块打包在一起默认全量编译耗时极长而且交叉编译时部分重量级模块还会带来一堆额外的依赖检查。我建议在configure之前先整理一个“黑名单”。首选要跳过的是qtwebengine这个模块要做完整Chromium内核的交叉编译链到自己怀疑人生基本没人在裸板环境里需要它。然后是qt3d、qtcharts、qtquick3d这些和OpenGL有暧昧关系的模块只要不搞3D界面直接skip。工控场景如果用不到Qt SerialBus和Qt SerialPort以外的高级网络模块也尽量裁剪。我实际使用的跳过清单是这样的-skip qtwebengine -skip qtwebview -skip qtwebchannel -skip qtwebsockets \ -skip qt3d -skip qtcharts -skip qtdatavis3d -skip qtgamepad \ -skip qtlocation -skip qtmqtt -skip qtnetworkauth -skip qtopcua \ -skip qtremoteobjects -skip qtscript -skip qtscxml -skip qtsensors \ -skip qtwayland -skip qtwebengine注意qtserialport和qtserialbus我没有跳因为工控HMI基本都要用串口。你根据自己项目的实际需求来增减原则很简单不用到的模块就别编。4. configure参数逐条拆解4.1 一段可以直接用的configure命令cross-compile配置是整个流程的核心参数非常多我先把一段实测可用的完整命令贴出来再一条一条解释里面的逻辑cd /opt/src mkdir build-qt-aarch64-static cd build-qt-aarch64-static ../qt-everywhere-opensource-src-5.14.2/configure \ -prefix /opt/Qt/5.14.2/aarch64-static \ -opensource -confirm-license \ -release -static \ -xplatform linux-aarch64-gnu-g \ -qt-zlib -qt-libpng -qt-libjpeg -qt-freetype -qt-pcre \ -no-icu -no-dbus \ -no-opengl \ -no-xcb -no-xkbcommon \ -linuxfb \ -no-cups -no-gtk \ -nomake examples -nomake tests -nomake benchmarks \ -skip qtwebengine -skip qtwebview -skip qtwebchannel -skip qtwebsockets \ -skip qt3d -skip qtcharts -skip qtdatavis3d -skip qtgamepad \ -skip qtlocation -skip qtmqtt -skip qtnetworkauth -skip qtopcua \ -skip qtremoteobjects -skip qtscript -skip qtscxml -skip qtsensors \ -skip qtwayland4.2 关键参数背后的原理与选择-static这个参数决定了Qt库以静态库形式输出。不加它后面一切免谈。-release是发布模式去掉调试符号和附加调试信息能显著缩小最终可执行文件体积。-xplatform linux-aarch64-gnu-g告诉Qt使用哪个交叉编译平台配置文件。这里展开讲一下-xplatform。Qt的mkspecs目录里放着很多平台配置linux-aarch64-gnu-g这个目录在Qt 5.14.2源码中是默认带了的。它会自动把编译器设置成aarch64-linux-gnu-g不需要手动修改。但如果你下载的是修改过的源码包或者自定义的工具链就需要检查一下这个目录是否存在。不存在的话最简单的办法是复制linux-g改名然后手动编辑qmake.conf里几个编译器的变量。-qt-zlib -qt-libpng -qt-libjpeg -qt-freetype -qt-pcre这几个参数前面说过了是为了避免依赖宿主机或sysroot里的第三方库统一使用Qt捆绑版本并且这些库会以静态方式编入Qt库。-no-icu和-no-dbus是我个人强烈推荐的。ICU是个巨大的国际化库交叉编译时依赖特别多QWidget传统界面完全不需要它D-Bus在嵌入式系统上也是可选的阉割掉能减少不少麻烦。-no-opengl、-no-xcb、-no-xkbcommon这三个是为了把Graphics和Windowing相关的依赖全部关掉。工控HMI如果用Framebuffer驱动屏幕根本不需要X11也不需要OpenGL。这一套组合拳下来configure阶段最常见的“找不到GL库”“找不到xcb库”问题就从根源上消失了。4.3 显示后端到底选什么linuxfb / minimal / eglfsQt 5.14在嵌入式Linux下的显示后端主要有三个linuxfb直接写Framebufferminimal不碰任何显示设备eglfs基于OpenGL ES驱动显示。适合大多数工控场景的是linuxfb。它直接操作/dev/fb0不依赖X11、不依赖Wayland普通LCD屏、HDMI转RGB屏都能支持。configure参数里加上-linuxfb就能编出linuxfb平台插件。如果目标板带GPU加速器而且你会写OpenGL ES代码那可以考虑eglfs但它要额外准备GPU驱动对应的libEGL和libGLESv2交叉编译配置复杂度高一个档次。minimal平台插件默认也会编译它不做任何显示输出主要用来做无头环境下的冒烟测试。比如在x86主机上用qemu运行aarch64程序时没有实际Framebuffer可用就可以用-platform minimal先验证程序能正常走完初始化流程。4.4 裁剪Qt库模块减掉一半编译时间刚才那串-skip参数直接决定了configure阶段要处理哪些模块。还有一个细节要注意-nomake examples -nomake tests -nomake benchmarks能阻止构建系统编译大量的示例程序。这些示例对正式项目没有用处在交叉编译时只会白白消耗几十分钟。另外-no-cups -no-gtk是关闭打印支持和GTK主题插件。如果你确定设备上没有打印机也不需要通过GTK方式拉取桌面外观这两个功能就是纯负担。4.5 configure阶段需要重点检查的输出跑完configure命令后屏幕末尾会输出一份摘要展示Qt将要构建的模块列表以及各个特性是enabled还是disabled。你一定要花两分钟扫一遍这页内容重点看这几个位置Qt Print Support 是否为 no如果意外变成yes说明-no-cups没生效。X11/XCB Support 是否为 no。OpenGL 相关是否都为 no。LinuxFB 是否为 yes。如果发现某项和你预期不符先别急着make回头检查对应参数。否则等到编到一半才报错排查代价就大多了。5. 从configure到install的一键构建5.1 完整的自动构建脚本每次手工敲configure参数容易出错我习惯把整个流程写成一个shell脚本放在构建目录里方便反复执行。脚本内容如下#!/bin/bash set -e QT_SRC/opt/src/qt-everywhere-opensource-src-5.14.2 BUILD_DIR/opt/src/build-qt-aarch64-static PREFIX/opt/Qt/5.14.2/aarch64-static JOBS$(nproc --ignore1) mkdir -p $BUILD_DIR cd $BUILD_DIR $QT_SRC/configure \ -prefix $PREFIX \ -opensource -confirm-license \ -release -static \ -xplatform linux-aarch64-gnu-g \ -qt-zlib -qt-libpng -qt-libjpeg -qt-freetype -qt-pcre \ -no-icu -no-dbus \ -no-opengl -no-xcb -no-xkbcommon \ -linuxfb \ -no-cups -no-gtk \ -nomake examples -nomake tests -nomake benchmarks \ -skip qtwebengine -skip qtwebview -skip qtwebchannel -skip qtwebsockets \ -skip qt3d -skip qtcharts -skip qtdatavis3d -skip qtgamepad \ -skip qtlocation -skip qtmqtt -skip qtnetworkauth -skip qtopcua \ -skip qtremoteobjects -skip qtscript -skip qtscxml -skip qtsensors \ -skip qtwayland make -j$JOBS make install脚本里我用nproc --ignore1把并行编译任务数设为物理CPU数减1避免内存被吃满。如果你在虚拟机里编译建议直接固定make -j4稳很多。5.2 构建耗时与资源消耗我实测下来上面这套裁剪配置在8核16GB的机器上完整构建时间大约35到40分钟。如果你不裁剪模块直接全量编译时间奔着3小时以上去了。所以说模块裁剪不只是省硬盘空间更是在省你的时间。编译过程最怕的就是中途磁盘空间耗尽我建议每编译十分钟看一眼磁盘df -h /opt/src构建目录里会堆积大量中间对象文件峰值空间很容易到10GB以上别让开发分区成为瓶颈。5.3 验证安装产物是否正常make install完成之后到安装目录里检查一下文件结构ls /opt/Qt/5.14.2/aarch64-static/bin/qmake find /opt/Qt/5.14.2/aarch64-static -name *.a | head -20如果能看到大量的.a静态库文件说明Qt确实是按照静态模式编译出来的。再重点确认一下平台插件文件的位置正常情况下应该在这里ls /opt/Qt/5.14.2/aarch64-static/plugins/platforms/里面应该有libqminimal.a和libqlinuxfb.a这两个静态库文件这是后面应用能否正常跑起来的关键。如果你在目录里看到了.so后缀的动态库那说明configure时-static没生效需要回头检查参数。5.4 给qmake配置交叉链接环境虽然Qt安装完带了独立的qmake但有些交叉编译环节还是需要手动指定编译环境。最好在/opt/Qt/5.14.2/aarch64-static/bin/qmake同目录下放一个环境变量文件例如env.shexport PATH/opt/Qt/5.14.2/aarch64-static/bin:/usr/bin:/bin export CCaarch64-linux-gnu-gcc export CXXaarch64-linux-gnu-g export SYSROOT/usr/aarch64-linux-gnu每次编译应用之前先source env.sh确保qmake和编译器都在PATH里避免把x86宿主机自带的qmake误用了。6. 用静态Qt构建一个真正的GUI应用6.1 创建第一个QWidget工程先写一个最小可用的Qt Widgets程序。创建hello目录里面放三个文件。hello.proQT core gui widgets TARGET hello TEMPLATE app SOURCES main.cpp QTPLUGIN qlinuxfb qminimal qjpeg qgif CONFIG static QMAKE_LFLAGS -static-libgcc -static-libstdcmain.cpp#include QApplication #include QPushButton int main(int argc, char *argv[]) { QApplication app(argc, argv); QPushButton button(Hello from aarch64); button.resize(320, 200); button.show(); return app.exec(); }这个程序逻辑很简单但里面埋了一个静态交叉编译最容易踩的大坑插件链接。Qt 5的QPA架构里创建窗口必须依赖平台插件。动态编译时插件是独立so文件运行时从目录加载静态编译时插件变成了静态库如果不在编译阶段链进主程序运行时就会报“could not find or load the Qt platform plugin”。QTPLUGIN qlinuxfb qminimal qjpeg qgif这一行就是解决这个问题。qmake在静态模式下看到QTPLUGIN会去安装目录的plugins/platforms和plugins/imageformats下面找对应的静态库并链接进来。少写这个程序大概率起不来。6.2 用aarch64静态qmake编译环境变量准备好之后进入hello目录直接编译source /opt/Qt/5.14.2/aarch64-static/bin/env.sh qmake hello.pro make -j4编译完成后用file命令检查产物file hello如果输出里包含ELF 64-bit LSB executable, ARM aarch64说明交叉编译成功。再用ldd查看依赖aarch64-linux-gnu-readelf -d hello | grep NEEDED你会发现依赖列表里没有Qt的库只剩下libc.so.6、libm.so.6、libstdc.so.6、libgcc_s.so.1这几个底层系统库。这正是静态Qt应用该有的样子。6.3 静态插件与静态库的链接顺序问题有时候make链接阶段会报一堆“undefined reference”错误指向QPlatformIntegrationPlugin、QPlatformScreenPlugin这类符号。这通常不是Qt本身的问题而是链接顺序不对。qmake生成的Makefile默认生成的链接命令是合理的但如果你手动加-l参数或者调整了LIBS配置很容易把插件库放在Qt库之前导致链接器先处理libQt5Widgets.a时找不到插件符号。遇到这种问题检查你.pro文件里的LIBS和QTPLUGIN顺序尽量让QTPLUGIN放在最后或者干脆别手动干预插件库的链接。6.4 部署到开发板运行实测把编译好的hello文件通过scp拷到ARM64板子上直接执行chmod x ./hello export QT_QPA_PLATFORMlinuxfb ./hello如果你的板子有真实的/dev/fb0接口屏幕上应该能看到一个“Hello from aarch64”按钮窗口。如果板子是SSH连接的没有接屏可以用minimal平台做无显示冒烟测试./hello -platform minimal能正常退出不报错就说明Qt库本身在目标系统上工作正常。要是这一步能过后面接真屏的时候基本不会有阴暗问题。7. 高频问题与排查技巧实录7.1 configure阶段的两个经典误报第一个是“找不到xcb”相关错误。很多新手明明加了-no-xcbconfigure还是会因为检查系统库失败而中止。原因多半是在-skip或-no-xcb之外还有一个模块强制开启了xcb支持。我的经验是与其一个一个参数排查不如直接在configure命令里同时加上-no-xcb -no-xkbcommon -no-xcb-xlib把X11相关的检查彻底封印起来。第二个是“ICU not found”或者“xkbcommon not found”。Qt 5.14的configure脚本对某些库的检测有优先级即使你后面加了-no-icu如果前面的顺序写错了检测程序还是会去跑一遍。解决办法是确认-no-icu -no-dbus -no-xkbcommon这几个参数都出现在configure命令行中而不是只靠环境变量。7.2 链接阶段报找不到GL库如果configure阶段-no-opengl没有正确生效编译Qt某个模块时就会尝试链接libGL.so而交叉编译环境里没有ARM64版的OpenGL库。排查思路是先回看configure摘要里OpenGL是enabled还是disabled如果是enabled把-no-opengl放到configure命令靠前的位置重新执行。另一种情况是虽然configure摘要里OpenGL是no但某个第三方模块编译时还是会找GL。这种情况直接把对应模块加入-skip列表或者干脆不编译那个模块一劳永逸。7.3 运行时提示找不到platform plugin这是静态Qt最经典的问题出现频率极高。错误信息一般是“This application failed to start because no Qt platform plugin could be initialized”。先说结论99%的原因是QTPLUGIN没有配置正确。请检查hello.pro里有没有QTPLUGIN qlinuxfb并且确认安装目录下的plugins/platforms/libqlinuxfb.a文件真实存在。还有一个隐蔽的原因如果你在configure阶段没有加-linuxfblinuxfb插件压根不会被编译那么就算你写了QTPLUGIN qlinuxfb链接的时候也会因为找不到库而失败。所以项目规划时就要想清楚目标板用哪种显示后端configure阶段就定下来后面改起来比较麻烦。7.4 完全静态libc的坑与实测教训我试过一次用-static把整个产物做成完全静态可执行文件当时觉得“一个文件哪里都能跑”很爽。实测跑起来才发现程序里用QNetworkAccessManager访问域名解析时直接卡死后面一查才知道是因为glibc的NSS模块和/etc/nsswitch.conf那一套机制没法在纯静态环境下正常工作。另外locale、时区这类依赖动态加载数据的功能也全部退化成C默认行为中文路径、中文字符串在这种环境下极易出乱码。所以要再强调一次做静态Qt链接的libstdc和libgcc可以用静态libc请保留动态方式。这个方案既保住了Qt的“一键拷贝部署”优势又不牺牲glibc的基础能力。对部署体验要求高的项目可以考虑用musl工具链做完全静态但那套方案需要所有依赖库都用musl重新编译工作量完全另一个量级不适合作为入门首选。7.5 静态可执行文件体积优化Qt静态编译出来的GUI应用体积一般在10MB左右文件系统紧张的话可以做两步优化。第一步是用strip去掉符号aarch64-linux-gnu-strip hello实测可以减掉20%到30%体积。第二步是检查你是不是不小心链接了用不上的Qt模块例如QT - network只用QWidget的界面程序完全可以去掉Network体积降幅非常明显。7.6 中文字体与Framebuffer显示优化linuxfb本身不做字体渲染Qt会通过freetype引擎读取系统里的字体文件。如果你的目标板是个精简rootfs里面没有中文字体那么界面上所有中文都会变成方块。解决方法是把wqy-microhei.ttc或者NotoSansCJK-Regular.ttc放到板子/usr/share/fonts目录下然后设置环境变量export QT_QPA_FONTDIR/usr/share/fonts再有就是linuxfb模式下如果界面有闪烁感可以尝试启用双缓冲。在程序启动参数里加-plugin linuxfb:fb/dev/fb0:transform0同时在内核启动参数里确认fbcon驱动正常工作帧缓冲设备的刷新策略不理想时还可以在main.cpp里用QCoreApplication::setAttribute(Qt::AA_UseSoftwareOpenGL)捧一把软件渲染。7.7 GCC版本与编译告警的处理在Ubuntu 22.04上使用GCC 11编译Qt 5.14.2偶尔会遇到因为C标准变化导致的编译错误典型现象是某个头文件报deprecated或cannot convert。遇到这种问题最快的修复方式是在configure之前设置环境变量export CXXFLAGS-Wno-deprecated-copy -Wno-errordeprecated-copy如果某个模块始终编不过去先看它是不是你项目里必需的非必需模块直接skip不要在一个不用的模块上浪费半天时间。最后再分享一个我实际维护这套工具链的小技巧建议把构建目录整体打包留档不要编完就删。我自己的习惯是编译成功后把整个/opt/src/build-qt-aarch64-static目录连同Qt安装目录一起备份到外部存储里以后换电脑、开新项目、升级目标板内核时不需要重新花四十分钟跑一遍编译直接把备份解出来就能用。这套Qt 5.14.2的aarch64静态交叉编译方案我用了快两个项目周期期间只因为目标板换了内核版本重新编过一次其他时间基本是“拷贝即用”的状态。希望这份手册能帮你少走几步弯路顺利把ARM64板子上的Qt界面跑起来。
