1. 从宿主机到开发板:代码开发工具不对齐,程序连第一行都跑不起来
很多人第一次给 ARM 板子做 Qt 应用,都会撞上同一个瞬间:在 Ubuntu 上 make 得干干净净,把可执行文件拷到板子上,回车敲下去,终端甩回一句 cannot execute binary file: Exec format error。代码没问题,问题出在代码开发工具这一整条链路上——编译器、链接器、库、调试器,默认全是冲着宿主机 x86 去的。这里只讲一件事:怎样把这条链路整体转向 aarch64,让 Qt 程序在板子上正常启动,并且让 OpenGL 渲染真正落到 GPU 上,而不是悄悄回落成软件光栅化。适合已经会写 Qt、但第一次做交叉编译的人,也适合 Kit 配了三遍还是跑不起来的人。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具的第一层:交叉编译工具链与 sysroot 怎么落地
2.1 交叉编译到底在替谁编译
先把三个角色的边界说清楚,后面所有报错都能往这张表里归位。
| 角色 | 跑在哪 | 具体指什么 |
|---|---|---|
| host | 宿主机 Ubuntu x86_64 | 编译器本体、moc/uic/rcc、qmake 程序 |
| target | 板子 aarch64 | 最终可执行文件、Qt 动态库 |
| sysroot | 宿主机上的一个普通目录 | 从板子同步回来的 /usr/include、/usr/lib |
编译器在前端把 C++ 文本变成中间表示,再在代码生成阶段按目标架构输出机器码,这个过程跑在 x86 上完全没有问题,所以“交叉”本身不神秘。麻烦出在链接阶段:链接器要去 /usr/lib 找 libstdc++.so、libQt5Core.so,而宿主机的 /usr/lib 里全是 x86 的 .so,架构对不上会被直接跳过,最后就是一堆 undefined reference。sysroot 的作用就是把链接器的搜索起点从宿主机的根目录挪到一份“长得像板子根文件系统”的目录上。理解这一点,比背十条命令有用得多。
工具链来源上有个常见选择:发行版仓库里的 gcc-aarch64-linux-gnu,还是板厂 SDK 包里自带的那一套。两者都能编出 aarch64 的 ELF,差别在 glibc 版本、浮点 ABI 和内核头文件版本。判断依据只有一个——板子 rootfs 里 /lib/libc.so.6 的版本。宿主机工具链的 glibc 比板子新,编出来的程序可能在板子上直接报 GLIBC_2.xx not found;工具链比板子旧一般没事。所以我的习惯是:能用板厂 SDK 里那一套就用那一套,实在没有再用发行版的,并且编完第一时间在板子上验证,不要等 Qt 编完才发现基础库不兼容。
2.2 工具链落地与三条验证命令
我不喜欢把工具链塞进 /usr/local,容易和系统自带的混。统一放 /opt 下,一个版本一个目录,切换靠 PATH。
bash复制# 目录规划:一个工具链一个独立目录,方便多版本并存
sudo mkdir -p /opt/toolchain/aarch64
sudo tar -xf gcc-aarch64-linux-gnu-*.tar.xz -C /opt/toolchain/aarch64 --strip-components=1
# 只在当前 shell 生效,避免污染系统环境
export PATH=/opt/toolchain/aarch64/bin:$PATH
解压后不要急着编 Qt,先跑三条命令确认这工具链是不是真的冲着 aarch64 去的:
bash复制# 1. 看目标三元组,正常应输出 aarch64-linux-gnu 或 aarch64-none-linux-gnu
aarch64-linux-gnu-gcc -dumpmachine
# 2. 看配置里带的 sysroot 和 glibc 版本,确认没有指向宿主机
aarch64-linux-gnu-gcc -v
# 3. 确认前缀名对得上,别把 aarch64-none-elf 这种裸机工具链拿来编 Linux 程序
ls /opt/toolchain/aarch64/bin | grep gcc
第一条命令是在查“目标三元组”,它决定了编译器默认去哪个目录找库;第二条会打印 --with-sysroot 和 --with-glibc-version 之类的配置项,如果这里显示的 sysroot 是空或者指着宿主机,说明这套工具链是“自带库”的发行版版本,后面配 Qt 时 -sysroot 参数就得显式补上;第三条是血泪经验,裸机工具链(none-elf)编出来的程序没有 Linux 系统调用入口,跑起来只会段错误。
再用一个最小程序把“编得出、跑得动”这件事闭环掉:
c复制// hello.c:只依赖 libc,能编过就说明工具链和 sysroot 基本可用
#include <stdio.h>
int main(void)
{
printf("hello from target\n");
return 0;
}
bash复制aarch64-linux-gnu-gcc hello.c -o hello
# 关键一步:file 必须看到 ARM aarch64,看到 x86-64 就是编译器用错了
file hello
file 的输出里如果出现 ELF 64-bit LSB pie executable, ARM aarch64,第一层就算通了。如果这一步就报找不到 stdio.h,说明工具链自带的 sysroot 不完整,通常是解压时 --strip-components 层级写错,或者你拿到的是个精简过的工具链包,需要额外补 sysroot。
2.3 sysroot 从板子上搬回来
板厂 SDK 里的 sysroot 有时候是几年前的,和当前板子上的镜像对不上。最稳的办法是直接从板子上同步,前提是板子能 ssh 登录。
bash复制# 目录结构要和板子根文件系统一致,这样 -sysroot 指过去才能被正确解析
mkdir -p /opt/sysroot
rsync -avz --copy-unsafe-links root@192.168.1.100:/usr/include /opt/sysroot/usr/
rsync -avz --copy-unsafe-links root@192.168.1.100:/usr/lib /opt/sysroot/usr/
rsync -avz --copy-unsafe-links root@192.168.1.100:/lib /opt/sysroot/
--copy-unsafe-links 是这里最关键的一个参数。板子的 /usr/lib 里大量 .so 是指向 /lib 或带绝对路径的符号链接,比如 libQt5Core.so.5 -> /usr/lib/aarch64-linux-gnu/libQt5Core.so.5.15.2。直接 rsync 保留链接,到了宿主机上这个绝对路径可能指向一个不存在的位置,链接器打开就是空,报“找不到库”,而 ls 看上去文件明明在。加上这个参数后,指向 sysroot 外部的链接会被复制成实体文件,占点磁盘但省掉一整晚的排查。
同步完做一次完整性检查,重点看那几个一定会被链接到的库:
bash复制# 确认关键库和头文件都在,且是 aarch64 的 ELF
ls /opt/sysroot/usr/lib/libQt5Core.so* 2>/dev/null
file /opt/sysroot/usr/lib/libstdc++.so.6
readelf -h /opt/sysroot/usr/lib/libstdc++.so.6 | grep Machine
readelf 里 Machine 一行应该是 AArch64。如果这里是 Advanced Micro Devices X86-64,说明 rsync 的方向反了,把宿主机的库同步进去了,这种错误极其隐蔽,因为文件确实存在、名字也对,只有链接时才炸。
3. Qt 库的交叉编译:configure 参数错一个,后面全白干
3.1 为什么必须准备两份 Qt
这是交叉编译 Qt 最容易跳过、也最容易在后面被反咬一口的地方。Qt 的构建过程里有一批工具是要在宿主机上跑起来的:moc 负责把带 Q_OBJECT 的头文件翻译成 C++ 源码,uic 处理 .ui 文件,rcc 把 qrc 资源编译成二进制数组。这三个工具如果在宿主机上跑不起来,整个构建就停了;但如果用宿主机 apt 装的那份 Qt 里的 moc,而链接用的是自己编的 target Qt,版本只要差一点点,就会出现经典的 undefined reference to vtable for XXX——moc 生成的元对象代码和 Qt 库内部的元对象布局对不上。
| 组件 | 运行位置 | 提供什么 | 来源 |
|---|---|---|---|
| host Qt | 宿主机 x86 | moc、uic、rcc、qmake 可执行文件 | 同一份 Qt 源码编出来的 host 版本 |
| target Qt | 板子 aarch64 | libQt5Core 等动态库、头文件 | 同一份 Qt 源码编出来的 target 版本 |
结论很硬:host Qt 和 target Qt 必须来自同一份源码、同一个 commit,用 -hostprefix 和 -extprefix 分别安装到两个目录。省这一步,后面要用无数个玄学 bug 来还。
3.2 configure 参数逐条拆
下面这套参数是 Qt 5 系列交叉编译的常规骨架,Qt 6 用 CMake 之后参数名有变化,思路一致。
bash复制cd /opt/build/qt-target
../qt-everywhere-src/configure \
-prefix /usr \
-extprefix /opt/qt-target \
-hostprefix /opt/qt-host \
-sysroot /opt/sysroot \
-platform linux-g++ \
-xplatform linux-aarch64-gnu-g++ \
-opensource -confirm-license \
-nomake examples -nomake tests \
-opengl es2 \
-skip qtwebengine
逐条解释,每条都对应一个后面会出问题的地方:
-prefix /usr 是板子上的安装路径。程序在板子上运行时,Qt 会按这个前缀去找插件目录,所以它必须和板子实际部署位置一致,不能写成宿主机的 /opt/qt-target。
-extprefix /opt/qt-target 是宿主机上的安装路径,也就是 make install 之后东西落在哪儿。这个目录会被 Qt Creator 当作 Qt Version 的路径填进去。
-hostprefix /opt/qt-host 是那套 host Qt 的落点,moc、uic 就在这里的 bin 下。
-sysroot /opt/sysroot 告诉 configure 去我们刚同步回来的目录里找 xcb、fontconfig、glib 这些依赖。这个参数写错,configure 阶段就会报一堆 “cannot find -lXxx”。
-platform linux-g++ 和 -xplatform linux-aarch64-gnu-g++ 是一对:前者是构建期工具的编译平台,后者是目标平台的 mkspec 名,它对应 qtbase/mkspecs/ 下的一个目录。
-opengl es2 决定了 Qt 的图形后端走 OpenGL ES 2.0,而不是桌面 GL。嵌入式 GPU 基本只完整支持 GLES,选错的话后面 QOpenGLWidget 会创建不出上下文。
-skip qtwebengine 是省时间用的,这个模块依赖链极长,交叉编译成功率也低,第一轮先跳过,等主链路通了再回头补。
3.3 mkspec 与编译验证
linux-aarch64-gnu-g++ 这个名字不是 Qt 自带的,需要自己建。它本质上就是一个描述“用哪套编译器”的 qmake.conf。
bash复制mkdir -p /opt/build/qt-everywhere-src/qtbase/mkspecs/linux-aarch64-gnu-g++
makefile复制# qmake.conf:告诉 qmake 目标平台用哪套工具
MAKEFILE_GENERATOR = UNIX
CONFIG += incremental
QMAKE_INCREMENTAL_STYLE = sublib
include(../common/linux.conf)
include(../common/gcc-base-unix.conf)
include(../common/g++-unix.conf)
QT_QMAKE_TARGET_MKSPEC = linux-aarch64-gnu-g++
QMAKE_CC = aarch64-linux-gnu-gcc
QMAKE_CXX = aarch64-linux-gnu-g++
QMAKE_LINK = aarch64-linux-gnu-g++
QMAKE_AR = aarch64-linux-gnu-ar cqs
QMAKE_OBJCOPY = aarch64-linux-gnu-objcopy
QMAKE_STRIP = aarch64-linux-gnu-strip
load(qt_config)
这份文件里没有 sysroot 相关的配置,是因为 -sysroot 已经在 configure 阶段传进去了,qmake 会自动生成对应的 qconfig.pri。手写 QMAKE_CFLAGS += --sysroot=... 反而容易和 configure 生成的内容重复,导致参数顺序问题。
configure 通过之后是漫长的编译,make -j 的并发数不要拉满:
bash复制# 并发数按内存而不是核数来定,Qt 单个编译单元很吃内存
make -j4 2>&1 | tee build.log
make install
编译完成后先验 host Qt,再验 target Qt:
bash复制# host 侧工具必须能在宿主机直接执行
/opt/qt-host/bin/moc -v
# target 侧 qmake 必须是 aarch64 的 ELF,不能在宿主机上直接跑
file /opt/qt-target/bin/qmake
moc -v 的输出里版本号要和源码目录里 .qmake.conf 或 QT_VERSION 对得上。file 那一步如果显示 x86-64,说明 -extprefix 和 -hostprefix 写反了,装串了目录,这种错很难靠肉眼发现,只能靠这一步卡住。
4. 把代码开发工具接进 Qt Creator:Kit 配置、部署与运行参数
4.1 Kit 的四件套怎么填
Qt Creator 里一个 Kit 实际上是四个独立引用的组合,任何一项指错都会以“构建成功但跑不起来”或者“调试器连不上”的形式表现。
| Kit 项 | 填什么 | 常见错误 |
|---|---|---|
| Compiler | C 和 C++ 分别指向 /opt/toolchain/aarch64/bin/aarch64-linux-gnu-gcc 与 g++ |
误填宿主机 /usr/bin/g++ |
| Debugger | gdb-multiarch,需宿主机 apt 安装 |
填了 x86 版 gdb,连上后无法识别 AArch64 |
| Qt Version | /opt/qt-target/bin/qmake |
填了 /opt/qt-host/bin/qmake |
| Sysroot | /opt/sysroot |
留空,导致补全和跳转失效 |
填之前先在 Qt Creator 的 Devices 里加一个 Generic Linux Device,把板子的地址、用户名、认证方式配好,Kit 里的部署步骤才有落点。这个设备配置还有个隐性作用:Qt Creator 会用它在目标机上执行 uname -m 之类的探测命令,架构对不上时会直接标红。
gdb-multiarch 这一项值得单独说。宿主机自带的 gdb 只认 x86,连上 gdbserver 之后能建立连接,但一读寄存器就报 “architecture not supported”。装完 gdb-multiarch 还要在 Kit 的 Debugger 里把 GDB server executable 相关配置指向它,很多人卡在“能连上但看不到调用栈”就是因为漏了这一步。
4.2 平台插件与环境变量
Qt 程序在板子上启动的第一个动作是加载 QPA 平台插件,插件选不对,程序会先崩在启动阶段,而不是崩在你的业务代码里。
bash复制# eglfs:直接走 KMS/DRM 和 GPU,无桌面环境时的首选
export QT_QPA_PLATFORM=eglfs
# 指定 EGL 后端,接 HDMI 屏幕时一般用 eglfs_kms
export QT_QPA_EGLFS_INTEGRATION=eglfs_kms
# 动态库搜索路径,app 和 Qt 库不在同一目录时必配
export LD_LIBRARY_PATH=/usr/lib:$LD_LIBRARY_PATH
QT_QPA_PLATFORM 的候选值里,linuxfb 是纯 framebuffer 写入,不经过 GPU,只适合验证“窗口能不能出来”;eglfs 才会创建 EGL 上下文,也才有后面 GPU 渲染的余地。板子上如果跑着 Wayland 合成器,则应该用 wayland。这三个值选错的现象不一样:选成 linuxfb 时 OpenGL 相关代码会返回空上下文但不崩,属于最隐蔽的一种翻车。
如果不想每次登录都 export,可以在可执行文件同级放一个 qt.conf:
ini复制[Paths]
Prefix = /usr
Plugins = plugins
Libraries = lib
这个文件会被 Qt 优先读取,用来覆盖编译期写死的路径。部署到不标准目录时,它比一堆环境变量干净。
4.3 部署脚本:先 ldd 再运行
手动 scp 一次两次还行,次数一多必然漏库。写个脚本,把“传上去”和“检查依赖”绑在一起。
bash复制#!/usr/bin/env bash
# deploy.sh:把程序传上去,先查依赖再启动
set -e
TARGET="root@192.168.1.100"
APP="hello"
rsync -avz "./$APP" "$TARGET:/opt/app/"
rsync -avz "/opt/qt-target/lib/" "$TARGET:/usr/lib/"
ssh "$TARGET" "chmod +x /opt/app/$APP"
# 关键:先看有没有 not found,再谈运行
ssh "$TARGET" "ldd /opt/app/$APP | grep 'not found' || echo 'deps ok'"
ssh "$TARGET" "cd /opt/app && QT_QPA_PLATFORM=eglfs ./$APP"
set -e 让任何一步失败都中断,避免“传了一半就启动”。ldd | grep 'not found' 这一行是后悔药:它能提前告诉你缺哪个库,而不是等程序一启动就 error while loading shared libraries 然后你逐个去猜。|| echo 'deps ok' 是必要的,因为 grep 没匹配到时会返回非零,配合 set -e 会把脚本直接终止。
同步 /opt/qt-target/lib/ 这一步在生产环境要慎重,它会覆盖板子上已有的 Qt 库。稳妥做法是只传 ldd 结果里实际用到的那些,或者把 Qt 库放到 /opt/app/lib 下再靠 LD_LIBRARY_PATH 指过去。两种方式各有取舍:覆盖系统库省事但会牵连板子上其他 Qt 程序,独立目录干净但要维护搜索路径。
5. 避坑排查:交叉编译链路上五个高频翻车现场
5.1 程序拷过去直接 Exec format error
现象:./hello 一执行就报 cannot execute binary file: Exec format error,ls -l 看权限正常、文件大小也正常。
原因:可执行文件是 x86-64 的。最常见的来源不是编译器没配对,而是 qmake 用错了——Qt Creator 的 Kit 里 Qt Version 还指着宿主机那份 qmake,make 走的是宿主机的 Makefile,编译器和链接器全是 x86。
解决:file hello 先确认架构,再看构建目录里的 Makefile 第一行 CC、CXX 是不是 aarch64-linux-gnu- 开头。如果 Makefile 是对的但产物还是 x86,那就是增量构建残留,删掉 build 目录从头来。我现在的习惯是 Kit 建完先用这个最小 hello 工程跑一遍,通过了再导入正式工程,省得在一堆业务代码里找环境问题。
5.2 报 error while loading shared libraries
现象:程序在板子上启动,第一行就是 error while loading shared libraries: libQt5Core.so.5: cannot open shared object file。
原因:库没部署,或者部署了但不在动态链接器的搜索路径里。Qt 交叉编译时 -prefix /usr 写的是板子上的路径,如果实际部署到了 /opt/app/lib,运行时就找不到。
解决:板子上执行 ldd /opt/app/hello | grep 'not found',缺哪个补哪个。补齐后如果还在报,用 LD_LIBRARY_PATH=/opt/app/lib ./hello 验证是不是路径问题;确认是路径问题,就在启动脚本里固定这个变量,而不是靠 ldconfig,后者在只读 rootfs 上往往改不动。
5.3 窗口出不来,或者一启动就崩在平台插件
现象:程序能启动,但报 This application failed to start because no Qt platform plugin could be initialized,或者干脆黑屏。
原因:QPA 插件没部署,或者 QT_QPA_PLATFORM 指定的后端板子不支持。-prefix /usr 决定了 Qt 去 /usr/plugins/platforms 找 libqeglfs.so,这个目录如果没同步,插件就是缺的。
解决:先 ls /usr/plugins/platforms/ 看有哪些插件,再确认环境变量指向的插件确实存在。板子上没有 X11 时选 xcb 一定失败;有 GPU 但选了 linuxfb 则窗口能出来、OpenGL 全部返回空上下文,这种“看起来正常”的情况最费时间,只能靠下一章的 GPU 验证手段识别。
5.4 undefined reference to vtable for XXX
现象:编译链接阶段报某个带 Q_OBJECT 的类 undefined reference to vtable for XXX,头文件、cpp 都在,Q_OBJECT 宏也没漏。
原因:moc 生成的代码和链接的 Qt 库版本不一致。典型场景是用宿主机 apt 装的 Qt 里的 moc 去处理头文件,链接的却是自己编的 target Qt。版本差一个补丁号就可能出这个问题。
解决:检查构建目录里 moc 的实际路径,确认它是 /opt/qt-host/bin/moc。在 Qt Creator 里则是检查 Kit 的 Qt Version 是否指向 /opt/qt-target/bin/qmake,因为 moc 的路径是从 qmake 推导出来的。根治办法就是第 3 章说的那份 host Qt,从同一份源码编出来,别图省事复用系统里的。
5.5 编译到一半 g++ 被杀,日志只留一个 Killed
现象:make -j16 跑到某个大文件时进程直接消失,build.log 最后一行只有 Killed,没有任何编译错误。
原因:内存耗尽被 OOM killer 干掉。Qt 的某些编译单元(尤其是带大量模板展开的模块)单个进程能吃好几个 G,并发数拉满必然触发。
解决:make -j4 降并发,或者临时加 swap。判断依据看 dmesg | tail 里有没有 Out of memory: Killed process。这个坑的迷惑性在于它不报编译错误,重跑一次可能换个文件继续被杀,容易被误判成代码问题。
6. GPU 渲染验证:怎么确认 OpenGL 真的跑在板子的 GPU 上
窗口出来了不等于 GPU 在干活。Qt 在没有可用 EGL 上下文时会静默回落到软件光栅化,界面一样刷新,只是 CPU 单核跑满。判断分两层:先看运行时环境,再看实际负载。
第一层查设备节点和 EGL 能力。板子上确认 /dev/dri/card0 或 renderD128 存在,这是 DRM 设备节点,GPU 驱动加载成功的标志。再跑一下系统里自带的 EGL 信息工具(不同发行版名字不一样,有的叫 eglinfo,有的需要自己编一个几行的探测程序),重点看 EGL version 和 vendor 是不是 GPU 厂商而不是 Mesa 的 softpipe/llvmpipe。vendor 显示软件渲染,后面所有优化都是白费。
第二层用最小代码把渲染管线跑通:
cpp复制// glwidget.h:一个只做清屏和刷新的最小 OpenGL 部件
#include <QOpenGLWidget>
#include <QOpenGLFunctions>
#include <QSurfaceFormat>
#include <QTimer>
class GLWidget : public QOpenGLWidget, protected QOpenGLFunctions
{
Q_OBJECT
public:
explicit GLWidget(QWidget *parent = nullptr) : QOpenGLWidget(parent)
{
QSurfaceFormat fmt;
// 板子上走 GLES,不要用桌面 GL,嵌入式驱动对后者支持普遍不完整
fmt.setRenderableType(QSurfaceFormat::OpenGLES);
// 版本别贪高,ES 2.0 是嵌入式 GPU 覆盖最广的一档
fmt.setVersion(2, 0);
// 多重采样,只有真 GPU 上才生效
fmt.setSamples(4);
setFormat(fmt);
connect(&m_timer, &QTimer::timeout, this, QOverload<>::of(&GLWidget::update));
m_timer.start(16); // 约 60 帧,纯软件渲染会立刻吃掉一个核
}
protected:
void initializeGL() override
{
initializeOpenGLFunctions(); // 绑定当前上下文的函数指针
glClearColor(0.1f, 0.1f, 0.12f, 1.0f);
}
void paintGL() override
{
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
// 真正的绘制放这里:顶点着色器 + 片元着色器全部在 GPU 上执行
}
private:
QTimer m_timer;
};
setRenderableType 决定 EGL 创建的是 GLES 上下文还是桌面 GL 上下文,设错会直接拿不到上下文,initializeOpenGLFunctions 返回后所有 gl 调用都是空操作;setVersion 设成驱动不支持的版本,initializeGL 里会静默失败,界面上表现为一块纯色区域,不报错;setSamples(4) 是最好用的判据之一——软件光栅化下抗锯齿要么不生效要么极慢,肉眼能看出边缘锯齿和帧率差异。
跑起来之后在板子上开一个 top,看这个进程的 CPU 占用。60 帧的纯清屏如果吃掉接近一个核,基本可以判定没走 GPU;正常应该是个位数到十几的占用。这个判据不需要任何专业工具,但比看日志靠谱得多。
从那次在板子前盯了两小时“为什么界面这么卡”之后,我每次配完 Kit 都强制先跑一遍这个最小部件,CPU 占用正常了再碰业务代码。交叉编译这条路上,环境问题永远比代码问题多,早一步把环境验证固化成习惯,后面就少一次半夜翻 build.log。希望帮到你。
