1. 代码开发工具链为什么要在 ARM + UOS 上从源码编译 Qt
在 ARM 架构的 UOS 上搭一套顺手的代码开发工具链,Qt 往往绕不开,但直接拿系统仓库里的预编译包,迟早会撞上三件事:版本被锁死、模块缺斤少两、运行库跟本机架构对不齐。我见过不少在 x86 上跑得好好的工程,搬到 ARM 工控板上就因为 Qt 版本和系统包对不上,链接阶段报一串 undefined reference。从源码编译 Qt 5.15.2,换来的是一套贴合本机架构、模块可裁剪、安装路径可控的开发环境。这篇写的是我实际走通的流程:依赖怎么装、configure 参数怎么取舍、编译怎么落地、踩过的坑长什么样,适合正在 ARM 板子或国产系统上做 Qt 开发、又不想被系统包牵着走的工程师。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 编译地基:ARM 平台依赖库的精准部署
在 ARM 架构的 UOS 上编译 Qt,第一步不是急着拉源码,而是先把编译地基打稳。这一步偷懒,后面 configure 和编译阶段会成倍还回来,而且报错信息往往指向一个八竿子打不着的模块,排查起来很费劲。下面按依赖的层次拆开讲,每一组都说明为什么装、装错会怎样。
2.1 工具链与构建系统先备齐
最基础的编译工具链和构建系统必须先到位,否则 configure 脚本根本跑不起来。cmake 和 ninja 不是必须二选一,Qt 5.15.2 默认用 make,但把 ninja 装上,后续如果改用 Ninja 生成器会快不少:
bash复制sudo apt update
sudo apt install build-essential cmake ninja-build -y
build-essential 是个元包,实际拉进来的是 gcc、g++、make、libc6-dev 这一套,缺了它连最简的 C 程序都编不过。这里有个容易被忽略的点:ARM 平台上要确认装到的是 aarch64 版本的 gcc,而不是某些残留的交叉工具链。可以用 gcc -dumpmachine 看一眼输出,正常应该带 aarch64 字样。如果输出是 x86_64 或某个交叉前缀,说明 PATH 里混进了别的工具链,后面编出来的库架构就全乱了。
cmake 在 Qt 5.15.2 里主要给部分子模块用,ninja-build 属于可选项,但装了不亏。这三样装完,./configure 至少能正常启动,不会一开始就卡在「找不到编译器」上。
2.2 图形栈依赖:XCB 与 OpenGL 的 ARM 版本
Qt 的 GUI 模块在 Linux 下严重依赖 XCB(X 协议的 C 语言绑定)和 OpenGL。在 ARM 平台上,这些库必须是本机 aarch64 版本,不能从 x86 机器上拷 .so 过来用。XCB 的依赖项多且碎,官方给的这套安装命令基本覆盖了 Qt 5.15.2 GUI 所需:
bash复制sudo apt install libgl1-mesa-dev libglu1-mesa-dev \
libxcb1-dev libxcb-*dev \
libx11-xcb-dev libxcb-xinerama0-dev \
libxcb-xkb-dev libxcb-xinput-dev \
libxcb-xfixes0-dev libxcb-render-util0-dev \
libxcb-shape0-dev libxcb-sync-dev \
libxcb-randr0-dev libxcb-icccm4-dev \
libxcb-image0-dev libxcb-keysyms1-dev \
libxkbcommon-dev libxkbcommon-x11-dev -y
libgl1-mesa-dev 和 libglu1-mesa-dev 提供 OpenGL 头文件和链接库;后面一长串 libxcb-* 是 XCB 的各功能扩展,Qt 的窗口系统集成插件会按需链接它们。这里有个必须知道的细节:libxcb-*dev 这个通配写法并不能保证把每个子模块都装上,某些发行版的通配匹配会漏掉个别包。如果 configure 阶段提示缺某个具体 xcb 组件,比如 libxcb-composite0-dev,就按报错里的名字单独补装,别指望通配符一次到位。
提示:XCB 这组库装完之后,建议用
pkg-config --exists xcb && echo ok验证一下,输出 ok 才说明 pkg-config 能正确找到它。Qt 的 configure 内部也依赖 pkg-config 探测这些库。
2.3 字体、数据库、网络与多媒体库
字体和文本渲染是另一块硬依赖。缺了这组库,编出来的 Qt 应用可能显示不了任何文字,或者中文渲染成一堆方块,这种问题在开发阶段不明显,等上了界面才发现就晚了:
bash复制sudo apt install libfontconfig1-dev libfreetype6-dev \
libharfbuzz-dev libfribidi-dev -y
libfreetype6-dev 是字形栅格化的核心,libfontconfig1-dev 负责字体配置和查找,libharfbuzz-dev 做复杂文本整形(阿拉伯语、天城文这类脚本离不开它),libfribidi-dev 处理双向文本。做中文界面时,harfbuzz 和 freetype 的组合决定了汉字能不能正常显示。
数据库和网络模块的依赖看项目需要,但只要打算用 Qt 的 SQL 或 HTTPS,就得把下面这组装上:
bash复制sudo apt install libsqlite3-dev libssl-dev \
libdbus-1-dev libicu-dev -y
libsqlite3-dev 对应 Qt 的 SQLite 驱动,libssl-dev 是网络模块做 TLS 的前提,libdbus-1-dev 支撑进程间通信,libicu-dev 处理国际化编码。这里我一般会把 ICU 一起装上,Qt 的文本编解码在某些 locale 下会依赖它,漏装不一定立刻报错,但到了运行期处理非 ASCII 数据时就可能出问题。
多媒体和传感器模块按项目选装,不做音视频或传感器采集的可以直接跳过:
bash复制# Qt Multimedia 需要
sudo apt install libpulse-dev libasound2-dev \
libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev -y
# Qt Sensors 需要
sudo apt install libudev-dev -y
2.4 架构一致性检查:别让 x86 库混进来
ARM 平台编译最容易翻的车,是依赖库里混进了 x86_64 的版本。这种问题在安装阶段不报错,到了链接阶段才冒出一堆 undefined reference 或者架构不匹配的提示。装完依赖后花两分钟检查一下,能省掉后面半天的排查:
bash复制# 列出某个包安装的库文件路径
dpkg -L libgl1-mesa-dev | grep '\.so'
# 用 file 检查动态库的目标架构,正常应为 ARM aarch64
file /usr/lib/aarch64-linux-gnu/libGL.so.1
dpkg -L <包名> 列出包内所有文件,配合 grep 过滤出 .so 库;file 命令输出里如果看到 ARM aarch64 就对了,看到 x86-64 就说明这个库装错了,需要卸掉重装正确的架构版本。aarch64 的库通常落在 /usr/lib/aarch64-linux-gnu/ 目录下,这也是判断架构的一个直观依据。
Qt 在整个 configure 和编译过程中会反复通过 pkg-config 查找这些库的头文件和链接路径,任何一个库架构不对,configure 的探测结果就会失真,最后要么某个模块被悄悄禁用,要么编到一半链接失败。把这一层查干净,后面的流程才能顺。
3. configure 参数:把 Qt 裁剪成 ARM 平台需要的样子
Qt 的 configure 脚本提供了上百个选项,全部用默认值编出来的东西体积大、模块杂,很多在 ARM 工控板上根本用不上。合理裁剪不仅缩短编译时间,还能避开一堆 ARM 兼容性差的模块。下面这份配置是我在 ARM + UOS 上验证过的,先看脚本再逐项拆。
3.1 安装路径与配置缓存
先定安装路径,原则是不要装进 /usr/local 或系统目录,避免和系统自带的 Qt 打架:
bash复制#!/bin/bash
# 安装到用户目录下,避免污染系统环境,也方便回滚
QT_INSTALL_DIR="$HOME/Qt/5.15.2-arm"
# 清理上一次 configure 留下的缓存,防止旧参数残留
rm -f config.cache
./configure \
-prefix "$QT_INSTALL_DIR" \
-opensource \
-confirm-license \
-release \
-optimize-size \
-c++std c++17 \
-shared \
-system-zlib \
-system-libjpeg \
-system-libpng \
-system-freetype \
-fontconfig \
-sql-sqlite \
-ssl \
-opengl es2 \
-xcb \
-qpa xcb \
-nomake examples \
-nomake tests \
-skip qt3d \
-skip qtcharts \
-skip qtandroidextras \
-skip qtlocation \
-skip qtmacextras \
-skip qtpurchasing \
-skip qtscript \
-skip qtscxml \
-skip qtsensors \
-skip qtserialbus \
-skip qtserialport \
-skip qtwayland \
-skip qtwebchannel \
-skip qtwebengine \
-skip qtwebview \
-skip qtx11extras \
-v
rm -f config.cache 这行不能省。Qt 的 configure 会把上次探测到的库路径、编译选项缓存进 config.cache,改了依赖或换了参数却不清理缓存,configure 可能直接复用旧结果,表现出来的现象就是「明明装了新库,configure 却说找不到」。
-prefix 指定安装目录,配合后面 make install 一步到位。用 $HOME 下的路径,权限干净,卸载时整个目录删掉即可,不留尾巴。
3.2 核心参数逐项解读
把关键参数拉出来对一遍,每个都对应一个实际的取舍:
| 参数 | 作用 | ARM 平台上的考虑 |
|---|---|---|
-prefix "$HOME/Qt/5.15.2-arm" |
指定安装目录 | 避开 /usr/local,防止和系统包冲突 |
-release |
编 release 版 | 开发阶段如需调试符号可改 -debug,但体积会大很多 |
-optimize-size |
优化二进制体积 | ARM 设备存储普遍紧张,这个选项很值 |
-shared |
生成动态库 | 多个应用共享一套 Qt 运行库,省空间 |
-system-zlib 等 |
用系统库 | 减少一份重复编译,前提是系统库版本兼容 |
-fontconfig |
使用 fontconfig 字体配置 | 中文界面环境必须打开 |
-opengl es2 |
使用 OpenGL ES 2.0 | 多数 ARM GPU 只支持 ES,不支持桌面 OpenGL |
-xcb -qpa xcb |
启用 XCB 平台插件 | Linux 桌面环境的标准后端 |
-nomake examples -nomake tests |
不编示例和测试 | 省掉大量编译时间,需要时单独进对应子目录编 |
-skip qtwebengine |
跳过 WebEngine | 基于 Chromium,吃内存且 ARM 兼容性差,强烈建议跳过 |
-opengl es2 是 ARM 平台的关键项。x86 桌面上常见的桌面版 OpenGL 在多数 ARM SoC 的 GPU 上并不完整支持,强行用会编过但运行时黑屏。选 ES2 是贴着硬件来的,编出来的 Qt 才能用上 GPU 加速。
-skip qtwebengine 几乎是必选项。它内嵌整个 Chromium,编译要 16GB 以上内存,而且在 ARM 上存在已知的 libjpeg-turbo 兼容问题,贸然编很容易卡在某个子模块上出不来。项目要用浏览器控件再单独处理,别在一开始就把整个编译流程拖死。
3.3 模块裁剪的取舍:不是跳得越多越好
上面那份 skip 列表看着很爽,但盲目照抄会出问题。-skip qtserialport 和 -skip qtserialbus 这两行,做工业项目的就要特别留意——Qt 的串口通信类 QSerialPort 就在 qtserialport 模块里,跳过了就没有串口能力。如果你的应用要和 RS485 仪表、PLC 打交道,这两行必须删掉。
同理,-skip qtcharts 跳掉的是图表模块,做数据可视化、波形显示的界面会用到它;-skip qtsensors 跳掉传感器框架,做硬件采集的慎删。我一般的做法是:先把确认用不上的模块列出来跳掉,跟业务沾边的一律保留,编完再看哪些模块实际没用到,下一轮再裁。这样虽然多编一两个模块,但不会出现「以为跳掉的是无关模块,结果业务功能编译不过」的翻车。
裁剪的本质是拿编译时间换体积和复杂度,而不是越精简越好。对 ARM 工控板这种存储有限、但业务又可能随时扩展的场景,保留 qtcharts、qtserialport 这类常用模块,比事后重新编一遍划算得多。
4. 从 configure 到 make:开发工具链的编译与安装落地
configure 跑通只是第一步,真正耗时间的是编译。这一步的机器资源、并发数、失败重试策略都直接影响体验,配置不当会把一台好好的开发机拖到卡死。
4.1 编译并发与内存控制
configure 成功后,源码根目录会生成 Makefile,接下来就是 make:
bash复制# 进到源码根目录后执行,-j 的并发数按 CPU 核数和内存综合决定
make -j$(nproc)
$(nproc) 拿到的是当前机器的逻辑核数,直接拿它当并发数在内存充足的机器上没问题。但 Qt 的编译,尤其是 moc、uic 这类元对象处理,单个进程内存占用不低,核数多但内存小的机器(比如 4 核 8G 的工控板)用 -j4 很容易 OOM。稳妥点的做法是先看内存:free -h 看可用内存,一般按每并发 2GB 估算,比如 8G 内存开到 -j3 或 -j4 比较安全。宁可慢一点,也别让编译进程因为内存耗尽被系统 kill,那种「编到 80% 突然全没了」的体验最伤。
如果编译到某个子模块报错,源码目录里每个模块都有自己的 Makefile,可以进到对应子目录单独 make,方便定位和重试,不用整个工程从头再来。
4.2 make install 与目录结构
编译通过后安装到 configure 指定的前缀目录:
bash复制# 安装到 -prefix 指定的目录,此步会把库、头文件、工具链都落地
make install
安装完成后,$HOME/Qt/5.15.2-arm 下会形成标准结构:bin/ 放 qmake、moc、uic 等工具,lib/ 放动态库,include/ 放头文件,plugins/ 放平台插件和图像格式插件。其中 plugins/platforms/libqxcb.so 就是 XCB 平台插件,跑 GUI 程序时 Qt 要从这里加载,位置不对或缺失,程序启动会直接报「could not find or load the Qt platform plugin xcb」。
bin/qmake 是整个工具链的入口,后续所有基于这套 Qt 的编译都通过它定位库和头文件。安装完第一件事是用它查一下版本,确认装的是不是我们要的 5.15.2:
bash复制$HOME/Qt/5.15.2-arm/bin/qmake -v
输出里应该看到 Using Qt version 5.15.2 并带上 aarch64 相关的构建信息,对上就说明这套工具链本身是自洽的。
4.3 环境变量与 Qt Creator 识别
编译安装完,还得让系统和 IDE 认得到这套 Qt。最直接的是把 bin 目录加进 PATH,然后让 Qt Creator 把它注册成一个 Qt Version:
bash复制# 写入当前用户的 shell 配置,注意按实际 shell 选 .bashrc 或 .zshrc
echo 'export PATH="$HOME/Qt/5.15.2-arm/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
环境变量只是让命令行能找到 qmake,Qt Creator 里还要手动添加:打开「工具 → 选项 → Kits → Qt Versions」,点添加,选中 $HOME/Qt/5.15.2-arm/bin/qmake,Qt Creator 会自动探测出版本和编译器。然后在 Kit 里把编译器(gcc/g++)和这个 Qt Version 配到一起,一个可用的构建套件就成型了。
这里有个顺序容易搞反:一定要先添加 Qt Version,再建 Kit。Qt Creator 建 Kit 时下拉框里能选的 Qt 版本,来自已经注册的 Qt Versions 列表,版本没加进去,Kit 里就选不到,会让人误以为安装失败。
5. 踩坑排查:源码编译 Qt 时最常见的五个报错
编译 Qt 这种事,玄学成分不小,但绝大多数报错都能归到有限的几类原因上。下面五条是我这一路上真实碰到的,按「现象 → 原因 → 解决」记下来,照着对能省不少时间。
5.1 现象:configure 报找不到某个 xcb 子模块
原因:2.2 节那套 libxcb-*dev 通配安装漏掉了具体子模块,或者子模块装了但 pkg-config 的 .pc 文件没被识别到。
解决:看 configure 输出里点名的模块,比如缺 libxcb-composite0-dev,就单独补装。装完先 pkg-config --exists xcb-composite 确认能探测到,再回到源码目录 rm -f config.cache 清缓存重新 configure。缓存不清的话,旧探测结果会盖掉新装的库。
5.2 现象:configure 里 OpenGL 相关选项自相矛盾
原因:有些流传的配置脚本同时写了 -opengl es2 和 -no-opengl,这两个语义上互斥,最终生效的只有一个,结果就是明明想用 ES2,编出来却没开 OpenGL。
解决:只保留 -opengl es2,把 -no-opengl 删掉。configure 阶段可以用 -v 看它最终采用的 OpenGL 配置,确认是 ES2 而不是 desktop 或 no。ARM 平台上走 ES2 才是正路。
5.3 现象:链接阶段一串 undefined reference,指向某个系统库
原因:依赖库里混进了 x86_64 版本,链接器在 aarch64 目标下找不到匹配的符号。这种情况常见于手动拷过库文件、或者装过第三方的混合架构包。
解决:按 2.4 节的方法用 file 逐个查可疑的 .so,架构不对的卸掉重装。ldd 也可以用来查某个可执行文件依赖的库路径,确认它链接的是不是 aarch64 目录下的版本。
5.4 现象:编译 qtwebengine 时内存爆掉,进程被 kill
原因:qtwebengine 内嵌 Chromium,单个编译进程内存占用极高,用 -j$(nproc) 并发编译很容易把内存吃光,被 OOM killer 干掉。
解决:最省事的办法是 configure 时 -skip qtwebengine 直接不编。确实需要的话,单独进 qtwebengine 子目录串行编译,并且预留 16GB 以上内存,别和其他模块并发抢内存。
5.5 现象:编译装完,应用编不过,报找不到 QSerialPort
原因:configure 的 skip 列表里照抄了 -skip qtserialport,把串口模块整个跳掉了。
解决:回到 configure 脚本删掉 -skip qtserialport 和 -skip qtserialbus(如果业务涉及串口),清缓存重新 configure 并只补编缺失模块。这也是 3.3 节强调过的:skip 列表要按业务删减,不能无脑照抄。
6. 验证与定制:确认这套开发工具真正可用
编完装完不算完,得用一套小流程验证这套开发工具真的能跑起来,而不是 qmake -v 对了就以为万事大吉。
第一步验版本和模块。除了 qmake -v,再用 qmake 的 query 看安装信息:$HOME/Qt/5.15.2-arm/bin/qmake -query,重点看 QT_INSTALL_PREFIX、QT_INSTALL_LIBS、QT_INSTALL_PLUGINS 三个路径是否都指向你指定的目录。如果某个路径还指向系统目录,说明环境里有另一套 Qt 在干扰,需要清理 PATH 或卸载系统 Qt。
第二步写个最小 GUI 程序验证平台插件。一个只弹空窗口的 main.cpp 就够:
cpp复制#include <QApplication>
#include <QWidget>
int main(int argc, char *argv[]) {
QApplication app(argc, argv);
QWidget w;
w.resize(320, 240);
w.setWindowTitle("arm-qt-check");
w.show();
return app.exec();
}
配一个最简 pro 文件:QT += widgets 加 SOURCES += main.cpp,用刚装好的 qmake 走一遍 qmake && make。程序能编译、能在桌面环境里弹窗,说明库、平台插件、字体渲染这条链路是通的。如果弹窗失败报平台插件 xcb 找不到,回头查 plugins/platforms/ 下有没有 libqxcb.so,以及 QT_PLUGIN_PATH 有没有被别的路径污染。
第三步才是进 Qt Creator 建 Kit、跑一个带界面的小工程,确认 IDE 层面也没问题。这三步走完,一套从源码编出来的 ARM + UOS Qt 开发工具链才算真正落地。
血泪经验是:每次重编或换机器,我都强制从「qmake -query 路径检查 → 最小 GUI 程序弹出窗口」走一遍,绝不因为「上次是好的」就跳过。Qt 的坑大多藏在路径和插件这种看不见的地方,黑匣子不打开看一眼,等到业务代码编不过再回头查,后悔药可没处买。希望帮到你。
