【技術(shù)案例】Qt 環(huán)境部署 - Ubuntu 篇

什么是 Qt？

Qt 是一個(gè)跨平臺(tái) C++ 圖形用戶(hù)界面應(yīng)用程序開(kāi)發(fā)框架，可構(gòu)建高性能的桌面、移動(dòng)及 Web 應(yīng)用程序，也可用于開(kāi)發(fā)非 GUI 程序，比如控制臺(tái)工具和服務(wù)器。Qt 是面向?qū)ο蟮目蚣?，使用特殊的代碼生成擴(kuò)展以及一些宏，Qt 很容易擴(kuò)展，并且允許真正的組件編程。

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

Ubuntu 18/20 部署

Firefly 針對(duì) Firefly 產(chǎn)品上運(yùn)行的 Ubuntu 18/20 系統(tǒng)提供了對(duì)應(yīng)的 Qt 環(huán)境包，可以快速部署、開(kāi)發(fā)。兩個(gè)系統(tǒng)的環(huán)境包不通用，請(qǐng)根據(jù)你的 Firefly 設(shè)備所運(yùn)行的系統(tǒng)版本，選擇對(duì)應(yīng)的環(huán)境包。

環(huán)境包請(qǐng)點(diǎn)擊此處下載，提取碼：FFQT

環(huán)境包采用交叉編譯的模式，在一個(gè)平臺(tái)上生成另一個(gè)平臺(tái)上的可執(zhí)行代碼。我們需要在 x86_64 架構(gòu)的 Linux 電腦上進(jìn)行開(kāi)發(fā)和編譯，并將編譯生成的可執(zhí)行文件放到 Arm64 架構(gòu)的目標(biāo)設(shè)備上運(yùn)行，所以環(huán)境包需要往主機(jī)端和設(shè)備端都部署一遍。

注意：不同版本的環(huán)境包有些許差別，后面的部署和環(huán)境準(zhǔn)備部分只能取一種進(jìn)行講解，具體使用時(shí)請(qǐng)查看環(huán)境包內(nèi)自帶的文檔。

主機(jī)端部署

關(guān)于主機(jī)端的選擇：請(qǐng)使用和目標(biāo)設(shè)備有相同系統(tǒng)的主機(jī)進(jìn)行開(kāi)發(fā)。

例如：需要給運(yùn)行 Ubuntu 20 的 Firefly 設(shè)備開(kāi)發(fā) Qt 程序，那么主機(jī)也應(yīng)該選擇系統(tǒng)為 Ubuntu 20 的電腦。

1. 開(kāi)始部署

解壓環(huán)境包到電腦后，cd 到解壓出來(lái)的目錄中，開(kāi)始進(jìn)行部署。主要分為 3 步：

#將文件復(fù)制到系統(tǒng)/opt/目錄下cp -rfd firefly_qt5.15_arm64_20.04 /opt/
# 將 sysroot 也復(fù)制到 /opt/ 目錄下cp -rfd sysroot /opt/
# 復(fù)制環(huán)境變量文件到 /etc/profile.d/ 下cphost/host_qtEnv.sh/etc/profile.d/

2. 環(huán)境準(zhǔn)備

安裝交叉編譯器。

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

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

3. 驗(yàn)證

環(huán)境壓縮包中還附帶一個(gè) example 文件夾，里面包含幾個(gè)簡(jiǎn)單的 Qt demo，可以用于驗(yàn)證環(huán)境是否搭建成功。一切正常則說(shuō)明環(huán)境部署成功。

# 例如使用 analogclock 來(lái)驗(yàn)證cd example/analogclock
# 執(zhí)行 qmake 自動(dòng)生成編譯系統(tǒng)qmake
# 執(zhí)行 make 開(kāi)始編譯make

設(shè)備端部署

1. 開(kāi)始部署

解壓環(huán)境包到設(shè)備后，cd 到解壓出來(lái)的目錄中，開(kāi)始進(jìn)行部署。主要分為 2 步：

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

2. 環(huán)境準(zhǔn)備

設(shè)備上還需要安裝一些必要的庫(kù)：

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

打開(kāi)`/etc/profile.d/target_qtEnv.sh`可以看到其中有三部分注釋掉的環(huán)境變量：

#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

根據(jù)你想使用的 QPA_PLATFORM 來(lái)取消對(duì)應(yīng)部分的注釋。比如 Ubuntu 環(huán)境一般使用 XCB，取消這部分的注釋?zhuān)缓蟊４娌⑼顺鼍庉嫛?/p>

#XCBexport QT_QPA_PLATFORM=XCBexport QT_QPA_EGLFS_INTEGRATION=XCB_EGL

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

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

最后執(zhí)行 reboot 重啟設(shè)備。

3. 驗(yàn)證

將之前在主機(jī)端編譯好的可執(zhí)行文件，轉(zhuǎn)移到設(shè)備端運(yùn)行；如果運(yùn)行正常，則說(shuō)明設(shè)備端環(huán)境搭建成功。

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

Ubuntu 22 部署

如果目標(biāo) Firefly 設(shè)備運(yùn)行的是 Ubuntu 22 系統(tǒng)，則不需要交叉編譯開(kāi)發(fā)，安裝 Qt 更加簡(jiǎn)單方便。

Firefly 針對(duì) Ubuntu 22 將 Qt 環(huán)境做成了 deb 包，在目標(biāo)設(shè)備上使用 apt 即可安裝：

# 安裝基礎(chǔ)環(huán)境apt updateapt install -y qtcreator qtbase5-dev
# 根據(jù)開(kāi)發(fā)需要，安裝額外的 Qt 組件與開(kāi)發(fā)環(huán)境，例如apt install -y libqt5multimedia5 qtmultimedia5-dev libqt5quick5 qtdeclarative5-dev

Qt Creator 的配置

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

Ubuntu 18/20

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

sudo apt updatesudo apt install qtcreator

啟動(dòng) Qt Creator 后，首先點(diǎn)擊 tools -> options 打開(kāi)設(shè)置界面：

然后選擇 Qt Versions，點(diǎn)擊 add 添加 Qt 版本：

在彈出的窗口中選擇我們之前復(fù)制到 /opt 中的 Qt 環(huán)境：

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

可以給新添加的 Qt Version 起個(gè)名字，然后點(diǎn)擊 apply 使添加生效：

之后選擇 Kits 頁(yè)面，添加新的 Kit：

配置新的 Kit 如下：

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

最后可以打開(kāi)一個(gè)項(xiàng)目，選擇我們新增的 Kit 進(jìn)行編譯，編譯成功則說(shuō)明我們配置正確：

Ubuntu 22

目標(biāo)設(shè)備是 Ubuntu 22 系統(tǒng)，不需要交叉編譯，所以直接在設(shè)備端安裝 Qt Creator。

因?yàn)槭峭ㄟ^(guò) apt 安裝的 Qt 環(huán)境，所以打開(kāi) Qt Creator 它應(yīng)該可以自動(dòng)探測(cè)到 qmake 位置：

Qt Creator自動(dòng)探測(cè)到的qmake路徑為 /usr/lib/qt5/bin/qmake，無(wú)需再手動(dòng)添加 Qt Version。

Kit 的配置中，因?yàn)椴恍枰徊婢幾g，所以不設(shè)置 Sysroot，另外 Qt Version 選擇自動(dòng)探測(cè)到的 Qt Version，剩余其他配置和上一章的保持一樣即可。

常見(jiàn)問(wèn)題

1. 解壓失敗

如果解壓環(huán)境包的時(shí)候遇到這種錯(cuò)誤：

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

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

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

2. 找不到 Qt 庫(kù)

運(yùn)行 Qt 程序時(shí)如果出現(xiàn)找不到 Qt 庫(kù)的情況：

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

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

3. 多版本 Qt 沖突

運(yùn)行 Qt 程序時(shí)如果出現(xiàn)報(bào)錯(cuò)說(shuō)存在未定義的符號(hào)：

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

說(shuō)明 Qt 程序找到了和自身版本不匹配的 Qt 庫(kù)。這種問(wèn)題常出現(xiàn)在有多個(gè) Qt 版本環(huán)境的系統(tǒng)中，比如本來(lái)我們需要`/opt/firefly_qt5.15`下的環(huán)境，但是 Qt 程序卻嘗試使用`/lib/aarch64-linux-gnu/libQt5Gui.so.5`，導(dǎo)致出現(xiàn)問(wèn)題。

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

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)

解決方法一：

在編譯前就指定好程序優(yōu)先查找?guī)斓穆窂?，在?xiàng)目的 pro 文件中添加：

QMAKE_RPATHDIR += /opt/firefly_qt5.15/lib

解決方法二：

運(yùn)行程序時(shí)指定 LD_LIBRARY_PATH：

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

4. 找不到顯示

運(yùn)行 Qt 程序時(shí)如果出現(xiàn)無(wú)法連接到顯示：

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

大概率是環(huán)境變量問(wèn)題，需要指定顯示，通常為：

# x11 環(huán)境使用：export DISPLAY=:0
# wayland 環(huán)境使用：export WAYLAND_DISPLAY=wayland-0