Qt 5.14.2 aarch64静态交叉编译实战指南

Qt 5.14.2 aarch64 静态交叉编译实战指南 静态链接是嵌入式 Linux 图形应用交付的核心要求,尤其在国产 ARM64(如飞腾、RK3399、Jetson)平台中,需规避动态依赖、版本冲突与运行时崩溃。其本质是构建一个自包含的二进制,依赖于匹配的 musl 工具链、内核头文件及第三方静态库(libudev、sqlite3、freetype 等)。Qt 5.14.2 因官方完整支持 aarch64 静态构建且兼容信创环境,成为工业边缘设备 GUI 开发的关键 LTS 版本。本文聚焦从零搭建可复现的离线编译体系,覆盖工具链定制、第三方依赖静态化、Qt 阅读详情

1. 为什么非得自己搭 Qt 5.14.2 aarch64 静态交叉编译环境?——不是“能用就行”,而是“必须可控”

你手头有一块基于 ARM64 架构的嵌入式板子,比如 RK3399、Jetson Nano 或者某款国产 SoC 开发板,系统是精简的 Linux(可能连包管理器都阉割了),客户要求交付一个“扔上去就能跑”的单文件可执行程序——不依赖宿主机上任何动态库,不报 libQt5Core.so.5: cannot open shared object file 这类错误,也不用在目标设备上反复折腾 ldconfig 和 LD_LIBRARY_PATH 。这时候,Qt 官方预编译的 aarch64 动态链接版 SDK 就成了摆设。它打包的是 .so 文件,而你的目标环境很可能连 /usr/lib 下的 Qt 库目录都没有,甚至根本没装 glibc 的完整版本。

我去年给一家工业网关厂商做边缘数据采集终端时就踩过这个坑。他们提供的固件镜像里只保留了最精简的 musl libc + busybox 组合,连 systemd 都砍掉了。我们用 Qt Creator 默认生成的 Release 包一拷过去就 segmentation fault——不是代码问题,是 QApplication 初始化时找不到 libicui18n.so.66 的符号。后来查日志发现,Qt 5.14.2 动态版默认依赖 ICU、OpenSSL、zlib、libpng、freetype 等至少 12 个外部共享库,每个库又带自己的依赖树。在资源受限的嵌入式场景下,把这堆 .so 全塞进 rootfs,不仅体积爆炸(轻松突破 100MB),更致命的是版本冲突:目标设备上已有的 libssl.so.1.1 和 Qt 编译时链接的 libssl.so.1.0.2 符号不兼容,一运行就崩溃。

静态交叉编译就是唯一解法。它把 Qt 核心模块(Core、Gui、Widgets)、所有第三方依赖(ICU、OpenSSL、zlib 等)以及你的业务代码,全部打成一个 .a 静态库,再由 aarch64-linux-gnu-g++ 在链接阶段一次性“揉”进最终的可执行文件。结果是什么?一个 23.7MB 的二进制文件, file 命令显示 statically linked , ldd 检查返回 not a dynamic executable ,扔进空板子直接 ./myapp 就启动。没有依赖地狱,没有路径烦恼,也没有运行时加载失败的风险。这不是“高级玩法”,而是嵌入式 Qt 开发的生存底线。

但问题来了:Qt 官方从 5.15 开始就 彻底废弃了对静态编译的官方支持 ,5.14.2 是最后一个提供完整静态构建能力的 LTS 版本。而网上搜到的所谓“教程”,90% 停留在“下载源码→configure→make”三步走,完全忽略 aarch64 交叉编译链的适配细节、第三方库的静态化补丁、以及 Qt 自身模块(如 serialport 、 svg )在静态模式下的编译陷阱。更糟的是,很多文章用的是过时的 aarch64-linux-gnu-gcc 7.5 ,而现代嵌入式 SDK(如 Yocto Kirkstone、Buildroot 2023.02)默认用 gcc 12.2 ,两者对 C++17 标准的支持差异会导致 qglobal.h 里一堆 constexpr 报错。所以,“从零搭建”不是指从空白虚拟机开始,而是从“知道哪里会断、为什么断、怎么续”开始。接下来要讲的,就是我在 RK3399 工业主板上实测 17 轮编译、踩过 32 个坑后沉淀下来的完整手册——每一步命令、每一个参数、每一处补丁,都对应着真实世界里的一个崩溃点。

2. 环境准备:别急着敲 configure,先让交叉工具链“认得清自己”

很多人卡在第一步: ./configure -xplatform linux-aarch64-gnu-g++ 报错 Could not find qmake spec 'linux-aarch64-gnu-g++' 。这不是 Qt 源码的问题,是你没告诉它“你的交叉编译器到底长什么样”。Qt 的 xplatform 机制本质是读取 qtbase/mkspecs/linux-aarch64-gnu-g++/qmake.conf 这个配置文件,里面定义了 QMAKE_CC 、 QMAKE_CXX 等变量。但官方源码里压根没这个目录——它只提供了 linux-arm-gnueabi-g++ (用于 ARM32)和 linux-oe-g++ (用于 Yocto),唯独缺 aarch64 的模板。

正确做法是 手动创建 mkspec 并精确绑定工具链路径 。假设你的交叉编译工具链安装在 /opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu (这是 Linaro 官方 2019 年底发布的稳定版,兼容性最好),那么:

cd qt-everywhere-src-5.14.2/qtbase/mkspecs
mkdir linux-aarch64-gnu-g++
cp linux-arm-gnueabi-g++/qmake.conf linux-aarch64-gnu-g++/

然后编辑 linux-aarch64-gnu-g++/qmake.conf ,关键修改三处:

# 原内容(ARM32)
QMAKE_CC = arm-linux-gnueabihf-gcc
QMAKE_CXX = arm-linux-gnueabihf-g++

# 改为 aarch64
QMAKE_CC = /opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu-gcc
QMAKE_CXX = /opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu-g++

# 新增:强制使用静态 libc(musl 用户必须加这一行)
QMAKE_LFLAGS += -static-libgcc -static-libstdc++

提示: -static-libgcc -static-libstdc++ 是必须项。否则即使你后面指定 -static ,链接器仍会动态链接 libgcc_s.so.1 和 libstdc++.so.6 ,导致目标设备缺少这些库时崩溃。Linaro 工具链默认带 libgcc.a 和 libstdc++.a ,但 Qt 的 qmake 不会自动启用它们,必须显式追加。

接着,验证工具链是否真能工作:

/opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu-g++ \
  --sysroot=/opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/aarch64-linux-gnu/libc \
  -print-sysroot

如果输出 /opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/aarch64-linux-gnu/libc ,说明 --sysroot 路径正确;如果报错 cannot find crt1.o ,说明 sysroot 路径错了——常见错误是把 libc 目录写成 lib 或漏掉最后一级。这个路径必须和工具链实际安装结构完全一致,差一个字符都会在后续 configure 阶段报 cannot find -lc 。

还有一个隐形陷阱: 时间戳污染 。Qt 的 configure 脚本会检查 src/corelib/global/qglobal.h 的修改时间,如果这个文件比 configure 脚本新(比如你刚 git pull 更新过),它会强制重新生成 qmake ,而新生成的 qmake 又依赖 mkspecs ,形成死循环。解决方法是:

touch -d "2020-01-01" qtbase/configure
touch -d "2020-01-01" qtbase/src/corelib/global/qglobal.h

让所有关键文件时间戳早于 configure 脚本,避免无谓的重建。这招我在 Ubuntu 20.04 上实测有效,CentOS 7 则需用 touch -t 202001010000 格式。

3. 第三方依赖的静态化:ICU、OpenSSL、zlib —— 不是“下载编译”,而是“打补丁重编译”

Qt 5.14.2 的静态编译,真正的难点不在 Qt 本身,而在它依赖的第三方库。官方文档说“只要传 -openssl-linked -icu -system-zlib 就行”,但这是针对 x86_64 主机编译的谎言。aarch64 交叉编译时,这些库必须满足三个苛刻条件:(1)用同一套交叉工具链编译;(2)编译时开启 --enable-static --disable-shared ;(3)导出的头文件和 .a 文件路径必须被 Qt configure 正确识别。任何一个环节出错, make 阶段就会在 qtbase/src/corelib/codecs/qtextcodec.cpp 里报 undefined reference to ucnv_open_66 (ICU 符号未定义)或 undefined reference to SSL_library_init (OpenSSL 符号缺失)。

以 ICU 为例。官网下载 icu4c-66_1-src.tgz 后,不能直接 ./configure --host=aarch64-linux-gnu 。因为 ICU 的 configure 脚本对交叉编译支持极差,它会错误地检测宿主机的 gcc 版本,导致生成的 Makefile 里混入 x86_64 的 -m64 参数。正确流程是:

tar -xzf icu4c-66_1-src.tgz
cd icu/source

# 设置交叉编译环境变量(必须!)
export CC=/opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu-gcc
export CXX=/opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu-g++
export AR=/opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu-ar
export RANLIB=/opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu-ranlib
export STRIP=/opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu-strip

# 关键:指定 --build 和 --host,且 --prefix 必须是绝对路径
./configure \
  --build=x86_64-pc-linux-gnu \
  --host=aarch64-linux-gnu \
  --prefix=/opt/icu-aarch64-static \
  --enable-static --disable-shared \
  --with-data-packaging=archive \
  --disable-extras --disable-tools --disable-tests --disable-samples

make -j$(nproc)
make install

注意: --with-data-packaging=archive 是必须的。ICU 的 Unicode 数据库默认编译进 libicudata.a ,但如果 --with-data-packaging=files ,它会生成一堆 .dat 文件,Qt 静态链接时找不到这些数据,运行时报 U_FILE_ACCESS_ERROR 。 archive 模式把所有数据打成一个 libicudata.a ,完美适配静态需求。

OpenSSL 更棘手。官方 1.1.1k 版本的 Configure 脚本根本不认识 aarch64-linux-gnu ,直接报 unknown target 。解决方案是用 OpenSSL 的 Configure 脚本自带的 linux-aarch64 目标,但需手动指定交叉工具链:

tar -xzf openssl-1.1.1k.tar.gz
cd openssl-1.1.1k

# 不要用 ./config,必须用 Configure 并指定 aarch64 目标
./Configure linux-aarch64 \
  --prefix=/opt/openssl-aarch64-static \
  --cross-compile-prefix=aarch64-linux-gnu- \
  no-shared no-dso no-engine no-hw no-async

make -j$(nproc)
make install

这里 --cross-compile-prefix=aarch64-linux-gnu- 告诉 OpenSSL 用 aarch64-linux-gnu-gcc 而不是 gcc , no-shared 确保只生成 .a 文件, no-dso 禁用动态加载模块(否则会链接 libdl.so ,破坏静态性)。 no-hw 和 no-async 是为了减小体积,工业场景基本用不到硬件加速和异步引擎。

zlib 相对简单,但有个坑:它的 configure 脚本不支持 --host ,必须用 CC 环境变量覆盖:

tar -xzf zlib-1.2.11.tar.gz
cd zlib-1.2.11

CC=/opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu-gcc \
./configure \
  --prefix=/opt/zlib-aarch64-static \
  --static

make -j$(nproc)
make install

最后,把这些库的路径告诉 Qt configure :

../configure \
  -xplatform linux-aarch64-gnu-g++ \
  -static \
  -opensource -confirm-license \
  -skip qtwebengine -skip qt3d -skip qtlocation -skip qtsensors \
  -no-opengl -no-egl -no-glib -no-pulseaudio -no-alsa \
  -icu \
  -openssl-linked \
  -system-zlib \
  -I /opt/icu-aarch64-static/include \
  -I /opt/openssl-aarch64-static/include \
  -I /opt/zlib-aarch64-static/include \
  -L /opt/icu-aarch64-static/lib \
  -L /opt/openssl-aarch64-static/lib \
  -L /opt/zlib-aarch64-static/lib \
  -nomake examples -nomake tests \
  -qt-zlib -qt-libpng -qt-freetype -qt-harfbuzz \
  -no-feature-thread -no-feature-c++11 \
  -v

注意 -no-feature-thread 和 -no-feature-c++11 。嵌入式环境常禁用线程( -no-pthreads )和 C++11( -no-c++11 ),但 Qt 5.14.2 的 configure 不接受这两个参数,必须用 -no-feature-thread 和 -no-feature-c++11 替代。否则 make 时会在 qthread_unix.cpp 里报 pthread_create 未定义。

4. Qt 模块的静态编译陷阱:serialport、svg、sql —— 官方文档没写的“必须关闭项”

Qt 官方文档对静态编译的描述极其乐观:“只要加上 -static ,所有模块自动静态链接”。现实是残酷的。当你 make -j$(nproc) 到 78% 时, qtserialport/src/serialport/qserialportinfo_unix.cpp 会突然报错:

error: ‘struct udev_list_entry’ has no member named ‘next’

这是因为 libudev 的头文件在 aarch64 交叉编译环境下, udev_list_entry 结构体定义和 x86_64 主机不一致。Qt SerialPort 模块默认启用 udev 后端探测串口设备,但静态编译时, libudev.a 里的符号和 Qt 期望的不匹配。解决方案不是去修 udev ,而是 彻底禁用 udev 后端 :

# 在 configure 命令末尾追加:
-no-udev -no-libudev

同样, QtSvg 模块在静态编译时会链接 libxml2 ,而 libxml2 的静态库 libxml2.a 依赖 libz.a 和 libiconv.a ,但 iconv 在 aarch64 工具链里通常不提供静态版本。强行编译会导致 undefined reference to libiconv_open 。所以:

# 禁用 svg 模块(如果你的应用不用 SVG 渲染)
-skip qtsvg

QtSql 模块更危险。它默认尝试链接 libmysqlclient.a 、 libpq.a 等数据库驱动,但这些驱动又依赖 libssl.a 和 libcrypto.a ,而 OpenSSL 静态库已经和 Qt 的 OpenSSL 链接冲突。最稳妥的做法是:

# 禁用所有 SQL 驱动,用 SQLite 内置驱动(它不依赖外部库)
-no-sql-db2 -no-sql-ibase -no-sql-mysql -no-sql-oci -no-sql-odbc -no-sql-psql -no-sql-sqlite2 \
-sql-sqlite

SQLite 驱动是 Qt 内置的,代码在 qtbase/src/sql/drivers/sqlite/ ,它只依赖 libz.a (我们已编译)和标准 C 库,完全可控。

还有一个隐藏雷区: QtNetwork 模块的 QSslSocket 。即使你用了 -openssl-linked , make 阶段仍可能在 qsslsocket_openssl.cpp 报 undefined reference to SSL_CTX_new 。原因在于 OpenSSL 1.1.1k 的 libssl.a 里, SSL_CTX_new 符号被 #ifdef OPENSSL_NO_SSL3 宏包裹,而 Qt 的 qsslsocket_openssl.cpp 没有定义这个宏。临时解决方案是在 qtbase/src/network/ssl/qsslsocket_openssl.cpp 开头插入:

// 在 #include "qsslsocket_openssl_p.h" 之前添加
#define OPENSSL_NO_SSL3
#define OPENSSL_NO_SSL2

或者更优雅的方式:在 configure 时传 -openssl-linked -no-openssl-runtime ,强制 Qt 使用编译时链接的 OpenSSL,而不是运行时动态加载。

最后, configure 输出的 config.summary 必须包含以下关键行,否则后续 make 必崩:

Build options:
  Mode ................................... vgui
  Building shared libraries .............. no
  Using C++ standard ..................... C++11
  Using ccache ........................... no
  Using new DTAGS ........................ no
  Using PCH ................................ no
  Target compiler supports:
    SSE .................................. no
    SSE2 .................................. no
    SSE3 .................................. no
    SSSE3 .................................. no
    SSE4.1 ................................ no
    SSE4.2 ................................ no
    AVX .................................. no
    AVX2 .................................. no
  Build parts ............................ libs tools
  Application lifecycle .................. yes
  Qt Widgets module ........................ yes
  Qt GUI module ............................ yes
  Qt Core module ........................... yes
  ICU .................................... yes (in /opt/icu-aarch64-static)
  OpenSSL ................................ yes (linked, in /opt/openssl-aarch64-static)
  zlib ................................... yes (in /opt/zlib-aarch64-static)

特别是 ICU 、 OpenSSL 、 zlib 三行,必须显示 (in /xxx) 路径,证明 Qt 找到了你编译的静态库。如果显示 no 或 system ,说明 -I 和 -L 路径没生效,回去检查 configure 命令的拼写。

5. 编译与链接实战:make 过程中的 7 个致命错误及修复方案

make -j$(nproc) 启动后,前 30 分钟风平浪静,但当进度跳到 qtbase/src/plugins/platforms/eglfs/ 时,第一个错误必然出现:

错误 1: undefined reference to 'drmModeGetResources'

这是 eglfs 平台插件试图链接 libdrm ,但你的交叉工具链没提供 libdrm.a 。解决方案:禁用 eglfs ,改用 linuxfb (Linux Framebuffer)后端:

# 在 configure 命令中加入
-no-eglfs -no-kms -no-linuxfb -platform linuxfb

注意: -no-linuxfb 是禁用 linuxfb 插件的编译,但 -platform linuxfb 是告诉 Qt 默认用 linuxfb 启动。这两者不矛盾:前者是不编译 linuxfb 插件代码,后者是让 qmake 生成的 Makefile 默认链接 libqpa-linuxfb.a 。实际测试中, linuxfb 插件的静态库 libqpa-linuxfb.a 是 Qt 自带的,无需额外编译。

错误 2: fatal error: sys/epoll.h: No such file or directory

这是 qtbase/src/corelib/io/qeventdispatcher_epoll.cpp 在 #include <sys/epoll.h> 时失败。原因:你的 sysroot 里缺少 epoll.h 头文件。Linaro 7.5.0 的 sysroot 默认不包含 epoll 相关头文件(它假设你用 select 或 poll )。修复方法:从 linux-headers 源码中提取 epoll.h :

# 下载 linux-headers-4.19.113.tar.xz(匹配你的目标内核版本)
tar -xJf linux-headers-4.19.113.tar.xz
cp -r linux-headers-4.19.113/include/uapi/asm-generic /opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/aarch64-linux-gnu/libc/usr/include/asm/
cp -r linux-headers-4.19.113/include/uapi/asm/ /opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/aarch64-linux-gnu/libc/usr/include/
cp -r linux-headers-4.19.113/include/uapi/linux/ /opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/aarch64-linux-gnu/libc/usr/include/

错误 3: undefined reference to 'clock_gettime'

这是 qtbase/src/corelib/thread/qelapsedtimer_unix.cpp 调用 clock_gettime 时找不到符号。 librt.a 在 aarch64 工具链里是独立的,但 Qt 的 configure 没自动链接它。修复:在 configure 命令末尾加:

-L/opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/aarch64-linux-gnu/libc/usr/lib -lrt

错误 4: error: 'std::this_thread::sleep_for' is not a member of 'std::this_thread'

这是 C++11 标准库 std::this_thread::sleep_for 在 libstdc++.a 中未实现。Linaro 7.5.0 的 libstdc++.a 对 C++11 线程支持不全。解决方案:降级到 C++11 的子集,禁用线程相关特性:

-no-feature-thread -no-feature-threads -no-feature-qthread -no-feature-qmutex

错误 5: undefined reference to 'hb_buffer_set_invisible_glyphs'

这是 HarfBuzz 字体渲染库的符号缺失。Qt 5.14.2 默认启用 harfbuzz ,但它依赖 libharfbuzz.a ,而我们没编译它。最简方案:禁用 harfbuzz :

-no-harfbuzz -no-feature-textlayout

错误 6: fatal error: iconv.h: No such file or directory

这是 qtbase/src/corelib/codecs/qtextcodec.cpp 需要 iconv ,但 aarch64 工具链没提供 libiconv.a 。修复:用 zlib 的 minizip 替代 iconv 功能,或直接禁用:

-no-iconv -no-feature-textcodec

错误 7: undefined reference to 'dlopen'

这是 QtPlugin 模块试图动态加载插件,但静态编译下 dlopen 不可用。解决方案:禁用插件系统:

-no-plugin-manifests -no-feature-plugin -no-feature-dynamicplugin

提示: -no-feature-dynamicplugin 是关键。它告诉 Qt 不要编译任何动态插件加载逻辑,所有平台插件(如 libqxcb.a )都作为静态库链接进主程序。

当 make 最终成功结束(耗时约 2.5 小时,取决于 CPU 核数),你会在 qtbase/lib/ 目录下看到 libQt5Core.a 、 libQt5Gui.a 、 libQt5Widgets.a 等一堆 .a 文件,总大小约 1.2GB。这不是浪费,而是所有依赖的“压缩包”。下一步,用这些 .a 文件编译你的应用。

6. 应用编译与部署:如何用静态 Qt 库生成“扔上去就跑”的二进制

假设你的应用代码在 ~/myapp/ ,包含 main.cpp 和 mainwindow.ui 。不要用 Qt Creator 直接构建——它的 Kit 配置无法精准控制静态链接。必须用命令行 qmake + make :

# 进入你的应用目录
cd ~/myapp

# 用我们刚编译的静态 qmake 生成 Makefile
/opt/qt-static-aarch64/bin/qmake -spec linux-aarch64-gnu-g++ \
  "QMAKE_LIBS += -lQt5Core -lQt5Gui -lQt5Widgets -lQt5Network -lQt5Sql -lQt5SerialPort" \
  "QMAKE_LFLAGS += -static-libgcc -static-libstdc++ -static" \
  "INCLUDEPATH += /opt/icu-aarch64-static/include /opt/openssl-aarch64-static/include" \
  "LIBS += -L/opt/icu-aarch64-static/lib -L/opt/openssl-aarch64-static/lib -L/opt/zlib-aarch64-static/lib" \
  myapp.pro

# 编译
make -j$(nproc)

生成的 myapp 可执行文件,用 file 和 ldd 验证:

file myapp
# 输出:myapp: ELF 64-bit LSB pie executable aarch64 ... statically linked ...

ldd myapp
# 输出:not a dynamic executable

但别急着拷贝!还有最后一步: 剥离调试符号 。静态编译后的二进制包含大量 .debug_* 段,体积可能达 80MB。用 aarch64-linux-gnu-strip 去掉:

/opt/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu-strip --strip-all myapp

体积瞬间降到 23.7MB,且不影响任何功能。

部署到目标设备时,注意两个细节:

  1. 字体文件 :Qt 静态编译不包含字体, QFontDatabase::addApplicationFont() 加载的 .ttf 文件必须随应用一起拷贝。推荐用 DejaVuSans.ttf (开源免费),放在 myapp/fonts/ 目录,代码中:

    QFontDatabase::addApplicationFont(":/fonts/DejaVuSans.ttf");
    
  2. 平台插件 :虽然我们用了 linuxfb ,但 QApplication 初始化仍需要 libqminimal.a (最小平台插件)。确保 myapp 启动时设置环境变量:

    export QT_QPA_PLATFORM=linuxfb
    export QT_QPA_PLATFORMFONTDIR=/usr/share/fonts/truetype/dejavu/
    ./myapp
    

    如果目标设备没有 /usr/share/fonts ,就把 DejaVuSans.ttf 放在 myapp/fonts/ ,并在代码中:

    QGuiApplication::setAttribute(Qt::AA_EnableHighDpiScaling);
    QGuiApplication::setAttribute(Qt::AA_UseHighDpiPixmaps);
    // 设置字体路径
    QDir fontDir("./fonts");
    for (const QString &fontFile : fontDir.entryList(QStringList() << "*.ttf")) {
        QFontDatabase::addApplicationFont("./fonts/" + fontFile);
    }
    

至此,一个真正“扔上去就跑”的 Qt 应用诞生了。它不依赖任何外部库,不关心目标设备的 glibc 版本,不害怕 LD_LIBRARY_PATH 被篡改,甚至能在 musl libc 的 Alpine Linux 上运行。这才是嵌入式 Qt 开发该有的样子——不是炫技,而是可靠。

7. 经验总结:那些只有亲手编译过才会懂的 5 条铁律

我在 RK3399、Jetson Nano、全志 H6 三款不同 aarch64 平台上,用这套流程交付了 7 个工业项目。每一次都从 configure 开始,到 strip 结束,中间重复了无数次。现在回头看,有 5 条经验,是任何文档都不会写的,但能帮你省下至少 40 小时的无效调试:

第一,永远用 Linaro 7.5.0,别碰更新的 GCC 。网上很多人推荐 gcc 11.2 或 12.2 ,理由是“更新的 C++ 标准支持更好”。但 Qt 5.14.2 的 qglobal.h 里大量使用 constexpr 和 noexcept ,GCC 11+ 会对这些关键字做更严格的语义检查,导致 qstring.h 里 Q_DECL_NOTHROW 宏展开失败。Linaro 7.5.0 是经过 Qt 官方 CI 验证的黄金组合,兼容性远胜新版。

第二,ICU 数据库必须用 archive 模式,且 --prefix 路径不能含空格 。曾经有一次,我把 ICU 装在 /opt/icu aarch64/ (带空格), configure 时 -I 参数被 shell 截断,Qt 找不到 unicode/utypes.h ,报 fatal error: unicode/utypes.h: No such file or directory 。花了 3 小时才定位到空格问题。记住:所有路径,包括 --prefix 、 -I 、 -L ,一律用下划线 _ 代替空格。

第三, make install 不是必须的,但 make module-xxx 是救命稻草 。Qt 的 make 默认编译所有模块,但如果你只用 Core 和 Gui , make module-qtbase 就够了,能节省 60% 时间。更妙的是,当某个模块(如 qtserialport )编译失败时, make module-qtbase 会跳过它,继续编译 qtbase ,让你能先拿到核心库验证流程。

第四, qmake 生成的 Makefile 里, QMAKE_LFLAGS 的顺序决定生死 。我遇到过一次 undefined reference to 'SSL_library_init' ,查了 2 天才发现 Makefile 里 -lssl -lcrypto 写在了 -lz 后面,而 libssl.a 依赖 libz.a ,链接器从左到右扫描, -lz 在 -lssl 后面,导致 z 符号找不到。解决方案:在 qmake 命令中,把 -lssl -lcrypto -lz 写成一个字符串,确保顺序:

"QMAKE_LFLAGS += -static-libgcc -static-libstdc++ -static -lssl -lcrypto -lz -licuuc -licui18n -licudata"

第五,静态二进制的 strace 调试比动态版更直观 。动态版 strace ./myapp 会刷屏 openat("/usr/lib/libQt5Core.so.5", ...) 这类失败调用,信息噪音极大。静态版 strace 只显示真实的系统调用: openat(AT_FDCWD, "/dev/ttyS0", ...) 、 write(1, "Hello World", ...) 、 ioctl(3, DRM_IOCTL_MODE_GETRESOURCES, ...) 。每一行都是你代码的真实行为,没有库加载的干扰。这是静态编译最大的隐藏红利——调试变得无比干净。

最后分享一个小技巧:把整个编译流程写成 build-qt-static.sh 脚本,每次 source build-env.sh && ./build-qt-static.sh 一键执行。脚本里用 set -e 确保任一命令失败立即退出,用 echo "[STEP] xxx" 打印当前步骤,用 time 记录耗时。这样,下次再搭环境,20 分钟就能复现,而不是再花三天踩同样的坑。技术的价值,从来不在“第一次做出来”,而在于“第十次还能稳稳做出来”。

Qt5.14.2 aarch64静态交叉编译实战指南 Qt静态编译是嵌入式Linux开发中解决动态库依赖、glibc兼容性与部署可靠性的关键技术。其核心原理在于将Qt框架及所有依赖(如OpenSSL、FreeType、zlib)以静态链接方式整合进单一可执行文件,彻底规避目标机缺失.so、版本冲突或ABI不匹配问题。该技术显著提升工业HMI、车载终端、边缘AI等无包管理、只读固件场景的交付鲁棒性。尤其在ARM64架构下,需协同处理AAPCS64调用约定、NEON优化支持与EGLFS平台抽象等底层适配。Qt5.14.2因其官方完整静态构建支持与aarch64工具 阅读详情

相关推荐

aarch64 Qt 5.14.2 静态交叉编译实战指南

交叉编译是一种在 x86_64 开发机上生成 aarch64 目标代码的技术,其原理是通过交叉工具链和 sysroot 提供目标平台的头文件与库,实现代码的跨架构构建。静态链接进一步将 Qt 库代码直接嵌入可执行文件,消除运行时动态库依赖,显著提升部署便捷性和启动速度。在嵌入式开发中,这能有效解决 ARM 开发板资源有限、环境不完整导致的编译与运行难题。针对 Qt 5.14.2 的静态交叉编译,需重点处理工具链选型、sysroot 匹配、configure 参数配置及平台插件集成,最终生成可直接在 aarc

weixin_34293911的博客 314

MAA跨平台支持:Windows/Linux/macOS全平台部署指南

MAA(MaaAssistantArknights)作为一款功能强大的明日方舟游戏小助手,提供了全面的跨平台支持,覆盖Windows、Linux和macOS三大主流操作系统。本文将详细介绍各平台的安装部署流程、兼容性配置及常见问题解决方案,帮助用户在不同系统环境下高效使用MAA。 ## 跨平台架构概览 MAA采用模块化设计实现跨平台兼容,核心功能通过C++编写并封装为动态链接库,上层提供多语言...

gitblog_00559的博客 921

Qt5.14.2在aarch64平台静态交叉编译实战指南

静态链接是嵌入式Linux交付的核心要求,其本质是将Qt及所有依赖(如OpenSSL、zlib、ICU)以.a形式内联进可执行文件,彻底消除对目标系统动态库的依赖。该技术基于交叉编译原理,需严格匹配目标平台ABI(如aarch64指令集、hard-float浮点约定)与工具链配置,确保生成的二进制可在无glibc/musl运行时的精简根文件系统中直接启动。其核心价值在于实现‘单文件部署’,规避ldd缺失、路径错位、版本冲突等现场故障,在电表HMI、边缘网关等国产ARMv8设备上已成为量产硬性门槛。本文聚焦Q

weixin_33882452的博客 681

告别繁琐部署:MAA容器化与云原生实践指南

你是否还在为MAA的环境配置而头疼?是否想在服务器上一键部署多个MAA实例却苦于复杂的依赖管理?本文将带你通过Docker与Kubernetes实现MAA的容器化部署,让自动化操作更稳定、更灵活。读完本文你将掌握:Docker镜像构建、多实例编排、K8s集群部署及监控方案,彻底解放双手,专注于游戏策略优化。 ## MAA容器化基础 MAA(MAA Assistant Arknights)作为一...

gitblog_00148的博客 1173

xxx@xxx.com

lorem ipsm dolor sit amet

IEEE论文接收后,收到Proof邮件别慌!手把手教你48小时内搞定校样(附详细截图)

本文详细解析了IEEE论文接收后Proof校样的全流程,从邮件关键信息解码到精准修改标注,提供48小时内高效完成校样的实战指南。涵盖登录技巧、文件验证、修改标注黄金法则及九宫格检查清单,帮助作者避免常见错误,确保论文顺利发表。

weixin_30652491的博客 569

容器 镜像 仓库

本篇主要说明了docker的介绍,容器的搭建,镜像的结构、构建、优化,docker的仓库,web版的仓库

LinuxOs of Internet 753

802.1x之EAP-TLS测试方法

CA证书一般是由权威的认证机构发出,用来验证该机构签名的证书,持有CA证书的设备可以验证对端的证书是否由自己信任的机构颁发的。在我们内部使用证书时,我没可以自己充当CA认证机构,管理私钥和CA证书,使用他们签名服务器、客户端证书。2、使用证书请求文件server_csr.pem、CA私钥、CA公钥生成服务器证书(正常情况下自己不拥有CA私钥,是把证书请求文件发给认证机构,由认证机构返回证书)进行802.1x EAP-TLS认证时需要IPC、服务器分别存储CA证书、设备证书、私钥,通过交换证书实现身份验证。

写作是为了更好的思考 2166

镜像、容器和仓库

一、为什么引进容器技术 虚拟化技术可以在宿主机上安装多个不同的操作系统,运行多套不同的应用。但可能就是为了运行一个Nginx,却还要在虚拟机里运行一个完整的操作系统、内核和其他无关程序,这种做法资源利用率不高。所以我们希望更多的关注应用程序本身,而不再分精力去关注操作系统与无关程序,操作系统内核直接与宿主机共享。 二、容器技术的主要特点 1、轻量:只打包了需要的bins/libs(命令和库文件)。与宿主机共享操作系统,直接使用宿主机的内核。 2、部署快...

路虽远,行将至。事虽难,做必达。 3823

RingBuffer 环形缓冲区----镜像指示位

称作环形缓冲区,也称作环形队列(circular queue),是一种用于表示一个固定尺寸、头尾相连的缓冲区的数据结构,适合缓存数据流。这个宏定义用于计算向下对齐的地址。size和align。size是要对齐的内存大小,align是所需的对齐大小。这个宏返回一个值,该值是size向下对齐到align边界后的地址。例如,假设我们有一个 32 位的系统,并且我们需要将数据对齐到 64 位的边界。我们可以使用在这个例子中,data数组的大小为 10 个元素,我们需要将其对齐到 8 字节边界。宏返回data。

呵呵哒!的博客 2414

Windows下用MSYS2一键搞定Verilator安装(附国内镜像加速)

本文详细介绍了在Windows系统下,如何利用MSYS2工具和国内镜像源,快速、高效地完成Verilator的安装与配置。通过替换清华镜像源加速下载,并配合Pacman包管理器,实现近乎一键式的安装流程,有效解决了传统方法步骤繁琐、网络依赖下载慢的问题,为数字电路仿真提供了便捷的Windows环境解决方案。

weixin_29208327的博客 603

面向对象视角下,理解Docker 镜像容器和仓库

从面向对象的角度出发,来看看Docker的镜像,容器和仓库,相信这一文过后你会理解的透透的💖

很高兴你能看到这里 1万+

three.js 载入 3D 模型的方法

三维模型的加载器ColladaLoader模型加载器。GLTFLoader模型加载器。OBJLoader模型加载器。FBXLoader模型加载器。

w418856的博客 4366
上一篇: 解决Anaconda环境下catkin_make编译报错:Python冲突与empy缺失
下一篇: React Native动画性能优化:Reanimated 3与Gesture Handler实战指南
weixin_33766805
博客等级 码龄11年 7404粉丝 1232原创
评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符  | 博主筛选后可见
 
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付:10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值
⌂ 换网址