Qt Environment Deployment - Ubuntu

What is Qt environment?

Qt is a cross-platform C++ graphical user interface application development framework that can build high-performance desktop, mobile and web applications. It can also be used to develop non-GUI programs, such as console tools and servers. Qt is an object-oriented framework that uses special code generation extensions and some macros. Qt is easy to extend and allows real component programming.

Ubuntu 18/20 deployment

Firefly provides a corresponding Qt environment package for the Ubuntu 18/20 system running on Firefly products, which can achieve rapid deployment and development. The environments of the two systems are not universal. Please select the corresponding environment according to the system version running on your Firefly device.

If you need an environmental package, please contact us to request it.

The environment package uses a cross-compilation mode to generate executable code on one platform for another platform. We need to develop and compile on a Linux computer with x86_64 architecture, and put the compiled executable file on the target device with Arm64 architecture to run, so the environment package needs to be deployed on both the host and the device.

Note: There are slight differences between different versions of environment packages. The following deployment and environment preparation sections can only use one for explanation. Please refer to the documentation included in the environment package for specific use.

Host-side deployment

Regarding the choice of host: Please use a host with the same system as the target device for development.

For example, if you need to develop a Qt program for a Firefly device running Ubuntu 20, the host should also be a computer running Ubuntu 20.

1. Start deployment

After unzipping the environment package to your computer, cd to the unzipped directory and start deployment. It is mainly divided into 3 steps:

1. # Copy the file to the system /opt/ directory
2. cp -rfd firefly_qt5.15_arm64_20.04 /opt/
4. # Copy sysroot to the /opt/ directory
5. cp -rfd sysroot /opt/
7. # Copy the environment variable file to /etc/profile.d/
8. cp host/host_qtEnv.sh /etc/profile.d

2. Environmental preparation

Install the cross compiler.

1. sudo apt update
2. sudo apt install -y crossbuild-essential-arm64

Then log in again or restart the computer to ensure that the environment variables copied previously take effect.

3. Verification

The compressed package also comes with an example folder containing several simple Qt demos that can be used to verify whether the environment is successfully built. If everything goes well, it means that the environment is deployed successfully.

1. # For example, use analogclock to verify
2. cd example/analogclock
4. # Execute qmake to automatically generate the compilation system
5. qmake
7. # Execute make to start compiling/
8. make

Device deployment

1. Start deployment

After unzipping the environment package to your computer, cd to the unzipped directory and start deployment. It is mainly divided into 2 steps:

1. # Copy the ext part to the system's /opt/ directory. Note that ext is renamed to firefly_qt5.15
2. cp -rfd firefly_qt5.15_arm64_20.04/ext /opt/firefly_qt5.15
4. # Copy the environment variable file to /etc/profile.d/
5. cp target/target_qtEnv.sh /etc/profile.d/

2. Environmental preparation

You also need to install some necessary libraries on the device:

1. apt install -y libmtdev1 libinput10 libxkbcommon0 \
2. libdouble-conversion3 libicu66 libharfbuzz0b \
3. libwebpdemux2 libwebpmux3

Open "/etc/profile.d/target_qtEnv.sh" and you can see three commented-out environment variables:

1. #XCB
2. #export QT_QPA_PLATFORM=XCB
3. #export QT_QPA_EGLFS_INTEGRATION=XCB_EGL
5. #LinuxFB
6. #export QT_QPA_PLATFORM=LINUXFB
7. #export QT_QPA_FB_DRM=1
9. #EGLFS
10. #export QT_QPA_PLATFORM=EGLFS
11. #export QT_QPA_EGLFS_INTEGRATION=EGLFS_KMS #in minimal ubuntu, use eglfs_kms.
12. A_EGLFS_KMS_ATOMIC=1 #use drm atomic api or legacy api(two different)
13. #export QT_QPA_EGLFS_HIDECURSOR=1 #hide cursor

Uncomment the corresponding part according to the QPA_PLATFORM you want to use. For example, XCB is generally used in the Ubuntu environment. Uncomment this part, then save and exit the editor.

1. #XCB
2. export QT_QPA_PLATFORM=XCB
3. export QT_QPA_EGLFS_INTEGRATION=XCB_EGL

If you use XCB, you will need to install some additional libraries:

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

Finally, execute reboot to restart the device.

3. Verification

Transfer the executable file compiled on the host side to the device side for execution; if it runs normally, it means that the device side environment has been successfully built.

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

Ubuntu 22 deployment

If the target Firefly device is running Ubuntu 22, cross-compilation development is not required and installing Qt is much simpler and more convenient.

Firefly has made the Qt environment into a deb package for Ubuntu 22, which can be installed using apt on the target device:

1. # Install the basic environment
2. apt update
3. apt install -y qtcreator qtbase5-dev
5. # Install additional Qt components and development environments based on development needs, such as
6. apt install -y libqt5multimedia5 qtmultimedia5-dev libqt5quick5 qtdeclarative5-dev

Qt Creator configuration

Qt development often uses Qt Creator as the IDE. In the previous part, we set up the Qt development environment. Next, we will introduce how to ensure that Qt Creator can use the environment we have built, rather than the environment that comes with the IDE or is located elsewhere.

Ubuntu 18/20

On the host side, you can use the following command to quickly install Qt Creator:

1. sudo apt update
2. sudo apt install qtcreator

After starting Qt Creator, first click tools -> options to open the settings interface:

Then select Qt Versions and click add to add the Qt version:

In the pop-up window, select the Qt environment we copied to /opt before:

Note: The path here may vary depending on the version of the environment package, but in the end you have to choose the location of qmake under /opt

You can give the newly added Qt Version a name, and then click apply to make the addition effective:

Then select the Kits page and add a new Kit:

Configure the new Kit as follows:

The significance of configuration: First, name the Kit for easy identification. Device Type needs to be selected as Generic Linux Device. The focus is on the following three configurations. Sysroot needs to select the sysroot we copied to /opt before; compiler needs to select arm 64-bit GCC; Qt Version selects the Qt Version we added in the previous step, and then click Apply to apply the changes.

Finally, you can open a project and select our newly added Kit to compile. If the compilation is successful, it means that our configuration is correct:

Ubuntu 22

The target device is Ubuntu 22 system, and cross-compilation is not required, so Qt Creator is installed directly on the device.

Because the Qt environment is installed via apt, when you open Qt Creator it should automatically detect the qmake location:

The qmake path automatically detected by Qt Creator is /usr/lib/qt5/bin/qmake, so there is no need to manually add Qt Version.

In the Kit configuration, Sysroot is not set because cross-compilation is not required. In addition, Qt Version selects the automatically detected Qt Version. The rest of the configurations can remain the same as in the previous chapter.

FAQ

1. Decompression failed

If you encounter this error when unzipping the environment package.

1. tar: xxxxx: Directory renamed before its status could be extracted
2. tar: Exiting with failure status due to previous errors

You can add the -P parameter to tar to decompress it again, for example:

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

2. Multiple versions of Qt conflict

If the Qt library cannot be found when running a Qt program:

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

This means that the Qt program has found a Qt library that does not match its version. This problem often occurs in systems with multiple Qt version environments. For example, we originally need an environment under "/opt/firefly_qt5.15", but the Qt program tries to use "/lib/aarch64-linux-gnu/libQt5Gui.so.5", which causes problems.

Use the ldd command to see the libraries that a program is trying to use:

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

Solution 1: Specify the path where the program should search for the library first before compiling. Add the following to the pro file of the project:

1. QMAKE_RPATHDIR += /opt/firefly_qt5.15/lib

Solution 2: Specify LD_LIBRARY_PATH when running the program:

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

3. Display not found

If you cannot connect to the display when running a Qt program:

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

It is most likely an environment variable problem, which needs to be specified, usually:

1. # Use in x11 environment:
2. export DISPLAY=:0
4. # Use in wayland environment:
5. export WAYLAND_DISPLAY=wayland-0

4. Qt library not found

If the Qt library cannot be found when running a Qt program:

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

Please check whether the environment variable file "/etc/profile.d/target_qtEnv.sh" exists? If it exists, is it effective? Is the Qt library path placed in the specified location as required by the document?