Ubuntu下为嵌入式设备搭建aarch64架构的Qt交叉编译环境

1. 为什么需要交叉编译环境

在嵌入式开发中，我们经常会遇到一个头疼的问题：开发机的CPU架构和目标设备不一样。比如你的Ubuntu电脑是x86_64架构，而树莓派4B或者RK3588开发板却是aarch64架构。这就好比你想用中文写一篇文章给只会英文的人看，中间必须有个翻译过程。

交叉编译就是这个"翻译官"。它能让你在x86电脑上编译出直接在arm板子上运行的程序。我刚开始接触嵌入式Qt开发时，每次修改代码都要拷贝到板子上编译，效率低得让人抓狂。后来搭建好交叉编译环境后，开发效率直接翻倍。

这里有个常见的误区：很多人以为只要在Ubuntu上装个arm版的gcc就行了。实际上，Qt作为大型框架，需要整套工具链和环境配合。就像做菜不光要有锅，还得配好灶台、调料和菜刀。

2. 搭建编译工具链

2.1 选择交叉编译器

Linaro提供的GCC工具链是arm开发的首选，就像Android开发首选Android Studio一样。但官网版本多得让人眼花，我当初就选错过版本导致编译失败。关键要认准这几个参数：

• aarch64：64位ARM架构
• linux-gnu：Linux系统
• x86_64：表示这个编译器本身运行在x86电脑上

最新稳定版是gcc-linaro-11.3.1，下载命令：

bash复制wget https://releases.linaro.org/components/toolchain/binaries/11.3-2022.05/aarch64-linux-gnu/gcc-linaro-11.3.1-2022.05-x86_64_aarch64-linux-gnu.tar.xz

2.2 安装配置工具链

解压安装其实有讲究，我建议按这个步骤来：

bash复制# 创建专用目录
sudo mkdir -p /opt/toolchains
# 解压到指定位置
tar -xvf gcc-linaro-11.3.1-2022.05-x86_64_aarch64-linux-gnu.tar.xz -C /opt/toolchains
# 添加环境变量
echo 'export PATH=$PATH:/opt/toolchains/gcc-linaro-11.3.1-2022.05-x86_64_aarch64-linux-gnu/bin' >> ~/.bashrc
source ~/.bashrc

验证安装是否成功：

bash复制aarch64-linux-gnu-gcc --version

如果看到版本信息就说明工具链装好了。这里有个坑：有些Ubuntu版本默认没装multilib库，会导致工具链报错。解决方法：

bash复制sudo apt install gcc-multilib g++-multilib

3. 准备Qt源码

3.1 下载Qt源码

Qt官网提供了各种版本的源码包，我推荐用5.15.2这个LTS版本，稳定性和兼容性都经过验证：

bash复制wget https://download.qt.io/archive/qt/5.15/5.15.2/single/qt-everywhere-src-5.15.2.tar.xz

解压源码时建议用这个命令，可以保留文件权限：

bash复制tar -xJf qt-everywhere-src-5.15.2.tar.xz

3.2 配置编译参数

进入源码目录后，最关键的是configure配置。这是我经过多次尝试后总结的黄金配置：

bash复制./configure \
-prefix /opt/qt5.15.2-arm64 \
-xplatform linux-aarch64-gnu-g++ \
-opensource -confirm-license \
-release \
-nomake examples -nomake tests \
-skip qt3d -skip qtwebengine \
-qt-libjpeg -qt-libpng \
-no-opengl \
-no-icu \
-no-pch

参数说明：

• -prefix：指定安装路径
• -xplatform：选择目标平台配置
• -skip：跳过不需要的模块可以大幅缩短编译时间
• -no-opengl：嵌入式设备通常不需要OpenGL

4. 编译和安装

4.1 解决依赖问题

编译前先安装这些依赖包，否则会遇到各种奇怪错误：

bash复制sudo apt install build-essential libgl1-mesa-dev libglu1-mesa-dev \
libxkbcommon-dev libxcb-xinerama0-dev libxcb-xinerama0 \
libfontconfig1-dev libfreetype6-dev libx11-dev libxext-dev \
libxfixes-dev libxi-dev libxrender-dev libxcb1-dev \
libx11-xcb-dev libxcb-glx0-dev libxcb-keysyms1-dev \
libxcb-image0-dev libxcb-shm0-dev libxcb-icccm4-dev \
libxcb-sync-dev libxcb-xfixes0-dev libxcb-shape0-dev \
libxcb-randr0-dev libxcb-render-util0-dev

4.2 开始编译

使用多线程编译能节省大量时间，但线程数不是越多越好，一般用CPU核心数的1.5倍：

bash复制make -j$(($(nproc) * 3 / 2))

编译过程可能要1-2小时，建议用nohup防止终端断开：

bash复制nohup make -j$(($(nproc) * 3 / 2)) > build.log 2>&1 &
tail -f build.log  # 实时查看编译日志

4.3 安装到系统

编译完成后安装到之前指定的目录：

bash复制sudo make install

安装完成后检查生成的文件：

bash复制readelf -h /opt/qt5.15.2-arm64/lib/libQt5Core.so.5

应该能看到Machine: AArch64的输出。

5. 配置开发环境

5.1 设置Qt Creator

在Qt Creator中添加我们编译的Qt版本：

1. 打开Tools > Options > Kits
2. 添加新的Qt Version，选择/opt/qt5.15.2-arm64/bin/qmake
3. 创建新的Kit，设置：
   • Device type: Generic Linux Device
   • Compiler: 选择我们安装的aarch64-gcc和g++
   • Qt version: 选择刚添加的版本

5.2 测试交叉编译

创建简单的HelloWorld项目，选择我们配置的Kit进行编译。编译完成后用file命令检查生成的可执行文件：

bash复制file helloworld

应该显示ELF 64-bit LSB executable, ARM aarch64。

6. 常见问题解决

6.1 编译中途报错

遇到编译错误时不要慌，先看错误信息。常见问题有：

1. 头文件缺失：通常是缺少开发包，用apt安装对应的-dev包
2. 链接失败：检查库路径是否正确，特别是交叉编译器的sysroot
3. 内存不足：虚拟机编译时容易遇到，可以尝试减少make的线程数

6.2 程序运行异常

交叉编译的程序在目标板子上运行时报错，可以这样排查：

1. 用ldd检查依赖：

   bash复制aarch64-linux-gnu-ldd your_program
   

2. 确保所有依赖库都拷贝到了板子上
3. 检查板子的libc版本是否和工具链匹配

6.3 性能优化技巧

经过多次实践，我发现这些优化很有效：

1. 使用ccache加速重复编译：

   bash复制sudo apt install ccache
   export CCACHE_DIR="/tmp/ccache"
   export CC="ccache aarch64-linux-gnu-gcc"
   export CXX="ccache aarch64-linux-gnu-g++"
   

2. 选择性编译模块，只编译需要的组件
3. 使用distcc分布式编译（适合团队开发）

7. 进阶配置

7.1 添加第三方库

实际项目中经常需要集成第三方库，比如sqlite、openssl等。交叉编译这些库的方法：

bash复制# 以openssl为例
wget https://www.openssl.org/source/openssl-1.1.1q.tar.gz
tar -xzf openssl-1.1.1q.tar.gz
cd openssl-1.1.1q
./Configure linux-aarch64 --prefix=/opt/openssl-arm64 --cross-compile-prefix=aarch64-linux-gnu-
make -j$(nproc)
sudo make install

然后在Qt的configure参数中添加：

code复制-openssl-linked -I /opt/openssl-arm64/include -L /opt/openssl-arm64/lib

7.2 使用sysroot

当目标板子有完整的根文件系统时，可以创建sysroot提高兼容性：

bash复制# 从板子上拷贝系统文件
rsync -avz root@board:/lib /opt/sysroot/
rsync -avz root@board:/usr /opt/sysroot/

# 配置时添加sysroot参数
-sysroot /opt/sysroot

8. 实际项目经验

在最近的一个工业HMI项目中，我们团队用这套环境开发了基于RK3588的Qt应用。踩过几个坑值得分享：

1. 字体问题：板子上缺少字体导致界面显示异常，解决方法是将字体打包到资源文件：

   qrc复制<RCC>
     <qresource prefix="/fonts">
       <file>fonts/wqy-microhei.ttc</file>
     </qresource>
   </RCC>
   

2. 触摸屏校准：不同设备的触摸事件坐标可能需要转换，可以用QTransform处理：

   cpp复制QTransform transform;
   transform.scale(2.0, 2.0);  // 示例缩放
   installEventFilter(this);
   

3. 性能调优：关闭不必要的动画效果，使用QWidget代替QML能显著提升低端设备性能