麒麟arm64源码编译Qt 5.12.8实战与避坑指南

简介本资源面向在国产化平台进行桌面或嵌入式应用开发的工程师提供在 Kylin-Server-10-SP2-Release-Build09-20210524 的 arm64 架构上编译完成的 Qt 5.12.8 头文件集合可解决麒麟系统下 Qt 开发环境搭建与头文件缺失、版本不匹配等常见问题。压缩包为 gz 格式共约 2000 个文件全部为 .h 头文件整体约 65.91MB涵盖 QLocale、QOpenGL 系列函数、Valgrind 调试支持、QUrl 顶级域名等模块的声明便于在交叉编译或本地构建时直接引用。目前已有 251 人学习下载适合需要快速补齐 Qt 头文件依赖、对照源码排查编译错误的开发者参考使用。1. 麒麟系统上把 Qt 5.12.8 从源码啃下来为什么值得折腾在 Kylin-Server-10-SP2-Release-Build09-20210524-arm64 这套国产化服务器环境里系统自带的 Qt 版本往往停在 5.6 或 5.9 附近而不少工业上位机、组态软件、串口调试工具偏偏要求 5.12.8 这个 LTS 版本。直接apt install qt5-default拿到的要么版本对不上要么缺qtmqtt、qscintilla这类扩展模块最后只能走源码编译这条路。arm64 平台和 x86 最大的区别在于官方预编译包基本不覆盖麒麟的库路径和 GCC 版本交叉编译又容易在qmake阶段就翻车所以本地原生编译反而是最稳的选择。这篇笔记面向的是手里已经有一台麒麟 arm64 服务器、需要把 Qt 5.12.8 完整跑起来的嵌入式或桌面应用开发者从依赖准备一路讲到模块裁剪和验证中间踩过的坑都会标出来。2. 编译前的依赖清单与工具链核对2.1 先确认系统里到底有什么麒麟 SP2 基于较新的 glibc但默认安装的编译工具往往不完整。第一步不是急着下源码而是把家底摸清楚。执行下面几条命令把 GCC、G、make、Python 的版本记下来后面配置阶段会反复用到。# 查看系统版本与架构确认是 aarch64 而非 x86_64 cat /etc/kylin-release uname -m # 核对编译器版本Qt 5.12.8 建议 GCC 7.3 及以上 gcc --version g --version make --version # 查看 Python 位置Qt 的 configure 脚本依赖 python2 或 python3 which python3 python3 --version逻辑说明uname -m返回aarch64才说明是真正的 arm64 环境如果返回x86_64说明你连错机器了。GCC 版本低于 7.3 时Qt 的 C11 特性支持会出问题典型表现是编译qbytearray相关文件时报std::atomic找不到。Python 这块要注意Qt 5.12.8 的configure脚本对 Python 3 的支持是半吊子如果系统里只有 Python 3.10 以上建议额外装一个python3.8或直接用-no-feature-python跳过。2.2 一次性补齐开发库麒麟的软件源里包名和 CentOS、Ubuntu 都有差异下面这份清单是我在 SP2 上实测能装齐的。缺任何一个都可能在configure或make中途报错与其编译到一半再补不如一次装完。# 基础编译工具 sudo yum install -y gcc gcc-c make cmake perl python3-devel # X11 与 OpenGL 相关Qt Widgets 和 Qt Quick 都依赖 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 libtiff-devel # 音频与多媒体编译 QtMultimedia 时需要 sudo yum install -y alsa-lib-devel pulseaudio-libs-devel # 数据库驱动QtSql 模块依赖 sudo yum install -y sqlite-devel postgresql-devel mysql-devel # 网络与安全 sudo yum install -y openssl-devel libcurl-devel参数说明mesa-libGL-devel提供 OpenGL 头文件缺了会在编译qtbase/src/gui/opengl时报GL/gl.h: No such file。libXtst-devel是 XTest 扩展Qt 的自动化测试模块需要它。sqlite-devel建议必装因为 Qt 自带的 SQLite 插件在麒麟上默认走系统库不装的话QSqlDatabase会提示驱动未加载。如果这台机器不接显示器、只做后台服务可以省掉 X11 那一组但configure时要加-no-xcb否则一样会去找 X11 头文件。提示麒麟 SP2 的 yum 源里mysql-devel可能叫mariadb-devel装之前先yum search一下别硬套包名。3. 源码获取、configure 参数与模块裁剪3.1 源码包怎么拿、放哪Qt 5.12.8 的源码有两种拿法一是从官方归档站下single包二是用git拉5.12.8分支再初始化子模块。arm64 上我推荐用 single 包省去子模块同步的麻烦。下载后解压到一个路径不含中文和空格的目录比如/opt/qt-src。# 创建源码目录并进入 sudo mkdir -p /opt/qt-src cd /opt/qt-src # 假设源码包已放到当前目录解压 tar -xf qt-everywhere-src-5.12.8.tar.xz # 进入解压后的目录 cd qt-everywhere-src-5.12.8逻辑说明qt-everywhere-src是包含所有模块的完整包解压后大约 5GB 左右。不要放在/root下因为编译过程中会产生大量中间文件/root分区通常较小容易撑爆。解压后先别急着 configure用ls看一眼目录结构确认qtbase、qtdeclarative、qtmultimedia这些子目录都在。3.2 configure 参数逐条拆解configure 是整个编译过程中最容易翻车的一步。参数写多了编译不过写少了功能缺失。下面这份是我在麒麟 arm64 上验证过的配置兼顾了桌面应用和串口通信需求。# 在源码根目录执行 ./configure -prefix /opt/Qt5.12.8 \ -opensource -confirm-license \ -release -shared \ -platform linux-g \ -nomake examples -nomake tests \ -no-openssl \ -qt-zlib -qt-libpng -qt-libjpeg \ -qt-sqlite \ -skip qtwebengine \ -skip qtwebview \ -skip qtlocation \ -skip qtsensors \ -skip qtgamepad \ -skip qtserialbus \ -skip qtwayland \ -v参数说明-prefix指定安装路径建议单独放一个目录方便后续打包。-opensource -confirm-license是开源版必须的少了会交互式询问。-release -shared生成动态库如果要做静态部署改成-static但静态编译在 arm64 上对 OpenSSL 依赖处理很麻烦不建议新手碰。-nomake examples -nomake tests能省掉至少 30% 的编译时间examples 里有些模块的示例代码在 arm64 上本身就有编译错误。-no-openssl是因为麒麟自带的 OpenSSL 版本和 Qt 5.12.8 的兼容层有冲突如果确实需要 HTTPS建议单独编译 OpenSSL 1.1.1 再用-openssl-linked指定路径。-qt-zlib -qt-libpng -qt-libjpeg表示用 Qt 自带的第三方库避免和系统库版本打架。-skip那几个模块要么体积巨大qtwebengine 在 arm64 上编译要几个小时要么在服务器场景根本用不上。注意-skip qtwebengine是必须的这个模块在 arm64 上需要 Chromium 的交叉编译支持麒麟环境基本编不过去硬编只会浪费时间。3.3 模块裁剪的取舍逻辑不是所有项目都需要完整 Qt。如果你的应用只用到 Widgets 和 Network可以把qtdeclarative、qtquickcontrols也 skip 掉编译时间能从两小时压到四十分钟。但要注意qtmqtt和qscintilla这两个热搜里常出现的模块并不在qt-everywhere包里它们是独立项目需要单独编译。qtmqtt依赖qtbase的QtNetwork所以qtbase必须完整编译。qscintilla则依赖QtWidgets和QtPrintSupport裁剪时别把qtbase里的打印支持关了。# 如果只需要核心模块可以用更精简的配置 ./configure -prefix /opt/Qt5.12.8-mini \ -opensource -confirm-license \ -release -shared \ -nomake examples -nomake tests \ -no-openssl \ -qt-zlib -qt-libpng -qt-libjpeg \ -skip qtdeclarative \ -skip qtmultimedia \ -skip qtwebengine \ -skip qtlocation \ -skip qtsensors \ -skip qtgamepad \ -skip qtserialbus \ -skip qtwayland \ -skip qtquickcontrols \ -skip qtquickcontrols2 \ -v逻辑说明这份配置只保留qtbase、qtsvg、qttools等基础模块适合纯 Widgets 应用。-skip qtdeclarative会连带跳过 QML 相关的一切如果后续想加 QML 界面就得重新编译。建议第一次编译时保留qtdeclarative哪怕不用后面想加也方便。4. 编译、安装与 qtmqtt/qscintilla 扩展模块4.1 make 阶段的并行度与内存控制configure 通过后make的并行度设置直接影响编译速度和成功率。arm64 服务器通常核数不多盲目-j拉满会导致内存溢出典型报错是g: internal compiler error: Killed。# 查看 CPU 核数和内存 nproc free -h # 根据内存决定并行度一般每核 2GB 内存 # 假设 8 核 16GB 内存用 -j8 make -j8 21 | tee build.log # 如果中途报错单独重试出错模块不要从头再来 make -j4 21 | tee build_retry.log逻辑说明tee build.log把编译输出同时写到文件和终端方便出错后回溯。如果make -j8跑到一半被 Killed降到-j4再跑make 会自动跳过已编译成功的文件。internal compiler error不一定是代码问题九成是内存不够。编译qtdeclarative时单个进程峰值能到 2GB 以上16GB 内存的机器建议-j6保守一点。4.2 安装与环境变量配置编译完成后执行make install然后配置环境变量让系统能找到新装的 Qt。# 安装到 configure 时指定的 prefix sudo make install # 配置环境变量写入 /etc/profile.d/qt5.sh sudo tee /etc/profile.d/qt5.sh EOF export QTDIR/opt/Qt5.12.8 export PATH$QTDIR/bin:$PATH export LD_LIBRARY_PATH$QTDIR/lib:$LD_LIBRARY_PATH export QT_PLUGIN_PATH$QTDIR/plugins export QML2_IMPORT_PATH$QTDIR/qml EOF # 使环境变量生效 source /etc/profile.d/qt5.sh # 验证 qmake 版本 qmake -v参数说明QTDIR是 Qt 的根目录很多第三方项目的.pro文件会引用这个变量。LD_LIBRARY_PATH让运行时能找到libQt5Core.so.5等动态库。QT_PLUGIN_PATH是插件路径缺了会导致QSqlDatabase找不到驱动、QJpegPlugin加载失败。QML2_IMPORT_PATH是 QML 模块路径不用 QML 可以不加。qmake -v输出里应该显示Using Qt version 5.12.8如果显示的是系统旧版本说明 PATH 顺序不对。4.3 单独编译 qtmqtt 与 qscintillaqtmqtt和qscintilla不在主包里需要单独拉源码编译。这两个模块在工业上位机和代码编辑器场景里出现频率很高热搜里也常有人问。# 编译 qtmqtt cd /opt/qt-src git clone -b 5.12.8 https://code.qt.io/qt/qtmqtt.git cd qtmqtt /opt/Qt5.12.8/bin/qmake make -j4 sudo make install # 编译 qscintilla cd /opt/qt-src # 假设已下载 QScintilla 源码包并解压 cd QScintilla-2.11.6/Qt4Qt5 /opt/Qt5.12.8/bin/qmake qscintilla.pro make -j4 sudo make install逻辑说明qtmqtt的qmake必须用新编译的 Qt 5.12.8 里的不能用系统自带的否则会链接到旧版本库。qscintilla的.pro文件在Qt4Qt5目录下虽然名字叫 Qt4Qt5但兼容 Qt5。编译完成后qtmqtt的头文件会装到/opt/Qt5.12.8/include/QtMqtt库文件在/opt/Qt5.12.8/lib。qscintilla装完后需要在项目的.pro里加LIBS -lqscintilla2_qt5才能链接。提示qscintilla编译时如果报undefined reference to QPrinter说明qtbase的QtPrintSupport没编进去回头检查 configure 时有没有误加-no-printsupport。5. 避坑排查麒麟 arm64 编译 Qt 的五个血泪教训5.1 报错GL/gl.h: No such file or directory现象configure 阶段或编译qtbase/src/gui时提示找不到GL/gl.h。 原因系统没装mesa-libGL-devel或者装了但头文件路径不在默认搜索路径里。 解决sudo yum install mesa-libGL-devel如果已装用find / -name gl.h -path *GL*确认路径然后在 configure 时加-I/usr/include/GL。5.2 报错g: internal compiler error: Killed现象make 跑到某个模块突然中断日志最后一行是Killed。 原因并行编译时内存耗尽被系统 OOM Killer 杀掉。 解决降低-j数值8GB 内存用-j216GB 用-j432GB 以上再考虑-j8。也可以临时加 swap 分区顶一下。5.3 qmake 生成的 Makefile 里链接了错误的库路径现象编译第三方项目时提示cannot find -lQt5Core但/opt/Qt5.12.8/lib下明明有。 原因环境变量LD_LIBRARY_PATH没生效或者qmake用的是系统旧版本。 解决which qmake确认指向/opt/Qt5.12.8/bin/qmake在.pro文件里显式加QMAKE_LIBDIR /opt/Qt5.12.8/lib。5.4 运行程序时报QSqlDatabase: QSQLITE driver not loaded现象程序启动后数据库连接失败提示 SQLite 驱动未加载。 原因QT_PLUGIN_PATH没设置或者sqldrivers插件目录不在搜索路径。 解决export QT_PLUGIN_PATH/opt/Qt5.12.8/plugins用ls /opt/Qt5.12.8/plugins/sqldrivers确认libqsqlite.so存在。如果不存在说明 configure 时-qt-sqlite没生效检查sqlite-devel是否安装。5.5 编译 qtmqtt 时报QtMqtt/QMqttClient: No such file现象项目里#include QtMqtt/QMqttClient编译失败。 原因qtmqtt没装到 Qt 的 include 目录或者.pro里没加QT mqtt。 解决确认qtmqtt执行了make install然后在.pro里加QT mqtt重新qmake再make。6. 验证编译成果与一个提速技巧编译装完之后别急着上项目先用一个最小示例验证 Qt 5.12.8 在麒麟 arm64 上确实能跑通。下面这个测试程序同时覆盖 Widgets、Network 和 SQLite能一次性把核心模块都验一遍。// test_qt.cpp #include QApplication #include QLabel #include QNetworkAccessManager #include QSqlDatabase #include QDebug int main(int argc, char *argv[]) { QApplication app(argc, argv); // 验证 Widgets QLabel label(Qt 5.12.8 on Kylin arm64 OK); label.show(); // 验证 Network QNetworkAccessManager manager; qDebug() Network manager created: manager; // 验证 SQLite 驱动 QSqlDatabase db QSqlDatabase::addDatabase(QSQLITE); db.setDatabaseName(:memory:); if (db.open()) { qDebug() SQLite driver loaded OK; } else { qDebug() SQLite driver failed: db.lastError().text(); } return app.exec(); }编译命令/opt/Qt5.12.8/bin/qmake -project # 在生成的 .pro 文件里加 QT widgets network sql /opt/Qt5.12.8/bin/qmake make ./test_qt逻辑说明qmake -project自动生成.pro文件然后手动补上QT widgets network sql。运行后如果弹出窗口、终端输出SQLite driver loaded OK说明 Widgets、Network、SQL 三个模块都正常。如果窗口没弹出来但终端没报错检查DISPLAY环境变量是否设置无头服务器上跑 GUI 需要 X11 转发或虚拟显示。最后分享一个提速技巧如果后续需要反复编译调试把qtbase单独拎出来编译其他模块用make -C qtbase的方式增量编译。qtbase是整个 Qt 的核心改configure参数后只需要重编qtbase其他模块的 Makefile 会引用qtbase的库不用全部重来。我在麒麟 SP2 上第一次全量编译花了将近三小时后来用增量方式改配置每次只要二十分钟。这个习惯帮我省下了大量等待时间希望帮到你。本文还有配套的精品资源点击获取