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,且不影响任何功能。
部署到目标设备时,注意两个细节:
-
字体文件 :Qt 静态编译不包含字体,
QFontDatabase::addApplicationFont()加载的.ttf文件必须随应用一起拷贝。推荐用DejaVuSans.ttf(开源免费),放在myapp/fonts/目录,代码中:QFontDatabase::addApplicationFont(":/fonts/DejaVuSans.ttf"); -
平台插件 :虽然我们用了
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 分钟就能复现,而不是再花三天踩同样的坑。技术的价值,从来不在“第一次做出来”,而在于“第十次还能稳稳做出来”。
314



被折叠的 条评论
为什么被折叠?



