什么是 Qt？

Qt 是一個跨平臺 C++ 圖形用戶界面應用程序開發框架，可構建高性能的桌面、移動及 Web 應用程序，也可用于開發非 GUI 程序，比如控制臺工具和服務器。Qt 是面向對象的框架，使用特殊的代碼生成擴展以及一些宏，Qt 很容易擴展，并且允許真正的組件編程。

Qt 因其模塊化程度高，可重用性好，可以快速上手等特點，成為了一款非常受歡迎的開發框架。

Ubuntu 18/20 部署

Firefly 針對 Firefly 產品上運行的 Ubuntu 18/20 系統提供了對應的 Qt 環境包，可以快速部署、開發。兩個系統的環境包不通用，請根據你的 Firefly 設備所運行的系統版本，選擇對應的環境包。

環境包請點擊此處下載，提取碼：FFQT

環境包采用交叉編譯的模式，在一個平臺上生成另一個平臺上的可執行代碼。我們需要在 x86_64 架構的 Linux 電腦上進行開發和編譯，并將編譯生成的可執行文件放到 Arm64 架構的目標設備上運行，所以環境包需要往主機端和設備端都部署一遍。

注意：不同版本的環境包有些許差別，后面的部署和環境準備部分只能取一種進行講解，具體使用時請查看環境包內自帶的文檔。

主機端部署

關于主機端的選擇：請使用和目標設備有相同系統的主機進行開發。

例如：需要給運行 Ubuntu 20 的 Firefly 設備開發 Qt 程序，那么主機也應該選擇系統為 Ubuntu 20 的電腦。

1. 開始部署

解壓環境包到電腦后，cd 到解壓出來的目錄中，開始進行部署。主要分為 3 步：

#將文件復制到系統/opt/目錄下cp -rfd firefly_qt5.15_arm64_20.04 /opt/
# 將 sysroot 也復制到 /opt/ 目錄下cp -rfd sysroot /opt/
# 復制環境變量文件到 /etc/profile.d/ 下cphost/host_qtEnv.sh/etc/profile.d/

2. 環境準備

安裝交叉編譯器。

sudo apt updatesudo apt install -y crossbuild-essential-arm64

然后重新登錄或者重啟電腦，以確保之前復制的環境變量能生效。

3. 驗證

環境壓縮包中還附帶一個 example 文件夾，里面包含幾個簡單的 Qt demo，可以用于驗證環境是否搭建成功。一切正常則說明環境部署成功。

# 例如使用 analogclock 來驗證cd example/analogclock
# 執行 qmake 自動生成編譯系統qmake
# 執行 make 開始編譯make

設備端部署

1. 開始部署

解壓環境包到設備后，cd 到解壓出來的目錄中，開始進行部署。主要分為 2 步：

# 將 ext 部分復制到系統的 /opt/ 目錄下，注意此處順便是將 ext 重命名成了 firefly_qt5.15cp -rfd firefly_qt5.15_arm64_20.04/ext /opt/firefly_qt5.15
# 復制環境變量文件到 /etc/profile.d/ 下cp target/target_qtEnv.sh /etc/profile.d/

2. 環境準備

設備上還需要安裝一些必要的庫：

apt install -y libmtdev1 libinput10 libxkbcommon0 \ libdouble-conversion3 libicu66 libharfbuzz0b \ libwebpdemux2 libwebpmux3

打開`/etc/profile.d/target_qtEnv.sh`可以看到其中有三部分注釋掉的環境變量：

#XCB#export QT_QPA_PLATFORM=XCB#export QT_QPA_EGLFS_INTEGRATION=XCB_EGL
#LinuxFB#export QT_QPA_PLATFORM=LINUXFB#export QT_QPA_FB_DRM=1
#EGLFS#export QT_QPA_PLATFORM=EGLFS#export QT_QPA_EGLFS_INTEGRATION=EGLFS_KMS #in minimal ubuntu, use eglfs_kms.#export QT_QPA_EGLFS_KMS_ATOMIC=1 #use drm atomic api or legacy api(two different)#export QT_QPA_EGLFS_HIDECURSOR=1 #hide cursor

根據你想使用的 QPA_PLATFORM 來取消對應部分的注釋。比如 Ubuntu 環境一般使用 XCB，取消這部分的注釋，然后保存并退出編輯。

#XCBexport QT_QPA_PLATFORM=XCBexport QT_QPA_EGLFS_INTEGRATION=XCB_EGL

如果使用 XCB 的話，還需要安裝一些額外的庫：

apt install -y libxcb-icccm4 libxcb-image0 libxcb-shm0 \ libxcb-keysyms1 libxcb-render0 libxcb-render-util0 \ libxcb-shape0 libxcb-sync1 libxcb-xfixes0 \ libxcb-xinerama0 libxcb-xkb1 libxcb-randr0 \ libsm6 libice6 libxkbcommon-x11-0

最后執行 reboot 重啟設備。

3. 驗證

將之前在主機端編譯好的可執行文件，轉移到設備端運行；如果運行正常，則說明設備端環境搭建成功。

LD_LIBRARY_PATH=/opt/firefly_qt5.15/lib ./analogclock

Ubuntu 22 部署

如果目標 Firefly 設備運行的是 Ubuntu 22 系統，則不需要交叉編譯開發，安裝 Qt 更加簡單方便。

Firefly 針對 Ubuntu 22 將 Qt 環境做成了 deb 包，在目標設備上使用 apt 即可安裝：

# 安裝基礎環境apt updateapt install -y qtcreator qtbase5-dev
# 根據開發需要，安裝額外的 Qt 組件與開發環境，例如apt install -y libqt5multimedia5 qtmultimedia5-dev libqt5quick5 qtdeclarative5-dev

Qt Creator 的配置

Qt 開發常使用 Qt Creator 作為 IDE，前文中我們搭建了 Qt 開發環境，那么接下來將介紹如何確保 Qt Creator 能使用我們建好的環境，而不是 IDE 自帶的或者其他位置的環境。

Ubuntu 18/20

在主機端可以使用如下命令快速安裝 Qt Creator：

sudo apt updatesudo apt install qtcreator

啟動 Qt Creator 后，首先點擊 tools -> options 打開設置界面：

然后選擇 Qt Versions，點擊 add 添加 Qt 版本：

在彈出的窗口中選擇我們之前復制到 /opt 中的 Qt 環境：

注意：此處的路徑，根據環境包的版本不同，會有一些差異，但最終都是要選擇 /opt 下 qmake 的位置

可以給新添加的 Qt Version 起個名字，然后點擊 apply 使添加生效：

之后選擇 Kits 頁面，添加新的 Kit：

配置新的 Kit 如下：

配置的意義：首先給 Kit 起個名字，方便區分，Device Type 需要選擇 Generic Linux Device。重點是后面三個配置，Sysroot 需要選擇我們之前復制到 /opt 下的 sysroot；編譯器要選擇 arm 64bit 的 GCC；Qt Version 選擇我們上一步添加的 Qt Version，然后點擊 apply 應用更改。

最后可以打開一個項目，選擇我們新增的 Kit 進行編譯，編譯成功則說明我們配置正確：

Ubuntu 22

目標設備是 Ubuntu 22 系統，不需要交叉編譯，所以直接在設備端安裝 Qt Creator。

因為是通過 apt 安裝的 Qt 環境，所以打開 Qt Creator 它應該可以自動探測到 qmake 位置：

Qt Creator自動探測到的qmake路徑為 /usr/lib/qt5/bin/qmake，無需再手動添加 Qt Version。

Kit 的配置中，因為不需要交叉編譯，所以不設置 Sysroot，另外 Qt Version 選擇自動探測到的 Qt Version，剩余其他配置和上一章的保持一樣即可。

常見問題

1. 解壓失敗

如果解壓環境包的時候遇到這種錯誤：

tar: xxxxx: Directory renamed before its status could be extractedtar: Exiting with failure status due to previous errors

可以給 tar 加上 -P 參數重新解壓，比如：

tar -Pzxf firefly_arm64_qt5.15_20.04_20230415.tgz

2. 找不到 Qt 庫

運行 Qt 程序時如果出現找不到 Qt 庫的情況：

./analogclock: error while loading shared libraries: libQt5Gui.so.5: cannot open shared object file: No such file or directory

請檢查環境變量文件`/etc/profile.d/target_qtEnv.sh`是否存在？存在的話是否生效？Qt 庫路徑是否有按照文檔要求放到指定位置？

3. 多版本 Qt 沖突

運行 Qt 程序時如果出現報錯說存在未定義的符號：

./analogclock: symbol lookup error: ./analogclock: undefined symbol: _ZN9QGradientD1Ev, version Qt_5

說明 Qt 程序找到了和自身版本不匹配的 Qt 庫。這種問題常出現在有多個 Qt 版本環境的系統中，比如本來我們需要`/opt/firefly_qt5.15`下的環境，但是 Qt 程序卻嘗試使用`/lib/aarch64-linux-gnu/libQt5Gui.so.5`，導致出現問題。

使用 ldd 命令可以查看程序嘗試使用的庫：

root@firefly:~/analogclock# ldd analogclock | grep -i qt libQt5Gui.so.5 => /opt/firefly_qt5.15/lib/libQt5Gui.so.5 (0x0000007f8e0b2000) libQt5Core.so.5 => /opt/firefly_qt5.15/lib/libQt5Core.so.5 (0x0000007f8daf6000)

解決方法一：

在編譯前就指定好程序優先查找庫的路徑，在項目的 pro 文件中添加：

QMAKE_RPATHDIR += /opt/firefly_qt5.15/lib

解決方法二：

運行程序時指定 LD_LIBRARY_PATH：

LD_LIBRARY_PATH=/opt/firefly_qt5.15/lib ./analogclock

4. 找不到顯示

運行 Qt 程序時如果出現無法連接到顯示：

qt.qpa.xcb: could not connect to displayqt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.This application failed to start because no Qt platform plugin could be initialized. Reinstalling the application may fix this problem.
Available platform plugins are: eglfs, linuxfb, minimal, minimalegl, offscreen, vnc, wayland-egl, wayland, wayland-xcomposite-egl, webgl, xcb.
Aborted

大概率是環境變量問題，需要指定顯示，通常為：

# x11 環境使用：export DISPLAY=:0
# wayland 環境使用：export WAYLAND_DISPLAY=wayland-0