简介本资源面向在国产化平台上进行桌面或嵌入式应用开发的工程师提供在 Kylin-Server-10-SP2-Release-Build09-20210524-arm64 系统上编译完成的 Qt 5.12.8 头文件集合可解决 ARM64 架构下麒麟系统缺少匹配 Qt 开发头文件、难以直接编译 Qt 程序的问题。压缩包为 gz 格式共约 2000 个文件全部为 .h 头文件整体约 65.91MB涵盖 QtCore、QtGui、QtOpenGL、QtNetwork 等模块的公开接口声明以及 qopenglextensions、qopenglfunctions 系列 OpenGL 兼容层头文件便于开发者直接引用或对照排查编译依赖。目前已有 251 人学习下载适合需要快速搭建 Qt 交叉编译环境、核对 API 声明或补齐头文件依赖的开发者参考使用。1. 麒麟系统上把 Qt 5.12.8 从源码啃下来为什么值得折腾在一台国产 ARM 服务器上系统装的是 Kylin-Server-10-SP2-Release-Build09-20210524-arm64自带软件源里的 Qt 版本要么太老、要么缺模块而业务代码又必须锁死在 Qt 5.12.8 这个 LTS 版本上。这时候你只有两条路要么改业务代码去迁就系统源要么自己从源码把 Qt 5.12.8 编出来。我选后者因为改代码的成本远高于一次编译。这篇笔记讲的就是在 aarch64 架构的麒麟服务器上从零把 Qt 5.12.8 编译出来并跑通一个最小 GUI 程序的全过程包括依赖怎么装、configure 参数怎么配、编译报错怎么查、装完之后环境变量怎么设。适合手里有 ARM 服务器、需要在国产化平台上做 Qt 桌面或嵌入式开发的人也适合第一次在非 x86 架构上编大型 C 框架、想少走弯路的同行。整个过程最耗时的不是敲命令而是踩依赖和架构的坑下面把每一步都摊开讲。2. 编译前的环境盘点与依赖准备别让缺库毁掉三小时2.1 先确认系统底子别急着解压源码动手之前先花五分钟把系统信息摸清楚这一步能省掉后面大量「编译到一半报错」的时间。Kylin-Server-10-SP2 基于较新的内核和 glibcaarch64 架构下很多 x86 上的经验会失效所以先确认三件事CPU 架构、glibc 版本、GCC 版本。Qt 5.12.8 对 GCC 的要求是 5.3 以上麒麟自带的 GCC 一般能满足但 glibc 太新有时反而会让老版本 Qt 的某些检测脚本出问题。# 确认架构必须是 aarch64 uname -m # 查看系统发行版信息 cat /etc/os-release # 查看 glibc 版本Qt 5.12.8 建议 2.17 以上 ldd --version | head -n 1 # 查看 GCC 版本需要 5.3 gcc --version | head -n 1 # 查看 CPU 核心数决定后面 make -j 的并行度 nproc这几条命令的输出要记下来。nproc的结果直接决定后面make -j后面跟几核多就并行高一点核少就老老实实单线程否则内存会被打爆。我一般留一到两个核给系统比如 8 核就用-j6。另外确认磁盘空间Qt 源码解压后加上编译中间产物轻松吃掉 20GB 以上df -h看一眼根分区和你要放源码的分区。2.2 依赖包一次装齐别等报错再补Qt 的依赖分两类编译工具链和功能模块依赖。工具链包括 make、g、perl、python部分脚本用、pkg-config。功能模块依赖则取决于你要启用哪些 Qt 模块比如要 GUI 就得有 X11 或 OpenGL 相关开发库要网络就得有 OpenSSL 开发库。麒麟的包管理用的是 yum/dnf 体系下面这组依赖是我在 aarch64 上实测能覆盖绝大多数模块的清单。# 基础编译工具链 sudo yum install -y gcc gcc-c make perl python3 pkgconfig # X11 与 OpenGL 相关GUI 模块必需 sudo yum install -y libX11-devel libXext-devel libXrender-devel \ libXtst-devel libXi-devel mesa-libGL-devel mesa-libGLU-devel # 字体与图形库 sudo yum install -y fontconfig-devel freetype-devel libpng-devel \ libjpeg-turbo-devel zlib-devel # 网络与安全 sudo yum install -y openssl-devel # 多媒体与数据库按需不用可省 sudo yum install -y alsa-lib-devel libsqlite3x-devel装完依赖后建议用rpm -qa | grep devel扫一眼确认关键库都在。这里有个血泪经验aarch64 上某些-devel包的命名和 x86 不完全一致比如有的系统里 OpenGL 开发包叫mesa-libGL-devel有的叫libGL-devel装不上就yum search找一下实际包名。依赖没装齐configure 阶段会直接告诉你缺哪个但有些是编译到一半才暴露所以宁可一次装全。2.3 源码获取与目录规划Qt 5.12.8 的源码包是单个大压缩包解压后是一个qt-everywhere-src-5.12.8目录。我习惯把源码放在/opt/src下编译产物和安装目录分开方便以后清理或重编。安装目录我选/opt/Qt5.12.8不装到系统默认路径避免和系统自带的 Qt 冲突也方便多版本共存。# 创建源码和安装目录 sudo mkdir -p /opt/src /opt/Qt5.12.8 # 把源码包放到 /opt/src 后解压 cd /opt/src tar -xf qt-everywhere-src-5.12.8.tar.xz # 进入源码目录 cd qt-everywhere-src-5.12.8解压后先别急着 configure看一眼顶层目录结构确认configure脚本存在。Qt 5.12 用的是老式 configure 脚本不是 CMake所以参数写法是-prefix、-opensource这种风格。目录规划清楚之后后面出问题要重来直接删掉 build 目录重配即可不用重新解压源码。3. configure 参数怎么配一次配对少编两小时3.1 关键参数逐条拆解configure 是整场编译里最需要动脑的一步参数配错要么编出来的库缺功能要么直接编不过。Qt 5.12.8 的 configure 参数很多但在 aarch64 麒麟服务器上真正需要你操心的就那么几个。下面这条是我实际用的命令先贴出来再逐条解释。./configure -prefix /opt/Qt5.12.8 \ -opensource -confirm-license \ -release \ -nomake examples -nomake tests \ -no-openssl \ -skip qtwebengine \ -qt-zlib -qt-libpng -qt-libjpeg -qt-freetype \ -xcb \ -platform linux-g-prefix指定安装路径必须和前面创建的目录一致。-opensource -confirm-license表示使用开源协议并自动确认不加会卡在交互式提问。-release只编发布版不编调试版能省将近一半时间和磁盘。-nomake examples -nomake tests跳过示例和测试除非你要研究示例代码否则没必要编。-no-openssl是因为麒麟自带的 OpenSSL 版本和 Qt 5.12.8 的检测逻辑有时对不上直接禁用需要网络加密时再单独处理。-skip qtwebengine很关键QtWebEngine 在 aarch64 上编译极其耗时且依赖 Chromium 那一套除非业务必须用浏览器控件否则一定跳过。-qt-zlib -qt-libpng -qt-libjpeg -qt-freetype表示用 Qt 自带的第三方库避免和系统库版本打架这在国产系统上尤其省心。-xcb启用 X11 后端服务器上如果要跑 GUI 程序需要它。-platform linux-g明确指定平台aarch64 上一般能自动识别但写死更稳。3.2 参数取舍背后的判断逻辑上面这些参数不是拍脑袋定的每一条都对应一个实际约束。比如-no-openssl很多人第一反应是「网络模块不要加密了」其实不是Qt 的网络模块本身能用只是不链接系统 OpenSSL等你真需要 HTTPS 时可以单独编一个匹配的 OpenSSL 再重新 configure Qt 的 network 模块或者用运行时动态加载的方式。在麒麟这种系统库版本和上游不完全同步的环境里先禁用再按需补比一开始就硬链要稳。再比如-qt-zlib这一组本质是让 Qt 用自己源码树里带的 zlib、libpng 等而不是去链系统的-devel包。好处是版本可控不会因为系统库升级导致 Qt 运行时报符号找不到代价是编译时间略长、产物体积略大。在国产化平台上可控性比省那点空间重要得多。-skip qtwebengine则是纯粹的性价比判断这个模块编译动辄几小时依赖 Node.js、Chromium 一堆东西aarch64 上还容易挂除非明确要做内嵌浏览器否则跳过是理性选择。3.3 configure 通过后的自检configure 跑完会输出一份摘要列出哪些模块启用、哪些跳过、哪些因为缺依赖被禁用。这份摘要必须逐行看尤其是「These modules are disabled」那一段。如果发现你需要的模块被禁用了比如qtmultimedia因为缺 ALSA 被关掉那就回去补依赖再重新 configure。configure 本身不编译重跑成本很低但一旦开始 make 再发现模块缺失就得从头再来。# configure 完成后把摘要存一份方便对比 ./configure -prefix /opt/Qt5.12.8 -opensource -confirm-license \ -release -nomake examples -nomake tests -no-openssl \ -skip qtwebengine -qt-zlib -qt-libpng -qt-libjpeg -qt-freetype \ -xcb -platform linux-g 21 | tee /tmp/qt_configure.log # 检查被禁用的模块 grep -A 20 disabled /tmp/qt_configure.log摘要里还会告诉你用的是哪个编译器、哪个 C 标准。Qt 5.12.8 默认用 C11如果系统 GCC 默认标准更高一般也能兼容但遇到奇怪的模板报错时可以加-cstd c11强制指定。确认摘要没问题就可以进入编译阶段了。4. 编译与安装并行度、内存和报错排查4.1 make 并行度与内存的平衡编译 Qt 是个体力活aarch64 服务器核数通常不少但内存不一定跟得上。make -j的并行度不是越高越好每个编译单元尤其是 C 模板重的模块可能吃掉几百 MB 到 1GB 内存核多内存小的话并行一高就触发 OOM编译进程被系统杀掉报错信息还很不直观。我的经验是内存 16GB 以下-j不超过核数的一半32GB 以上可以接近核数。# 假设 8 核 16GB 内存用 -j4 比较稳 make -j4 21 | tee /tmp/qt_make.log # 如果中途报错日志里搜 Error 定位 grep -n Error /tmp/qt_make.log | head编译时间取决于核数和跳过的模块aarch64 上 8 核大概两到四小时具体看机器。建议挂tee把日志存下来一是方便出错回溯二是万一终端断了还能看进度。如果编译中途因为内存被杀dmesg | tail能看到 OOM killer 的记录这时候降低-j重来即可已经编好的目标文件不会丢make 会接着编。4.2 典型报错的定位思路aarch64 上编 Qt 5.12.8 最常见的报错有三类。第一类是缺头文件或库报错里会明确写fatal error: xxx.h: No such file or directory对应去装那个-devel包。第二类是链接错误undefined reference to xxx通常是某个功能库没链上回去检查 configure 摘要里对应模块是否启用。第三类是编译器内部错误或段错误这种最玄学往往是并行编译时内存不足或某个模块的代码在 aarch64 上有对齐问题降低并行度或单独进那个模块目录make往往能过。# 单独进某个出问题的模块目录编译方便看详细报错 cd qtbase make -j1 21 | tee /tmp/qtbase_make.log # 如果是链接错误看具体缺哪个符号 grep undefined reference /tmp/qtbase_make.log | head单独编某个模块时注意它依赖的其他模块可能还没编完所以一般是在整体 make 失败后定位到具体模块再进去单编。单编通过后回到顶层再make一次它会跳过已完成的继续往下走。4.3 安装与目录结构确认编译全部通过后make install把产物装到-prefix指定的目录。安装过程一般不会出错但装完要确认目录结构对不对。Qt 5.12.8 装完后/opt/Qt5.12.8下应该有bin、lib、include、plugins、mkspecs等目录bin里能看到qmake、moc、uic这些工具。# 安装 sudo make install 21 | tee /tmp/qt_install.log # 确认 qmake 存在且可执行 /opt/Qt5.12.8/bin/qmake -v # 查看安装目录大小确认没有明显缺失 du -sh /opt/Qt5.12.8qmake -v的输出会显示 Qt 版本和安装路径如果显示的是 5.12.8 且路径正确说明安装成功。如果显示的是系统自带的 qmake说明环境变量还没配下一步处理。5. 环境变量与最小验证程序编完不算完跑起来才算5.1 环境变量怎么设才不污染系统装完 Qt 后要让编译和运行都能找到它需要设几个环境变量。最省事的做法是写一个脚本用的时候 source 一下而不是直接写进/etc/profile全局污染。核心变量是PATH加 qmake 路径、LD_LIBRARY_PATH加 Qt 库路径、PKG_CONFIG_PATH加 pkgconfig 路径。# 保存为 /opt/Qt5.12.8/qt_env.sh export QT_DIR/opt/Qt5.12.8 export PATH$QT_DIR/bin:$PATH export LD_LIBRARY_PATH$QT_DIR/lib:$LD_LIBRARY_PATH export PKG_CONFIG_PATH$QT_DIR/lib/pkgconfig:$PKG_CONFIG_PATH # 使用时 source 一下 source /opt/Qt5.12.8/qt_env.sh # 验证 qmake 指向正确 which qmake qmake -vLD_LIBRARY_PATH这一条在运行时很关键否则程序启动会报找不到libQt5Core.so.5。但要注意LD_LIBRARY_PATH设太宽可能影响系统其他程序所以只在开发终端里 source不要全局设。如果要做成系统级更规范的做法是在/etc/ld.so.conf.d/下加一个 conf 文件再ldconfig但那样会影响所有程序我一般不用。5.2 一个最小 GUI 程序验证全链路验证 Qt 是否真正可用最直接的办法是编一个最小 GUI 程序。下面这个例子创建一个窗口标题显示 Qt 版本能编过、能弹出窗口就说明编译、安装、环境变量、X11 后端这一整条链路都通了。// main.cpp #include QApplication #include QLabel #include QString int main(int argc, char *argv[]) { QApplication app(argc, argv); // 显示当前 Qt 版本验证链接的是我们编的库 QString ver QString(Qt version: %1).arg(QT_VERSION_STR); QLabel label(ver); label.setWindowTitle(Qt on Kylin ARM64); label.resize(320, 120); label.show(); return app.exec(); }配套的工程文件test.pro只需要三行QT widgets SOURCES main.cpp TARGET qt_verify编译和运行# 确保已 source 环境变量 source /opt/Qt5.12.8/qt_env.sh # 生成 Makefile 并编译 qmake test.pro make # 运行需要当前有 X11 显示环境 ./qt_verify如果程序能弹出窗口并显示版本号说明整条链路打通。如果报cannot connect to X server说明当前终端没有图形显示环境用ssh -X或直接在服务器本地桌面跑。如果报找不到库检查LD_LIBRARY_PATH是否生效。5.3 无图形环境下的替代验证服务器很多时候没有图形界面这时候 GUI 程序跑不起来不代表 Qt 编坏了。可以用一个纯控制台的 Qt 程序验证核心库只链接QtCore打印版本和平台信息。// console_test.cpp #include QCoreApplication #include QString #include QDebug int main(int argc, char *argv[]) { QCoreApplication app(argc, argv); qDebug() Qt version: QT_VERSION_STR; qDebug() Build platform: QSysInfo::buildCpuArchitecture(); return 0; }工程文件把QT widgets换成QT core编译运行后能看到版本和架构输出就说明 QtCore 没问题。GUI 部分等有显示环境时再验证。这种分步验证的思路在排查「到底是 Qt 编坏了还是环境没配好」时特别有用。6. 避坑与排查aarch64 上编 Qt 最容易翻车的五件事6.1 坑一configure 报找不到 OpenGL 库现象是 configure 阶段提示OpenGL functionality tests failed或者摘要里qtgui被禁用。原因通常是mesa-libGL-devel没装或者装了但 pkg-config 找不到。解决是先确认包在不在rpm -qa | grep -i mesa不在就装装了还报错检查PKG_CONFIG_PATH是否包含系统默认路径必要时手动指定-I和-L参数指向 GL 头文件和库目录。6.2 坑二make 到一半被 Killed现象是编译进程突然消失日志里没有 Error只有Killed。原因是内存不足OOM killer 把编译进程杀了。解决是降低make -j的并行度或者加 swap。free -h看内存和 swap 使用情况dmesg | grep -i oom确认是 OOM。aarch64 服务器内存配置差异大别照搬 x86 上的-j经验。6.3 坑三链接时报 undefined reference 到某个 Qt 模块现象是编业务程序时链接失败提示找不到libQt5Xxx.so里的符号。原因是 configure 时那个模块被禁用了或者安装后LD_LIBRARY_PATH没包含 Qt 库路径。解决是先看/opt/Qt5.12.8/lib下有没有对应的.so文件没有就回去补依赖重新 configure 和 make有的话检查环境变量和.pro文件里的QT 是否写对。6.4 坑四qmake 生成 Makefile 时找不到 mkspecs现象是运行 qmake 报Could not find qmake configuration file或类似错误。原因是mkspecs目录没装全或者QMAKESPEC环境变量指向了错误位置。解决是确认/opt/Qt5.12.8/mkspecs存在且里面有linux-g等目录然后unset QMAKESPEC让 qmake 用内置默认值或者显式export QMAKESPEC/opt/Qt5.12.8/mkspecs/linux-g。6.5 坑五程序运行时报 xcb 插件加载失败现象是 GUI 程序启动时报This application failed to start because no Qt platform plugin could be initialized或者明确说xcb插件找不到。原因是 Qt 的插件路径没被正确识别或者libxcb相关库缺失。解决是设export QT_DEBUG_PLUGINS1看插件加载详细日志确认/opt/Qt5.12.8/plugins/platforms/libqxcb.so存在并用ldd检查它依赖的 xcb 库是否都能找到。缺库就补装对应的libxcb-*-devel或运行时包。7. 进阶技巧把编译产物做成可复用的开发环境7.1 用 qmake 的 cache 加速后续项目配置Qt 编好之后每次新建项目都手动 source 环境变量有点烦。可以在项目根目录放一个.qmake.cache或者在qmake命令里用-cache参数把 Qt 安装路径、编译器选项缓存下来。更实用的做法是写一个qt_env.sh放在项目里团队成员 clone 下来 source 一下就能用路径用相对或环境变量推导避免硬编码。# 项目内 qt_env.sh自动推导 Qt 路径 QT_DIR${QT_DIR:-/opt/Qt5.12.8} if [ ! -x $QT_DIR/bin/qmake ]; then echo Qt not found at $QT_DIR, please set QT_DIR return 1 fi export PATH$QT_DIR/bin:$PATH export LD_LIBRARY_PATH$QT_DIR/lib:$LD_LIBRARY_PATH echo Qt environment ready: $($QT_DIR/bin/qmake -v | tail -n 1)这个脚本的好处是路径可覆盖换机器或换安装目录时不用改脚本内容QT_DIR/other/path source qt_env.sh即可。7.2 交叉编译与本地编译的边界判断有人会问能不能在 x86 机器上交叉编译出 aarch64 的 Qt再拷到麒麟服务器上用。技术上可行但我不推荐在项目初期这么做。交叉编译需要一套完整的 aarch64 工具链和 sysroot配置复杂度远高于本地编译而且一旦 sysroot 里的库版本和实际服务器不一致运行时会出各种玄学问题。本地编译虽然慢但产物和运行环境天然一致省去大量排查时间。等本地编译跑通、环境稳定后再考虑用容器或交叉编译做 CI 加速那才是合理的顺序。7.3 验证编译产物完整性的一个习惯每次编完 Qt我都会跑一个「模块清单核对」把 configure 摘要里启用的模块列出来逐个检查/opt/Qt5.12.8/lib下有没有对应的.so再用qmake -query看关键路径。这个习惯帮我提前发现过好几次「某个模块其实没编进去」的问题避免等到业务程序链接时才暴露。# 列出所有 Qt 库和 configure 摘要对比 ls /opt/Qt5.12.8/lib/libQt5*.so | sed s#.*/lib##; s#\.so$## | sort # 查看 qmake 记录的关键路径 /opt/Qt5.12.8/bin/qmake -queryqmake -query会输出QT_INSTALL_PREFIX、QT_INSTALL_LIBS、QT_INSTALL_HEADERS等确认这些路径都指向/opt/Qt5.12.8而不是系统路径。如果指向系统路径说明环境变量或 qmake 本身有问题得回头查。我自己在 aarch64 上编 Qt 最大的教训是别信「应该没问题」每一步都验证。依赖装完验证一遍configure 完看摘要make 完看库文件装完跑最小程序。这套流程看起来啰嗦但比编到一半推倒重来省时间得多。希望帮到你。本文还有配套的精品资源点击获取