在树莓派上从源码构建QT6

这篇文章将指导你在树莓派上从源码构建 QT6。QT 是一个跨平台的应用程序框架，开发者可以在包括树莓派在内的各种平台上运行的用户界面和应用程序。

准备工作

硬件要求

你需要准备以下硬件：

• 一台树莓派（32 位或 64 位均可）
• 一张安装了树莓派操作系统的 SD 卡
• 一根网线或 Wi-Fi 连接
• 一台可以访问树莓派的电脑

软件要求

你需要在树莓派上安装以下软件：

• 树莓派操作系统（基于 Debian 12 Bookworm）
• 构建工具和编译器工具（cmake 和 ninja-build）

你可以使用以下命令安装这些软件包：

sudo apt update
sudo apt install build-essential cmake ninja-build

安装必要的构建依赖项

你需要安装大量的软件包才能构建 QT 6.6。一些 QT 6.6 的功能是可选的，可以根据你的特定需求选择是否包含。

首先，更新你的 apt 软件包缓存：

sudo apt update

然后继续安装以下必需的软件包：

开发包	说明
libfontconfig1-dev	字体配置库
libharfbuzz-dev	OpenType 文本整形引擎
libdbus-1-dev	D-Bus 库
libfreetype6-dev	字体引擎库
libicu-dev	Unicode 库
libinput-dev	输入设备处理
libxkbcommon-dev	XKB 编译器库
libsqlite3-dev	sqlite3 数据库驱动程序
libpng-dev	PNG 图像支持
libssl-dev	OpenSSL 支持
libjpeg-dev	JPEG 图像支持
libglib2.0-dev	glib 主循环支持

你可以使用以下命令安装所有必需的开发包：

sudo apt install libfontconfig1-dev libharfbuzz-dev libdbus-1-dev libfreetype6-dev libicu-dev libinput-dev libxkbcommon-dev libsqlite3-dev libssl-dev libpng-dev libjpeg-dev libglib2.0-dev

树莓派图形环境和驱动程序选项

在 QT 6 中，你将只能使用 Mesa 和 V3D、VC4 驱动程序，因为树莓派操作系统和 QT 6 都放弃了对博通专有 EGL blob 的支持。

图形驱动程序选项

图形驱动程序	所需软件包	说明
V3D 和 VC4 驱动程序	libgles2-mesa-dev libgbm-dev libdrm-dev	QT_FEATURE_kms=ON QT_FEATURE_opengles2=ON QT_FEATURE_opengles3=ON
仅在树莓派 4 和 5 上支持 V3D 驱动程序的 Vulkan	libvulkan-dev vulkan-tools	QT_FEATURE_vulkan=ON
X11	见下文	QT_FEATURE_xcb=ON
Wayland	见下文	请注意，Wayland 支持位于 qtwayland 子模块中。

可选的基础功能依赖项

某些功能并非严格必需，但可能仍然很实用，例如对 webp 图像格式的支持是可选的，但如今它已经被广泛使用，因此可能最好将其包含在内。

下表列出了一些可选功能以及需要安装的必需开发包。

基础 QT 的可选功能

可选功能	要安装的软件包	配置选项
对数据库 PostgreSQL 的支持	libpq-dev
对数据库 MariaDB /MySQL 的支持	libmariadb-dev libmariadb-dev-compat
使用 CUPS 进行打印支持	libcups2-dev
X11 支持	libx11-dev libxcb1-dev libxext-dev libxi-dev libxcomposite-dev libxcursor-dev libxtst-dev libxrandr-dev libx11-xcb-dev libxext-dev libxfixes-dev libxi-dev libxrender-dev libxcb1-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 libxcb-util0-dev libxcb-xinerama0-dev libxcb-xkb-dev libxkbcommon-dev libxkbcommon-x11-dev libxcb-xinput-dev libxcb-cursor-dev	QT_FEATURE_xcb=ON
Wayland	libwayland-dev
	libzstd libzstd-dev
GTK 3 主题支持	libgtk-3-dev
辅助功能	libatspi2.0-dev
SCTP 流控制传输协议	libsctp-dev	QT_FEATURE_LABEL_sctp

使用 apt install 从上表中安装你需要的功能所需的任何软件包。

构建 QT 6.6 基础模块

QT Base 提供了 QT 的核心部分，需要在其他任何东西之前构建和安装。

下载 QT 6.6 基础源码

wget https://download.qt.io/official_releases/qt/6.6/6.6.3/submodules/qtbase-everywhere-src-6.6.3.tar.xz

配置、构建和安装 QT 6.6 基础模块

解压源码：

tar xf qtbase-everywhere-src-6.6.3.tar.xz

创建一个构建目录：

mkdir qtbasebuild && cd qtbasebuild

可选：创建一个 cmake 工具链文件

如果你要为与构建时不同的体系结构类型构建，例如，你将在基于 armv6 的 Pi 上运行 QT，但在速度更快的设备（armv7 或 armv8）上构建，则可能需要创建一个 cmake 工具链文件。

注意： 如果 QT 6 构建将在与构建相同的体系结构上运行，则不需要这样做。例如，你正在 32 位 armv7 Pi 上构建，并打算在 armv7 或更高版本上运行 QT，则不需要工具链文件。

要创建一个名为 tc.cmake 的 cmake 工具链文件，请启动你喜欢的编辑器。在不会被删除的地方创建该文件，例如在你使用的安装前缀中，因为它将在安装时被 QT 构建文件引用。文件的内容取决于目标体系结构（注意：仅测试了 armv7）：

CMAKE_TOOLCHAIN_FILE 示例

体系结构	工具链文件内容
对于 armv6	set(CMAKE_CROSSCOMPILING FALSE) set(CMAKE_SYSTEM_NAME Linux) set(CMAKE_SYSTEM_PROCESSOR armv6) set(TARGET armv6-linux-eabi)
对于 armv7	set(CMAKE_CROSSCOMPILING FALSE) set(CMAKE_SYSTEM_NAME Linux) set(CMAKE_SYSTEM_PROCESSOR armv7) set(TARGET armv7-linux-eabi)
对于 armv8	set(CMAKE_CROSSCOMPILING FALSE) set(CMAKE_SYSTEM_NAME Linux) set(CMAKE_SYSTEM_PROCESSOR armv8) set(TARGET armv8-linux-eabi)
对于 aarch64	待定

配置选项

构建 QT 时可以通过多种方式对其进行定制，下表显示了在配置构建时可以使用的一些选项。

选项	说明
QT_FEATURE_opengles2=ON	使用 OpenGL ES 2.0
QT_FEATURE_opengles3=ON	使用 OpenGL ES 3.0
QT_FEATURE_kms=ON	使用内核模式设置
QT_FEATURE_vulkan=ON	使用 Vulkan 驱动程序
QT_QPA_DEFAULT_PLATFORM=eglfs	将默认平台插件设置为 eglfs
BUILD_WITH_PCH=OFF	禁用预编译头文件

配置 QT 6.6 构建

然后运行配置（根据需要调整前缀，根据需要添加/删除任何配置选项，如果未使用，则删除 CMAKE_TOOLCHAIN_FILE 参数，等等）：

cmake -G Ninja \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX= */opt/Qt/6.6*  \
-DQT_FEATURE_opengles2=ON \
-DQT_FEATURE_opengles3=ON \
-DQT_FEATURE_kms=ON \
-DQT_FEATURE_xcb=ON \
-DQT_FEATURE_vulkan=ON \
*-DCMAKE_TOOLCHAIN_FILE=tc.cmake*  \
-DQT_AVOID_CMAKE_ARCHIVING_API=ON ../qtbase-everywhere-src-6.6.3

检查配置摘要输出，确保已成功检测到所有必需内容，如果成功，则可以开始构建 QT。

构建 QT 6.6 基础模块

接下来是实际编译源码，我们将使用以下命令执行此操作，根据需要调整示例并行构建（4）。

注意： 在单核或低内存系统上，不建议进行并行构建。

cmake --build . --parallel 4

安装 QT 6.6 基础模块

构建成功完成后，下一步是将结果安装到系统中。要安装已编译的 QT，请运行：

cmake --install .

构建 QT 文档

QDoc 是构建和安装文档以供各种 GUI 工具使用的必需工具。QDoc 是 qttools 子模块的一部分，显然需要 QT 本身才能构建。文档可以在之后从构建树中构建，因此如果你确实需要文档，请暂时不要删除任何构建结果。

使用以下命令构建文档：

cmake --build . --parallel 4 --target docs

并使用以下命令安装：

cmake --build . --target install_docs

QT 基础模块的构建时间

QT 基础模块在各种系统上的构建时间比较

模块	Pi 5	Pi 4	32-bit RISC-V SoC	Rockchip RK3328	Pi 3	AMD Ryzen 3600X
qtbase	~40 分钟	~50 分钟	~3 小时			~6 分钟

构建 QT 子模块

你可以使用以下命令快速配置、构建和安装 QT 子模块（为什么不在简单的 for 循环中完成，我将把它留给读者作为练习！）：

/opt/Qt/6.6/bin/qt-configure-module . && cmake --build . --parallel 4 && cmake --install .

有关构建子模块的更深入教程，请参阅 QT 子模块构建教程。

结论

在本教程中，我们学习了如何在树莓派上从源码构建 QT 6.6。我们涵盖了安装必要的依赖项、配置构建过程以及构建和安装 QT 基础模块和子模块。现在你应该能够在树莓派上开发和运行基于 QT 的应用程序。