从零搭建Qt 5.14.2 aarch64静态交叉编译环境一份可复现的完整手册这些年做嵌入式Linux开发绕不开的一个话题就是GUI程序怎么上板子。如果你只需要画几个控件、显示几张图片那轻量级方案很多可一旦业务复杂到需要完整的控件库、富文本、WebEngine或者复杂布局业界真正靠谱的选择还是Qt。而Qt在ARM板子上部署又绕不开“交叉编译”这个词。这篇文章我从头到尾记录了一次Qt 5.14.2在aarch64平台上的静态交叉编译完整过程。关键词就三个Qt 5.14.2、aarch64、静态交叉编译。适合正在做ARM64平台产品开发、或者准备把Qt应用移植到国产化板卡上的同行参考。我会把环境准备、工具链选择、configure参数、常见报错全部摊开讲尽量做到你看完就能照着做。有一点要先说清楚Qt版本我特意选了5.14.2不是最新的5.15 LTS也不是Qt 6。原因后面章节细讲但核心一点——5.14.2罪稳定、兼容性好用它踩坑最少。1. 项目整体设计与思路拆解1.1 为什么是aarch64为什么静态编译aarch64是ARM 64位指令集的官方名字现在工控、安防、医疗、电力那边的新板子基本都是这个架构。以前用的armv732位ARM在慢慢被替换原因是64位带来更高的内存寻址上限和更强的计算性能跑起带WebEngine的Qt程序差别非常明显。再聊静态编译。嵌入式Linux上部署Qt程序传统上有两种方式动态编译Qt库以.so的形式放到/usr/lib里程序运行时候加载。需要rootfs里固化了匹配版本的Qt库板子之间拷贝必须保证环境一致。静态编译整个Qt库直接链接进你的可执行文件生成一个体积很大的单个ELF文件扔到任何同架构板子上都能跑。静态编译在嵌入式场景下优势非常大不用管目标板的库依赖、不用调整加载路径、单文件拷过去就能跑。缺点是文件体积大Qt Widgets静态链接后通常25MB起步但对比部署省下来的精力这多出来的体积多数时候可以接受。1.2 Qt版本选型背后的考量和替代方案Qt官方对LTS版本的支持策略是5.12、5.15是LTS5.14不是。按常理选LTS更“正规”但我最终锁定5.14.2原因很实际5.14.2对应qmlcachegen等工具链相对完善交叉编译时auxiliary host工具出问题的概率低。5.14系列在嵌入式配置选项上比5.12多了不少新特性又不像5.15那样动不动引入更高的gcc标准要求。我在两三个产线上用5.14.2做过长期跑批测试稳定性有底。网上关于5.14.2交叉编译的资料积累充足踩坑后能找到的参考最多。如果你是新项目、没有历史包袱也可以考虑5.15.2最后一个支持Windows 7的LTS但要用gcc 9以上编译对老工具链不友好。5.14.2对gcc 7/8/9都兼容得不错这是它作为交叉编译版本的优势。1.3 方案全貌从源码到aarch64静态可执行文件的链路整个编译链路可以概括为在x86_64开发机上安装aarch64交叉编译工具链。准备aarch64的sysroot包含目标板rootfs的头文件和库文件。用交叉工具链从头编译Qt 5.14.2源码关键参数-static、-xplatform。配置Qt的qmake交叉编译环境让后续qmake生成Makefile时能自动调用aarch64的编译器。用qmake编译业务应用生成静态可执行文件。拷贝到aarch64目标板直接运行。这里面最容易出问题的是第3和第4步configure参数配错会导致编译直接中断sysroot缺失库文件会导致各种undefined reference。后面的章节我会一步步拆解。2. 环境准备与工具链选型2.1 开发机环境说明我用的是Ubuntu 18.04.6 x86_64。为什么不建议用更新的Ubuntu 20.04/22.04来做这个事因为Qt 5.14.2官方发布的预编译工具链以及网上可查的各种配置组合大多是在gcc 7/8/9环境下验证过的。新系统自带gcc 11或其他更高版本虽然可以手动降级但徒增成本。$ cat /etc/os-release NAMEUbuntu VERSION18.04.6 LTS (Bionic Beaver) $ gcc --version gcc (Ubuntu 7.5.0-3ubuntu1~18.04) 7.5.0 $ uname -m x86_64两个原则编译主机尽可能干净不需要的图形界面可以不开磁盘剩余空间至少保证20GB编译Qt源码全量构建需要10GB左右。2.2 交叉工具链Linaro aarch64 gcc 7.5交叉编译工具链选择Linaro出品的gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu。这是嵌入式圈最常见的选择编译器版本7.5.0glibc 2.28兼容性很好。# 下载工具链并解压到/opt目录 cd /opt wget https://releases.linaro.org/components/toolchain/binaries/7.5-2019.12/aarch64-linux-gnu/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu.tar.xz tar xvf gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu.tar.xz解压完目录结构是这样的/opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/ ├── aarch64-linux-gnu/ │ ├── bin/ │ ├── lib/ │ ├── libc/ │ └── ... ├── bin/ │ ├── aarch64-linux-gnu-gcc │ ├── aarch64-linux-gnu-g │ └── ... └── lib/这里有个细节必须注意工具链自带了一个aarch64的libc在aarch64-linux-gnu/libc目录下理论上可以直接当作sysroot的一部分用。但实际项目里目标板的glibc版本可能和工具链自带的不同最稳妥的方式是直接把目标板的rootfs拷贝到开发机以它为准。2.3 sysroot构造两种方式对比sysroot就是交叉编译时编译器寻找头文件和库文件的根目录。它必须与目标板运行环境一致否则编译出来的程序可能在板子上跑不起来或运行时报version GLIBC_2.28 not found这类错误。我用的是“直接拷贝目标板rootfs”的方式mkdir -p /opt/aarch64-sysroot # 把目标板或设备厂商提供的rootfs拷贝到/opt/aarch64-sysroot # 例如rsync板子的/usr、/lib、/etc等目录另一种方式是Linaro工具链自带的libc作为sysroot好处是省事坏处是和真实目标环境可能有偏差。我的建议做产品就老老实实用板子配套的rootfs做通用学习可以偷懒用工具链自带的。sysroot准备好后先验证工具链能否正常使用交叉编译export PATH/opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/bin:$PATH aarch64-linux-gnu-gcc --version # 写个hello world测试 echo int main(){return 0;} test.c aarch64-linux-gnu-gcc -o test test.c file test # 输出应该包含 ELF 64-bit LSB executable, ARM aarch64这里我强烈建议先把这一步跑通再往下走。交叉工具链本身有问题的话后面Qt编译过程里报错会非常难排查。2.4 Qt 5.14.2源码下载与安全校验Qt官方提供了所有历史版本的源码包Qt 5.14.2源码可以从Qt官方Archive获取文件名是qt-everywhere-src-5.14.2.tar.xz。体积大约500MB解压后约3GB。cd /opt wget https://download.qt.io/archive/qt/5.14/5.14.2/single/qt-everywhere-src-5.14.2.tar.xz tar xvf qt-everywhere-src-5.14.2.tar.xz下载完成后建议检验一下SHA1校验和防止下载文件损坏导致编译到一半报莫名奇妙的错误。官方页面上能看到对应哈希值用sha1sum比对一下即可。3. Qt源码configure阶段的配置与原理3.1 configure参数详解每个选项为什么选它进入Qt源码目录后正式开工。先创建编译输出目录强烈建议不要直接在源码目录里配置方便清理mkdir -p /opt/qt-build cd /opt/qt-everywhere-src-5.14.2我最终使用的configure命令如下./configure -prefix /opt/qt5.14.2-aarch64-static \ -opensource -confirm-license \ -release -static -strip \ -xplatform linux-aarch64-gnu-g \ -sysroot /opt/aarch64-sysroot \ -no-opengl -no-gui \ -no-feature-vnc -no-feature-printpreview \ -no-dbus -no-icu -no-cups -no-tslib \ -nomake examples -nomake tests \ -skip qtwebengine -skip qtwebview -skip qtquick3d \ -no-use-gold-linker \ -qt-zlib -qt-libpng -qt-libjpeg \ -qt-pcre -qt-harfbuzz \逐项拆解-prefix /opt/qt5.14.2-aarch64-static安装路径。这个路径会写入qmake生成的Makefile里建议固定下来后面不要变。-release -staticrelease模式、静态编译核心中的核心。-xplatform linux-aarch64-gnu-gQt的交叉平台名。Qt 5.14里内置了这个mkspec对应mkspecs/linux-aarch64-gnu-g目录。如果你用的不是Linaro工具链这里可以自己写一个mkspec但先用它内置的就好。-sysroot /opt/aarch64-sysroot指定sysroot路径让配置阶段能找到aarch64的头文件和库。-no-opengl -no-gui注意这里的-no-gui不是禁用Qt GUI模块而是禁用窗口系统相关特性xcb、wayland等因为我们是无界面或极简界面场景。如果你需要完整Widgets界面并且目标板有显示环境需要去掉-no-gui改为对xcb等平台插件单独配置。-skip qtwebengineWebEngine在嵌入式交叉编译里是最大的坑涉及大量编译依赖一般不需要就果断跳过。-qt-zlib -qt-libpng -qt-libjpeg -qt-pcre -qt-harfbuzz让Qt使用自带的第三方库而不是依赖sysroot里的版本。这一步是为了避免“你板子里的libpng和我编译时用的libpng版本不一致”这类玄学问题静态编译下尤其重要。configure阶段如果报错先看输出最后几行。最常见的是两个找不到交叉编译器、sysroot路径不完整。前者检查PATH变量后者检查-sysroot参数对应的目录是否存在并且里面有没有usr/include、usr/lib这些基础目录。3.2 编译与安装过程实测时长与资源占用configure通过后接下来就是漫长的make过程。建议用-j参数充分利用CPU多核make -j$(nproc)我当年用的机器是8核16线程编译Qt 5.14.2模块跳过WebEngine后大约需要40分钟到1小时。如果不开-j单线程跑可能要三四个小时。有两个点要特别提醒不要急着一上来就make install先看make是否完整通过。如果中途报错修改配置后重新编译先make clean再configure否则可能出现残留问题。编译过程中如果报cannot find -lXXX不要慌基本都是sysroot里缺对应的开发库。找到报错的名字到sysroot里确认头文件和.so是否存在缺失就从目标板上补齐。安装make install这一步执行完/opt/qt5.14.2-aarch64-static目录下就会生成完整的Qt交叉编译库包括lib、include、binqmake注意这个qmake是x86_64的但生成的Makefile会针对aarch64、mkspecs目录。3.3 安装完成后的验证方法安装完第一时间验证Qt是否正确交叉编译export PATH/opt/qt5.14.2-aarch64-static/bin:$PATH qmake -query看看输出里QT_SYSROOT、QT_INSTALL_PREFIX等路径是否指向正确位置。接下来创建一个最小Qt Widgets程序测试mkdir -p /tmp/qt-test cd /tmp/qt-test cat main.cpp EOF #include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(Hello Qt on aarch64); label.show(); return app.exec(); } EOF cat test.pro EOF QT widgets SOURCES main.cpp TARGET qt-test EOF /opt/qt5.14.2-aarch64-static/bin/qmake test.pro make file qt-testfile命令输出应为qt-test: ELF 64-bit LSB executable, ARM aarch64, dynamically linked ...这里的动态链接指的是链接到Qt静态库里的系统库部分如libc、libstdc、libpthreadQt本身的库已经被静态合并进ELF了。你可以用aarch64-linux-gnu-readelf -d qt-test | grep NEEDED查看依赖会发现只剩基础系统库不会再有libQt5Widgets.so.5这种了。4. 静态交叉编译的完整实操流程4.1 业务项目中的qmake工程配置写法交叉编译环境和qmake配置就绪后真正的业务工程怎么接入下面是一个标准的qmake工程文件写法我直接给可复制的完整版QT core gui widgets CONFIG c11 static TARGET myapp TEMPLATE app # 静态编译相关配置 QMAKE_LFLAGS -static # 如果程序较大推荐去掉符号表减小体积 QMAKE_CXXFLAGS_RELEASE -fno-exceptions -fno-rtti # 链接时按需裁剪 QMAKE_LFLAGS_RELEASE -Wl,--gc-sections QMAKE_CXXFLAGS_RELEASE -ffunction-sections -fdata-sections # 关闭默认的动态链接选项 CONFIG - dynamic SOURCES \ main.cpp \ mainwindow.cpp HEADERS \ mainwindow.h RESOURCES \ resources.qrc这里QMAKE_LFLAGS -static是核心。加上后Qt会尝试把所有链接库静态链接进最终可执行文件。如果漏了它可能出现Qt库是静态编的但链接出来的还是动态依赖Qt库的情况困扰很多新手。另外一个经验不要加CONFIG static这种情况qmake对static配置的支持比较暧昧在不同版本上行为不一致。显式指定QMAKE_LFLAGS -static是Linux下最可靠的。4.2 动态加载插件与静态插件的处理Qt的平台插件机制在静态编译场景下需要特殊处理。默认情况下Qt的平台插件比如linuxfb、eglfs、xcb是独立.so文件程序运行时会从插件目录动态加载。静态编译时这些插件不会自动被带进可执行文件。解决办法有两种第一种在pro文件里显式添加插件库的链接# 在pro中加入你要使用的平台插件 LIBS -lqlinuxfb -lqeglfs QTPLUGIN qlinuxfb qeglfs第二种使用Qt自带的Q_IMPORT_PLUGIN宏在main.cpp的最前面导入需要的插件#include QtPlugin Q_IMPORT_PLUGIN(QLinuxFbIntegrationPlugin)然后程序启动时通过-platform linuxfb参数指定平台。这种方法的好处是插件和主程序绑死不再依赖目标板上的插件目录结构。我用的是linuxfbLinux帧缓冲作为测试构型因为我们的目标板只有几块显示屏没有复杂的桌面环境linuxfb是最轻的行为方式。4.3 应用部署如何静静地把这个大文件放到板子上静态编译出来的Qt程序体积非常大一个简单Widgets项目动不动25~40MB。不要试图用命令行直接传效率太低。推荐三个方式如果板子支持SSH/NFS优先用scp/rsync传。通过U盘拷贝这是工控场景最常见的。把程序放进rootfs镜像里随镜像烧录。# scp传文件到板子 scp qt-test root192.168.1.100:/root/ # 到板子上执行 chmod x qt-test ./qt-test -platform linuxfb实测一个包含基本Widgets控件的程序静态编译后35MB直接拷贝到开发板运行非常流畅。没有任何动态库依赖这在批量交付维护的场景里极其珍贵。4.4 部署验证与运行检查在板子上运行之前先立几个检查项# 查看系统架构 uname -a # 确认ELF格式 file /root/qt-test # 查看动态链接依赖应该只剩系统库 readelf -d /root/qt-test | grep NEEDED如果运行报No such file or directory但是程序明明存在大概率是动态链接器中某个库找不到或者程序是动态链接的但目标板缺少Qt依赖。这种问题在纯静态编译下基本不会出现。运行GUI程序需要确认显示环境export QT_QPA_PLATFORMlinuxfb export QT_QPA_FB_DRM1 # 如果需要DRM渲染 ./qt-test没有显示器的情况可以用-offscreen参数测试./qt-test -platform offscreen能正常启动不崩溃说明Qt的静态编译链路是通的剩下的就是显示适配层面的调试。5. 常规问题与排查技巧实录5.1 交叉编译时的三大报错类型速查表下面这些错误是我在不同项目里实际遇到并解决的整理成一张速查表按出现频率排序报错现象根因解决方法cannot find -lGLOpenGL相关库缺失configure没有正确禁用OpenGL检查configure是否加-no-opengl或到sysroot补齐libGL库undefined reference to symbol XOpenDisplayX11相关库缺失或顺序不对静态链接时库顺序很关键把依赖库放到被依赖库之后fatal error: zlib.h: No such file or directorysysroot里缺少zlib开发头文件用-qt-zlib让Qt内置zlib或到sysroot安装zlib-devqmake: could not find a Qt installation of qmake的qmake路径配置不对检查qmake -query的输出看QT_INSTALL_PREFIX是否指向/opt/qt5.14.2-aarch64-staticmultiple definition of qt_version_tagQt库被重复链接检查pro里是否误加了多个Qt库路径或清理Makefile后重新qmake5.2 静态链接时反复出现的undefined reference根源分析静态链接报undefined reference比动态链接多得多原因是顺序敏感性。GNU ld或gold在遍历静态库时是单次扫描从左到右处理每个对象文件/库如果碰到未定义符号就记录下来但如果一个符号在右侧的库里定义了而左侧库引用了它——那不会再回头去那个库查找。这意味着链接库的顺序必须遵循依赖关系被依赖的库放到后面。例如Qt Widgets程序常见写法LIBS -lQt5Widgets -lQt5Gui -lQt5Core但如果你的程序用到了Qt5Gui的更多功能比如图像处理而Qt5Gui依赖Qt5Core按上面顺序链接没问题。可一旦在中间插入其他库打乱顺序就极容易报undefined reference to QWidget::xxx。动态链接没有这个限制静态链接必须严格排序。我的习惯是让qmake自动管理Qt库顺序默认顺序正确自己手动追加系统库时只往后加不往前插。5.3 sysroot缺失库文件的两种补法在实际项目里目标板rootfs往往不是完整开发环境缺开发库-dev包是常态。Qt configure阶段或者编译阶段报缺头文件/缺库时有两种补法第一种如果目标板能联网装包直接在板子上装然后重新打包rootfs# 在目标板上 apt-get install libxcb1-dev libx11-dev libxkbcommon-dev第二种目标板不能装包产线锁死找同架构的其他系统镜像解包把文件和目录拷贝到sysroot里。这个操作要非常小心不能覆盖sysroot里已有的库文件优先新增加值而不是修改已有内容。用第二种方式补文件时有一个关键操作需要保留库的软链接结构。比如拷贝libz.so要确保sysroot里有libz.so - libz.so.1 - libz.so.1.2.11的完整链否则链接器找不到同名不带版本号的软链接文件依然报cannot find -lz。5.4 目标板运行时崩溃的常见原因编译链接成功、生成静态可执行文件并不意味着一定能在板子上正常运行。我遇到过的运行时崩溃原因按概率排列glibc向后兼容问题交叉工具链的glibc版本比目标板高编译出的程序依赖更高的GLIBC_XX版本板子上的老glibc无法满足。解决使用与目标板glibc版本匹配或更低版本的工具链。缺少字体文件Qt Widgets如果启用了文本渲染默认会找系统字体目录。静态编译后如果目标板无字体会显示方块或乱码。解决把文泉驿或者Noto字体拷到板子的/usr/share/fonts或者Qt的lib/fonts目录。平台插件不匹配程序在板子上运行时找不到对应平台插件或者插件与编译时配置不一致。解决确保-platform参数指定的插件已被静态导入。5.5 体积优化三板斧静态编译体积大但有几个有效的减重手段第一编译选项压缩。用-ffunction-sections -fdata-sections配合链接器-Wl,--gc-sections可以去掉未引用的函数和数据reduce体积10~20%。第二裁剪不需要的Qt模块。Qt 5.14里用-skip跳过用不到的模块比如我们用不到WebEngine、Quick 3D直接跳过既减少编译时间又减小体积。release模式本身就带了-O2优化和二进制瘦身strip掉符号表又能省一部分。第三字体和图标资源精简。静态编译下Qt的资源文件qrc直接编进二进制字体、图标这类大资源注意压缩。一个.ttf字体2~5MB如果放了多个没用的字重整个程序体积膨胀很快。实测一个全功能Widgets程序三项手段全用上从42MB降到31MB左右效果还是可观的。6. 实际项目体会这套环境能给你带来什么做了这么多年嵌入式开发我最大的感受是交叉编译本身不难难在“环境一致性”。静态Qt帮你解决了运行时依赖的问题但前提是编译链路上的每个环节都拧紧螺丝。这个Qt 5.14.2 aarch64静态编译环境我已经在两个项目里实际使用了一个是工业触摸屏控制程序一个类似HMI界面的数据采集终端。完全单文件部署出厂时烧好一个ELF、一个配置文件就够了从来没出现“换台设备程序跑不起来”的问题。对于一个要批量交付到现场的设备来说这种安心感千金难换。如果你准备在自己的板子上搭这套环境我的建议是别图快严格按照configure参数来每一步跑通再往下走。尤其是sysroot构造宁可多花半天时间准备得完整一些也不要等到Qt编译到一半才发现缺东缺西。最后分享一个小技巧把整套配置命令和目录结构写进一个一键脚本每次新接手项目或者指导同事搭环境直接跑一遍脚本二十分钟能搭好一套一模一样的交叉编译环境。这样不光自己省事团队协作时也能保证大家的编译结果一致。