小皮匠

外观

QT交叉编译

2025-06-30

这是在Ubuntu20上交叉编译Qt 5.15.2，并将其安装在Raspberry Pi CM4 上的指南。

随着软件和硬件的每次更新，一些文章的指引似乎都有些过时，或者不全，或者不准确。

因此，这里提供一个完整的流程,并对关键部分进行了必要的说明。

相比其他文档，本文档升级的交叉编译器版本，及对64位QT的支持。

准备工作

不同硬件、不同版本、不同架构、不能混用！

不同硬件、不同版本、不同架构、不能混用！

不同硬件、不同版本、不同架构、不能混用！

这是很多小伙伴踩坑的地方，比如参照最新的bookworm，或buster文档，对bullseye版本操作，导致奇怪的问题。

请务必根据自己的硬件、软件版本、架构等情况进行调整，以下是笔者的配置。

所以当你遇到问题时，请务必先检查文档是否与你使用的各个版本一致。

Raspberry Pi OS是基于debian的，所以不同的Raspberry Pi OS对应debian版本如下。

Raspberry Pi OSdebian
最新12 (bookworm)
本文11 (bullseye)
旧版10 (buster)

硬件

软件

树莓派CM4

选择其中一个架构进行烧录，不同的架构，部分命令有所区别，请注意分辨。

32位镜像：2025-05-06-raspios-bullseye-armhf.img.xz 大小: 948306000 字节 : 904 MiB 64位镜像：·2025-05-06-raspios-bullseye-arm64.img.xz 大小: 892209344 字节 : 850 MiB

这里假设已经完成一些便捷的配置，如：SSH,VNC服务等。

注意，一些文档在 buster 或之前的版本要求开启KMS，而在 bullseye 或之后的版本不需要。

增加源码包的支持。


32位架构：
编辑 `/etc/apt/sources.list` 文件，取消对deb-src的注释
deb http://raspbian.raspberrypi.org/raspbian/ bullseye main contrib non-free rpi
# Uncomment deb-src lines below then 'apt-get update' to enable 'apt-get source'
deb-src http://raspbian.raspberrypi.org/raspbian/ bullseye main contrib non-free rpi


64位架构：
编辑 `/etc/apt/sources.list` 文件，取消对deb-src的注释
deb http://deb.debian.org/debian bullseye main contrib non-free
deb http://security.debian.org/debian-security bullseye-security main contrib non-free
deb http://deb.debian.org/debian bullseye-updates main contrib non-free
# Uncomment deb-src lines below then 'apt-get update' to enable 'apt-get source'
deb-src http://deb.debian.org/debian bullseye main contrib non-free
deb-src http://security.debian.org/debian-security bullseye-security main contrib non-free
deb-src http://deb.debian.org/debian bullseye-updates main contrib non-free

32位和64位架构，都需要编辑 `/etc/apt/sources.list.d/raspi.list` 文件，取消对deb-src的注释
deb http://archive.raspberrypi.org/debian/ bullseye main
# Uncomment deb-src lines below then 'apt-get update' to enable 'apt-get source'
deb-src http://archive.raspberrypi.org/debian/ bullseye main

目前官方的源已经很快了，如果一定要更换，请参考如下内容，注意32位和64位的区别。

# 对于32位系统，编辑 `/etc/apt/sources.list` 文件，删除原文件所有内容，用以下内容取代
deb http://mirrors.tuna.tsinghua.edu.cn/raspbian/raspbian/ bullseye main non-free contrib rpi
deb-src http://mirrors.tuna.tsinghua.edu.cn/raspbian/raspbian/ bullseye main non-free contrib rpi

# 对于64位系统 编辑 `/etc/apt/sources.list` 文件，用以下内容取代的：
deb https://mirrors.tuna.tsinghua.edu.cn/debian/ bullseye main contrib non-free
deb-src https://mirrors.tuna.tsinghua.edu.cn/debian/ bullseye main contrib non-free
deb https://mirrors.tuna.tsinghua.edu.cn/debian/ bullseye-updates main contrib non-free
deb-src https://mirrors.tuna.tsinghua.edu.cn/debian/ bullseye-updates main contrib non-free
deb https://mirrors.tuna.tsinghua.edu.cn/debian/ bullseye-backports main contrib non-free
deb-src https://mirrors.tuna.tsinghua.edu.cn/debian/ bullseye-backports main contrib non-free
deb https://mirrors.tuna.tsinghua.edu.cn/debian-security bullseye-security main contrib non-free
deb-src https://mirrors.tuna.tsinghua.edu.cn/debian-security bullseye-security main contrib non-free

# 对于两个架构，编辑 `/etc/apt/sources.list.d/raspi.list` 文件，删除原文件所有内容，用以下内容取代：
deb http://mirrors.tuna.tsinghua.edu.cn/raspberrypi/ bullseye main
deb-src http://mirrors.tuna.tsinghua.edu.cn/raspberrypi/ bullseye main

然后使用以下命令更新系统并安装所需的Qt和开发包

sudo apt-get update
sudo apt-get upgrade
sudo apt-get build-dep qt5-qmake libqt5gui5 libqt5webengine-data libqt5webkit5
sudo apt-get install libudev-dev libinput-dev libts-dev libxcb-xinerama0-dev libxcb-xinerama0 gdbserver

注意build-dep和install的区别。

命令功能安装内容典型用途
apt-get install安装预编译的二进制软件包可直接运行的软件普通软件安装
apt-get build-dep安装软件编译依赖源代码编译所需的库和工具从源代码编译软件

创建一个qt5.15的安装目录，注意修改替换pi为你的用户名

sudo mkdir /usr/local/qt5.15
sudo chown -R pi:pi /usr/local/qt5.15

ubuntu宿主机

首先，更新Ubuntu20并安装一些必需的库。如果你用的时ubuntu22 或更高版本，以下内容不适用。

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install gcc git bison python gperf pkg-config gdb-multiarch
sudo apt install build-essential

其他的一些工具
sudo apt-get install open-vm-tools open-vm-tools-desktop
sudo apt-get install openssh-server net-tools vim fcitx fcitx-googlepinyin

对于所需的文件，我在/opt 下创建以下目录结构

sudo mkdir /opt/raspi
sudo mkdir /opt/raspi/build
sudo mkdir /opt/raspi/tools
sudo mkdir /opt/raspi/sysroot
sudo mkdir /opt/raspi/sysroot/usr
sudo chown -R 1000:1000 /opt/raspi
cd /opt/raspi

下载Qt资源,或通过其他方式导入，并将其解压缩到raspi目录中

cd /opt/raspi
wget http://download.qt.io/archive/qt/5.15/5.15.2/single/qt-everywhere-src-5.15.2.tar.xz
tar xfv qt-everywhere-src-5.15.2.tar.xz

现在我们需要稍微修改一下mkspec文件，以便我们可以在编译器中使用它。为此，请运行以下命令

cd /opt/raspi
cp -R qt-everywhere-src-5.15.2/qtbase/mkspecs/linux-arm-gnueabi-g++ qt-everywhere-src-5.15.2/qtbase/mkspecs/linux-arm-gnueabihf-g++
sed -i -e 's/arm-linux-gnueabi-/arm-linux-gnueabihf-/g' qt-everywhere-src-5.15.2/qtbase/mkspecs/linux-arm-gnueabihf-g++/qmake.conf

64位架构 需要额外的以下修改 
cp -R qt-everywhere-src-5.15.2/qtbase/mkspecs/devices/linux-rasp-pi4-v3d-g++/ qt-everywhere-src-5.15.2/qtbase/mkspecs/devices/linux-rasp-pi4-64-v3d-g++/
sed -i -e 's/-mfpu=crypto-neon-fp-armv8//g' qt-everywhere-src-5.15.2/qtbase/mkspecs/devices/linux-rasp-pi4-64-v3d-g++/qmake.conf
sed -i -e 's/hard-float/aarch64/g' qt-everywhere-src-5.15.2/qtbase/mkspecs/devices/linux-rasp-pi4-64-v3d-g++/qmake.conf

交叉编译器没有选择 gcc-linaro-7.4.1 同时官方tools 也介绍 These toolchains are deprecated.

根据官方推荐，安装32位和64位架构的交叉编译器

sudo apt-get install gcc-arm-linux-gnueabihf g++-arm-linux-gnueabihf
sudo apt-get install gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

将树莓派原始库，通过rsync将其复制到宿主机的sysroot目录中,注意将用户及IP地址替换为你的实际值

cd /opt/raspi/
rsync -avz --rsync-path="sudo rsync" --delete pi@192.168.1.134:/lib sysroot/
rsync -avz --rsync-path="sudo rsync" --delete pi@192.168.1.134:/usr/include sysroot/usr/
rsync -avz --rsync-path="sudo rsync" --delete pi@192.168.1.134:/usr/lib sysroot/usr/
rsync -avz --rsync-path="sudo rsync" --delete pi@192.168.1.134:/usr/share sysroot/usr/

在buster版本之前，需要复制/opt/vc，在bullseye版本之后，不需要。

rsync -avz --rsync-path="sudo rsync" --delete pi@192.168.1.134:/opt/vc sysroot/opt/

清理rsync复制的符号链接，指向正确的原始文件。参考其他文章下载Python脚本，并执行它。

wget https://raw.githubusercontent.com/riscv/riscv-poky/master/scripts/sysroot-relativelinks.py
sudo chmod +x sysroot-relativelinks.py
./sysroot-relativelinks.py sysroot

现在我们可以配置构建并编译它

cd /opt/raspi/build

32位架构
../qt-everywhere-src-5.15.2/configure -release -opengl es2 -eglfs -kms -no-feature-eglfs_brcm -device linux-rasp-pi4-v3d-g++ -device-option CROSS_COMPILE=arm-linux-gnueabihf- -sysroot /opt/raspi/sysroot -prefix /usr/local/qt5.15 -extprefix /opt/raspi/qt5.15 -opensource -confirm-license -skip qtscript -skip qtwayland -skip qtwebengine -nomake tests -make libs -pkg-config -no-use-gold-linker -v -recheck

64位架构
../qt-everywhere-src-5.15.2/configure -release -opengl es2 -eglfs -kms -no-feature-eglfs_brcm -device linux-rasp-pi4-64-v3d-g++ -device-option CROSS_COMPILE=aarch64-linux-gnu- -sysroot /opt/raspi/sysroot -prefix /usr/local/qt5.15 -extprefix /opt/raspi/qt5.15 -opensource -confirm-license -skip qtscript -skip qtwayland -skip qtwebengine -nomake tests -make libs -pkg-config -no-use-gold-linker -v -recheck

对比buster版本,这里的配置 -mks 与 -no-feature-eglfs_brcm 是新增的。

大致的原因新版系统默认不再使用 Broadcom 的专有 VideoCore 驱动，而是改用 标准 DRM/KMS（Mesa）驱动。

几分钟后，脚本应该完成，并且应该设置或不设置以下EGLFS条件

QPA backends:
  DirectFB ............................... no
  EGLFS .................................. yes [SHOULD BE YES]
  EGLFS details:
    EGLFS OpenWFD ........................ no
    EGLFS i.Mx6 .......................... no
    EGLFS i.Mx6 Wayland .................. no
    EGLFS RCAR ........................... no
    EGLFS EGLDevice ...................... yes [SHOULD BE YES]
    EGLFS GBM ............................ yes
    EGLFS VSP2 ........................... no
    EGLFS Mali ........................... no
    EGLFS Raspberry Pi ................... no [SHOULD BE NO]
    EGLFS X11 ............................ yes
  LinuxFB ................................ yes
  VNC .................................... yes
  XCB:
    Using system-provided xcb-xinput ..... yes
    Native painting (experimental) ....... no
    GL integrations:
      GLX Plugin ......................... no
      EGL-X11 Plugin ..................... yes

完整输出

如果不是这种情况，或者出现任何其他错误消息，请检查并清理build下的文件，然后重新配置。

如果你想改变一些变量再次配置，也需要事先删除构建目录的内容。

如若不然，会产生一些奇奇怪怪的问题。

如果一切正常，则运行make和make install命令。

make -j$(nproc)
make install

如果编译成功，编译后的文件（它们位于/opt/raspi/qt5.15目录中）可以复制到Raspberry Pi。同样，我们使用rsync命令来执行此操作。

cd /opt/raspi/
rsync -avz --rsync-path="sudo rsync" qt5.15 pi@192.168.1.134:/usr/local/

如果树莓派空间很小，也可以重新烧录后在复制，以移除不需要的库和工具。大概节省700MB左右的空间。

QtCreator配置

在树莓派上，我们需要配置QtCreator以使用我们刚刚编译的Qt。

首先，我们需要安装QtCreator。

sudo apt-get install qtcreator

接下来正常配置即可

架构gccg++
32位arm-linux-gnueabihf-g++arm-linux-gnueabihf-g++
64位aarch64-linux-gnu-gccaarch64-linux-gnu-g++

QtCreator运行时需要添加额外的环境变量

设置 DISPLAY 到 :0
设置 QT_QPA_PLATFORM 到 xcb

参考的链接

  1. Qt 5.15 cross compile for Raspberry Compute Module 4 on Ubuntu 20 LTS
  2. Cross-Compiling-Qt-for-Raspberry-Pi-4
  3. ubuntu虚拟机为树莓派5交叉编译Qt5并实现远程开发
  4. Building Qt 5 from Git
贡献者: yulc