做嵌入式 Linux 开发的朋友应该都体会过“库依赖地狱”的痛。如果你的应用要部署到 ARM64aarch64设备上同时又希望运行时只丢一个二进制文件过去不挂一堆.so那么 Qt 5.14.2 的 aarch64 静态交叉编译就是一条非常值得走通的路。这篇文章我把自己从零开始搭环境、配置 Qt、交叉编译、到最终跑在板子上的完整过程写出来包括参数为什么要这么选、哪些模块可以砍掉、静态插件怎么处理以及我踩过的几个实打实的坑。适合刚接触 ARM64 平台、急着出可交付程序的嵌入式开发者和测试工程师参考。1. 动手前先把思路理清楚为什么是 Qt 5.14.2、aarch64 与静态交叉编译1.1 这个组合解决什么问题先拆开看这三个关键词。Qt 5.14.2虽然不是 5.12 那种纯 LTS 版本但胜在源码包完整、模块稳定5.15 之后官方对开源离线源码包的下载方式做了不小调整反而 5.14.2 的qt-everywhere-opensource-src-5.14.2.tar.xz这类包仍然保留在归档目录里下载方便社区资料也多。对很多量产的嵌入式设备来说5.14.2 已经覆盖了 Widgets、Quick、网络、串口这些常用能力版本换代不用追太激进。aarch64 是现在几乎所有新平台的基础架构。树莓派 64 位系统、瑞芯微 RK3568/RK3588、飞腾、鲲鹏以及各种工业级 ARM 核心板清一色是 aarch64。也就是说只要你的目标设备不是太老按 aarch64 编译基本是通用做法。静态交叉编译则是把“编出来能跑”和“拿到哪都能跑”这两件事同时解决。Qt 官方安装包一般只提供 x86 平台目标板基本拿不到现成的 Qt 包所以必须交叉编译。为什么要静态嵌入式板子上的文件系统一般很小动态依赖多的时候经常出现“程序拷过去一运行就报缺少 libQt5Core.so.5”的情况。静态编译后二进制文件直接包含 Qt 核心库和你选择使用的第三方库跑起来省心不少。1.2 静态交叉编译的关键约束交叉编译本身就是一个“在 A 平台上编译 B 平台程序”的过程复杂点主要在三个地方工具链要认对、sysroot 要对准、依赖库要给全。静态版本又额外加了一堆约束。第一目标平台的 glibc 静态库必须存在。工具链只有编译器还不够如果最终链接阶段想生成纯静态的可执行文件那么/usr/aarch64-linux-gnu/lib/下面必须有libc.a、libm.a、libpthread.a这类静态库。很多精简交叉工具链只带了.so没带.a配置完成后一执行链接就报cannot find -lc这个问题很典型。第二Qt 的第三方组件策略要收敛。Qt 默认会去检测系统里的 zlib、libpng、libjpeg、freetype、glib、ICU、dbus、xcb 等库。在交叉编译环境下这些库大多不在默认路径里configure 检测要么跳过、要么失败与其让它自动探测不如主动指定用 Qt 源码自带的版本-qt-zlib -qt-libpng -qt-libjpeg -qt-freetype -qt-pcre把外部依赖降到最低。第三帧缓冲插件要提前想好。aarch64 板子有的是带 GPU 的但很多工业板干脆就是简单的 DRM/KMS 或 framebuffer。为了少引入 OpenGL ES/EGL 那套依赖可以先走linuxfb平台插件把程序跑起来后面真需要 GPU 加速再补 EGLFS 也不迟。这些约束决定了后面所有配置不是随手敲几个命令就能过的。2. 先把地基打牢主机环境、交叉工具链与 Qt 源码包2.1 主机基本要求与依赖安装我这边用的主机是 Ubuntu 22.04 x86_648 核 CPU16GB 内存。编译 Qt 5.14.2 源码建议至少 4 核以上否则make -j会等得很痛苦。磁盘空间方面源码包解压后大约 5GB 左右构建目录再加 10GB所以给/home或者工作目录留出 20GB 以上比较安心。交叉编译需要的基础工具链直接在 apt 里装就有sudo apt update sudo apt install build-essential gcc-aarch64-linux-gnu g-aarch64-linux-gnuUbuntu 20.04 对应 GCC 9.322.04 对应 GCC 11.x都可以编 Qt 5.14.2。另外还要装目标平台的 C 库开发包否则之后静态链接时会缺少libc.asudo apt install libc6-dev-arm64-cross安装完成后验证一下工具链是否可用aarch64-linux-gnu-gcc --version aarch64-linux-gnu-gcc -v能正常输出版本信息说明PATH已经没问题。如果自己下载了 Linaro 工具链记得把bin目录加到环境变量里比如export PATH/opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/bin:$PATH2.2 交叉工具链与 sysroot 准备Ubuntu 自带的交叉工具链默认会把 aarch64 相关的头文件和库放在/usr/aarch64-linux-gnu/你可以把它理解成目标板的 sysroot。执行ls /usr/aarch64-linux-gnu/lib/libc.a能看到libc.a说明后续做全静态链接有戏。如果你用的是 Yocto 构建的 SDK 或者厂商提供的工具链通常会有一个明确定义的 sysroot 目录比如/opt/fsl-imx-x11/4.1.15-2.1.0/sysroots/aarch64-poky-linux/。这种情况需要在后续配置 Qt 时明确把 sysroot 告诉编译器常用做法是在对应的 qmake.conf 里追加QMAKE_CFLAGS --sysroot/path/to/sysroot QMAKE_CXXFLAGS --sysroot/path/to/sysroot QMAKE_LFLAGS --sysroot/path/to/sysroot在实际决定采用哪种 sysroot 之前建议先确认目标板子的 glibc 版本和运行库。如果目标板是 Debian/Ubuntu 系直接用 Ubuntu 主机上的交叉工具链即可如果目标板是 busybox 精简环境尽量从厂商提供的 rootfs 里抽取 sysroot避免二进制在目标板上因为 glibc 版本不对而无法运行。2.3 Qt 源码包获取与目录规划Qt 5.14.2 的源码包还在官方 archive 下。下载命令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 cd qt-everywhere-opensource-src-5.14.2这个包解压出来是完整的 Qt 源码树包含了 qtbase、qtdeclarative、qtmultimedia 等大量模块。接下来我会新建一个独立的构建目录不让编译中间文件污染源码目录cd .. mkdir build-qt-5.14.2-aarch64-static cd build-qt-5.14.2-aarch64-static目录规划上建议这样安排目录用途/home/yourname/qt-src存放源码包和解压后的源码/home/yourname/qt-buildQt 配置和编译中间产物/opt/Qt-5.14.2-aarch64-staticmake install安装后的 Qt 根目录这样后期如果编译某一步出错可以直接把 build 目录删掉重来不需要重新解压源码。3. 配置与编译最核心的环节全部拆开讲3.1 configure 参数逐项解释在构建目录里执行 configure命令写全了是这样../qt-everywhere-opensource-src-5.14.2/configure \ -prefix /opt/Qt-5.14.2-aarch64-static \ -xplatform linux-aarch64-gnu-g \ -static \ -release \ -opensource \ -confirm-license \ -no-pch \ -no-opengl \ -no-eglfs \ -no-xcb \ -linuxfb \ -no-glib \ -no-iconv \ -no-icu \ -no-dbus \ -no-xkbcommon \ -no-feature-xcb \ -qt-zlib \ -qt-libpng \ -qt-libjpeg \ -qt-freetype \ -qt-pcre \ -skip qtwebengine \ -skip qtwebview \ -skip qtwayland \ -skip qt3d \ -skip qtcharts \ -nomake examples \ -nomake tests \ -nomake tools一行一行看。-prefix指定安装目标目录之后所有交叉工具和库都会装到这里不能随便写因为后续 qmake 生成 Makefile 时会引用这个路径。-xplatform linux-aarch64-gnu-g这是交叉编译的核心参数。Qt 源码自带的 mkspec 里有一套对应 ARM64 平台的定义它在qtbase/mkspecs/linux-aarch64-gnu-g/qmake.conf中会默认使用aarch64-linux-gnu-gcc这套工具链。为什么不直接用-platform因为-platform是指“构建 Qt 本身用的工具链”我们想让 Qt 在 x86 主机上跑构建脚本但生成的库是 aarch64 的所以必须用-xplatform。-static是这次编译的重头戏它告诉 Qt 构建 qmake、核心库和所有编译进去的插件时使用静态库方式。-release去掉调试符号交叉编译本来就慢没必要为 release 版本额外保留一份 debug 库。-opensource -confirm-license自动确认 GPL/LGPL 版本协议避免编译到一半卡在交互确认上。接下来一串-no-是裁剪外部依赖的关键。-no-opengl -no-eglfs因为没有 GL 头文件和厂商闭源 GL 驱动OpenGL 相关模块在交叉环境下是重灾区。如果非要支持 GPU 加速需要厂商提供 libGLESv2.so/EGL/头文件并保留-opengl es2这里先关掉。-no-xcb -no-feature-xcb很多 ARM64 板子根本不跑 X Serverxcb 平台插件依赖一堆 X11 库横竖用不上直接砍掉。-linuxfb则让 Qt 默认使用 Linux framebuffer 平台插件对应/dev/fb0这类设备节点对大多数工控屏和开发板都适用。-no-glib -no-iconv -no-icu -no-dbus -no-xkbcommon依次关掉 glib 事件循环集成、iconv、ICU 字符集、D-Bus 和 xkbcommon 键盘支持。这些是交叉编译时最不稳定的一组依赖能省则省。ICU 通常处理 Qt WebEngine 等巨型模块反正 WebEngine 也跳过了自然不需要。-qt-zlib -qt-libpng -qt-libjpeg -qt-freetype -qt-pcre反过来指定 Qt 使用源码内部版本。这样可以保证所有第三方库跟着 Qt 一起静态编进可执行文件不需要目标板额外安装。最后-skip是跳过整个模块我跳过了 webengine、webview、wayland、3d、charts。QtWebEngine 在交叉编译中基本是噩梦需要 Python、ninja、系统庞大依赖链能跳必跳。-nomake examples -nomake tests -nomake tools则是告诉 Qt 不要编译示例和测试程序降低编译时间和失败概率。3.2 模块裁剪与库依赖策略很多人第一次搞 Qt 交叉编译时会想“既然包都下载了干脆全部编一遍以后要用什么模块都有。”这个想法在 x86 上没问题但在交叉编译上会把自己坑死。QtWebEngine、QtWebView 这种模块不仅编译时间长而且会强制依赖一堆系统库和工具链扩展在 Ubuntu 交叉工具链下经常直接卡死在 ninja 阶段。Qt3D 依赖 OpenGL如果上面把 OpenGL 关了它要么报错要么被自动禁用。QtWayland 是为 Wayland 合成器准备的普通 framebuffer 场景用不到。所以只保留 Qt 基础库尤其是 qtbase是性价比最高的选择。几乎所有 Widgets 程序只依赖 qtbase 里的 QtCore、QtGui、QtWidgets以及可选的 QtNetwork、QtSql这些默认都在 qtbase 里。库依赖策略上必须想清楚一个问题最终的程序要不要连 glibc 一起静态链接。我这里使用的策略是Qt 自身全部静态但 glibc、libstdc 等系统运行时库视目标板情况决定。如果目标板的 glibc 版本和编译机上的交叉库版本差异很大建议在 qmake.conf 或工程 Makefile 里加QMAKE_LFLAGS -static生成完全独立的静态二进制。不过全静态之后如果目标程序需要 DNS 解析可能要用-static-libgcc -static-libstdc而不是激进的全静态避免 glibc 在getaddrinfo等场景下出现 NSS 警告。具体取舍我会在后面的测试环境里再展开一次。3.3 make 与 make install 执行细节configure 正常结束后会生成很多 Makefile然后执行make -j$(nproc)这里注意不要在qt-everywhere-opensource-src-5.14.2源码目录里执行 make而是要在刚才的build-qt-5.14.2-aarch64-static目录里执行。否则会把中间文件和源码混在一起后期想清理很麻烦。编译过程中如果终端刷出来一些 “skip” 或者 “Project ERROR: Unknown module(s) in QT: xxx”只要不是 qtbase 的报错通常可以忽略。真正需要盯住的是qtbase/src/corelib、qtbase/src/gui这些目录里的编译是否全部完成。首次编译大概需要 20 到 40 分钟取决于 CPU 和内存。编译没有致命错误后执行安装make installmake install会把头文件、库文件、mkspec、qmake 工具都复制到/opt/Qt-5.14.2-aarch64-static。安装完检查一下目录结构ls /opt/Qt-5.14.2-aarch64-static/bin ls /opt/Qt-5.14.2-aarch64-static/lib看到qmake和libQt5Core.a、libQt5Widgets.a这类.a文件就说明静态编译成功了。注意/opt目录如果权限不够可以改用sudo make install或者之后再把整个目录chown给自己免得后续 qmake 取文件时遇到权限问题。4. 用 qmake 把手动交叉编译流程固定下来4.1 检查 mkspec 与工具链前缀构建过程中-xplatform linux-aarch64-gnu-g其实已经让 Qt 认为目标平台是 aarch64。安装完成后可以打开${QT_ROOT}/mkspecs/linux-aarch64-gnu-g/qmake.conf看一眼QMAKE_CC aarch64-linux-gnu-gcc QMAKE_CXX aarch64-linux-gnu-g QMAKE_LINK aarch64-linux-gnu-g QMAKE_LINK_SHLIB aarch64-linux-gnu-g如果里面有自定义工具链路径比如/opt/fsl/imx8/bin/aarch64-linux-gnu-gcc就手动改一下。使用 Ubuntu 自带工具链则通常保持默认即可。这一步还容易犯一个错在编译完 Qt 后直接换了一个更阴间的工具链路径结果 qmake 生成 Makefile 时还是引用旧的。解决方式很简单改完 qmake.conf 后重新运行一次 Qt 源码目录下的 configure 并重新 make install。所以最好开始就决定好用哪一套工具链避免中途切换。4.2 工程文件配置交叉编译环境假设我们有这样一个最简单的 Qt Widgets 工程hello_qt/ ├── main.cpp └── hello_qt.promain.cpp写一个标准样例#include QApplication #include QLabel int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label(Hello, aarch64 Qt Static!); label.resize(320, 240); label.show(); return app.exec(); }hello_qt.pro写QT widgets CONFIG static TARGET hello_qt SOURCES main.cpp然后使用安装出来的 Qt qmake 进行构建export PATH/opt/Qt-5.14.2-aarch64-static/bin:$PATH cd hello_qt qmake make这一步会直接生成 aarch64 的 Makefile不需要手动再指定交叉编译器因为 qmake 的 mkspec 已经绑定好了。运行结束后用file看一下产物file hello_qt正常输出应该是hello_qt: ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV), dynamically linked, with debug_info, not stripped如果输出里有statically linked则说明成功了。如果没有说明虽然 Qt 库是静态链接但 glibc 等系统库还是动态依赖这也算一种可运行的中间状态需要继续在 pro 文件里加QMAKE_LFLAGS -static重新 build 后再看。4.3 用交叉编译器直接验证最小链接如果 qmake 方式一时半会没搞利索还可以退回最朴素的命令方式确认工具链本身没问题。写一个纯 C 文件#include iostream int main() { std::cout aarch64 test std::endl; return 0; }然后直接aarch64-linux-gnu-g -o test test.cpp file test输出为 64-bit ARM aarch64就可以确定问题不在工具链而在 Qt 配置或 qmake 环境变量。这个“隔离变量”的习惯在处理交叉编译问题时会大大节约排查时间。5. 静态链接的坑插件、依赖、二进制检查5.1 静态插件处理Q_IMPORT_PLUGIN动态编译的 Qt 程序运行时会通过qt_plugin机制从插件目录里加载平台插件比如libqlinuxfb.so。静态编译后插件不会再从外部.so文件加载需要显式告诉编译器“把这个静态插件给我链接进来”。最简单的办法是在main.cpp中加一句#include QtPlugin Q_IMPORT_PLUGIN(QLinuxFbIntegrationPlugin)具体插件类名由 Qt 源码里的qlinuxfbplugin.cpp决定。对于 linuxfb 平台插件就是QLinuxFbIntegrationPlugin。加入后重新编译make clean make此时linuxfb插件会以目标文件的形式参与链接程序运行就可以通过-platform linuxfb指定使用帧缓冲平台。如果不想在源码里手动写死也可以在.pro文件里用变量控制CONFIG static QTPLUGIN linuxfb不过从我实测经验看Q_IMPORT_PLUGIN更直接不容易出现“qmake 变量没传递到链接命令”的情况。5.2 检查二进制里到底还依赖什么静态链接不代表依赖全都消失特别是系统运行库。我们可以用交叉工具链里的readelf检查动态依赖aarch64-linux-gnu-readelf -d hello_qt | grep NEEDED如果输出只有libc.so.6、libm.so.6、libstdc.so.6、libgcc_s.so.1说明 Qt 库已经是静态的了但系统运行时仍然是动态链接。如果输出为空且file显示 statically linked就是完全独立二进制。对于需要发布到多块同架构但系统版本可能不同的板子最稳妥的做法是在.pro里加上QMAKE_LFLAGS -static强制全静态。不过要注意全静态后如果目标板上的系统调用了 glibc 的 NSS 模块有时候会提示NSS: could not open file ...这种情况常见于使用域名解析的程序。如果程序不需要访问网络直接全静态如果需要 DNS建议不要对自己的 glibc 做全静态保留动态 libc把 Qt 静态就足够了。5.3 二进制体积控制与 strip 处理静态链接最大的问题是体积。一个最简单的 Widgets 程序编译出来可能就有 15MB 到 25MB。去掉调试符号有奇效aarch64-linux-gnu-strip hello_qtstrip 之后很多程序能降到 6MB 到 10MB 左右。对于体积更敏感的场景可以考虑不用 QtWidgets改用 Qt Quick 或者压缩字体但会增加工程量。这里提醒一下Qt 静态库在编译时如果没有去掉无用的模块最终链接时虽然没引用的符号不会被链进 app但 Qt 框架内需要动态注册的插件和类型信息有时候会强制把一些隐含代码拉进来。所以从 configure 阶段开始收敛模块就是为体积控制做铺垫。5.4 目标板上运行与显示验证把hello_qt拷贝到目标板执行chmod x hello_qt ./hello_qt -platform linuxfb如果你的板子使用 HDMI 输出或者 RGB 屏且fb0存在屏幕上会出现一个 320x240 的窗口。如果没有看到可以先确认 framebuffer 节点ls /dev/fb0如果设备节点存在但依然黑屏检查环境变量export QT_QPA_PLATFORMlinuxfb export QT_QPA_FB_DRM1 ./hello_qt不同的内核 DRM 驱动对 framebuffer 的支持略有差异但linuxfb是兼容性最好的兜底方案。真到了需要旋转屏幕、多屏拼接、GPU 加速的阶段再切到 EGLFS/KMS 也不迟。6. 常见问题与排查实录6.1 编译期常见错误对应对策错误现场原因处理办法Could not find qmake spec linux-aarch64-gnu-gQt 源码 mkspec 路径被破坏或工具链配置名不对确认qtbase/mkspecs/linux-aarch64-gnu-g存在没有则从linux-arm-gnueabi-g拷贝一份并改 qmake.confcannot find -lc/cannot find crt1.o缺少 aarch64 glibc 静态库安装libc6-dev-arm64-cross确认/usr/aarch64-linux-gnu/lib/libc.a存在GL/gl.h: No such file or directoryconfigure 里没有彻底关闭 OpenGL检查是否加了-no-opengl -no-eglfs且平台 mkspec 里没有强制QT_CONFIG opengllibEGL.so: cannot open shared object file有模块自动检测 EGL加-no-eglfs并确认EGLFS相关开关关闭Project ERROR: Unknown module(s) in QT: webengineQt 模块之间还有相互引用检查.pro有没有额外引入webengine大多数情况下跳过 webengine 后即可编译到qtbase/src/plugins时出现大量undefined reference to XOpenDisplayxcb 相关代码没有完全裁掉加上-no-xcb -no-feature-xcb必要时编译前先清空 build 目录编译期间最常见的问题是“configure 报了一堆 warning没注意结果 make 到中段才挂”。我的习惯是 configure 结束后立刻执行echo $?返回 0 才继续。不要只看终端末尾有没有 “Qt is now configured for building” 就盲目去 make因为有时候 configure 会以 error 结尾但终端刷屏让人漏看。6.2 运行期常见错误对应对策程序编译好了拷到板子上运行常见的运行期问题更隐蔽。我这里整理了几个最经常遇到的运行现场原因处理办法qt.qpa.plugin: Could not find the Qt platform plugin linuxfb静态编译时没有导入 linuxfb 插件在 main.cpp 里加Q_IMPORT_PLUGIN(QLinuxFbIntegrationPlugin)并确保 Qt configure 时保留了 linuxfbThis plugin does not support propagateSizeHints()某些窗口管理提示不适用 linuxfb可以忽略不影响程序运行libgcc_s.so.1 must be installed for pthread_cancel to work全静态链接与 glibc 线程模型冲突去掉QMAKE_LFLAGS -static让 libgcc 动态链接或加-static-libgccIllegal instruction编译器为特定 CPU 指令集优化目标 CPU 较老执行时加-no-sse之类不适用实际上需要检查 qmake.conf 中的-march降低为通用-marcharmv8-a运行时报段错误无任何输出sysroot glibc 与目标板不匹配或插件有 ABI 问题检查二进制readelf依赖尝试用目标板相同 glibc 的交叉工具链重新编译点击/触摸无反应linuxfb 默认不带 evdev 多点触控校准需要增编libinput或tslib插件并传入-plugin evdevtouch运行期最迷惑的就是Illegal instruction。因为开发主机 CPU 是 x86_64编译出的 aarch64 程序默认使用目标机 CPU 常见指令集但如果目标板是老一点的 Cortex-A53 而工具链开了较高的-marcharmv8.2-a就可能出现非法指令。我在自己调试时会确认目标板cat /proc/cpuinfo的 CPU part 型号然后在 qmake.conf 里不要加激进 march 参数保持默认的armv8-a最稳。6.3 我的一点实战心得上面这些配置参数如果单独拿出来每一条都不难但它们组合起来顺序错了都可能让最终产物不达预期。我自己最大的教训是不要一开始就追求“把所有依赖都静态到极致”而是先以linuxfb 无 xcb 无 opengl 的最小组合跑通一个 hello world。这个最小闭环一旦建立后面再加网络、数据库、多媒体都只是在 configure 参数里逐步加回来不会出现那种“改十处配置也定位不到啥原因”的绝望状态。编译 Qt 静态库并不是一锤子买卖后期如果发现缺了某个模块回到 configure 阶段重新编译也比想象中麻烦所以第一次 configure 前多花十分钟检查参数比之后返工省太多了。尤其是-no-opengl和-no-xcb这两个开关影响了整个编译时依赖树一旦决定后面很难反悔。另外Qt 的.a库在链接时是有严格顺序要求的比如libQt5Widgets.a必须在libQt5Gui.a之前libQt5Gui.a又必须在libQt5Core.a之前。如果手动链接很容易出现undefined reference问题。所以我个人强烈建议用 qmake 或 CMake 生成链接命令不要自己手写aarch64-linux-gnu-g的一大段-lQt5Widgets -lQt5Gui -lQt5Core否则你会被静态库的循环依赖折腾到怀疑人生。最后再分享一个小技巧在构建完 Qt 后可以把整个/opt/Qt-5.14.2-aarch64-static目录打成压缩包备份。下次换一台编译机器、换一个新项目不用重新花几十分钟编 Qt直接解压到相同路径qmake 和.a库就全可用了。交叉工具链只要保持版本一致这套备份方案能省掉大量重复劳动。
