Qt for QNX runtime target requirements | Qt 6.11
Description: Describes target requirements for running qt applications.

- Qt 6.11
- Supported Platforms
- Qt for QNX
- Qt for QNX runtime target requirements
- Qt 6.11.2 Reference Documentation

Building Qt for QNX ◦ Qt for VxWorks

# Qt for QNX runtime target requirements

QNX Software Systems delivers software solutions for making embedded devices. This includes creation of QNX Neutrino RTOS boot images in a very flexible way. Even though QNX provides several reference scripts for the OS image creation, sooner or later you will need to make changes or you might decide to create an OS image from scratch. Qt relies on the existence of several third-party components and selected OS services. Due to this, QNX Neutrino RTOS boot images for a target device running Qt must meet the requirements listed in the following sections to ensure that Qt works as expected.

## QNX screen graphics subsystem

Before any Qt application can be started, the QNX Screen Graphics Subsystem (also called just "Screen") must be running. `Screen` consists of a driver and several utilities and services which are used by Qt. This includes processing of mouse and keyboard events as well. You can ensure that `Screen` is configured and running correctly by verifying that a graphics application, like `gles2-gears`, can be started and runs without problems.

Most of the recent sample OS build scripts in the SDP include sections with all components and start commands for the Screen. You can use them as a reference.

## IPv6 support

Qt's networking stack requires IPv6 support to be enabled, independent of whether the actual networking uses IPv4 or IPv6.

Warning: `io-pkt-v6-hc` must be running, not `io-pkt-v4`.

## Random device `/dev/random`

Qt requires `/dev/random` to be present and functional. Start it before starting any Qt application or during the system startup:

     random -p
     waitfor /dev/random

## System logger

QNX provides the slog2 logging framework tailored to specifics of embedded systems. The major advantage of it is a much better performance than a text output to files. Qt uses this framework by default for any logging output going through QDebug on QNX Neutrino RTOS. The `slog2` service should be started during the system startup. The `slog2` also relies on the existence of the `/tmp` folder which has to be configured as well, for example:

     [type=link] /tmp=/dev/shmem
     display_msg "Starting slogger2..."
     slogger2 -U1001:1000 &
     waitfor /dev/slog2

## Environment variables

There is a set of environment variables you should set when starting a Qt application. Most of them are actually not specific to QNX Neutrino RTOS. They are still mentioned here, since knowing them just saves a lot of time in case of problems.

Note: `setconf` and `getconf` are required to access POSIX environment variables, especially for the host name and time and date.

### Qt runtime location

If you did not build Qt with the RPATH environment variable set, you can place the Qt runtime components in any folder in the file system. The following environment variables should point to valid locations assuming that the Qt installation is located in `<Qt-install-path>`:

- `LD_LIBRARY_PATH` should contain the path to the Qt libraries in `<Qt-install-path>/lib`.
- `QT_PLUGIN_PATH` defines where the Qt plug-ins are located. It should be set to `<Qt-install-path>/plugins`.
- `QML2_IMPORT_PATH` defines where the Qt Quick plug-ins are located. It should be set to `<Qt-install-path>/qml`.
- If Qt does not use fontconfig, you must either provide the path to the fonts with `QT_QPA_FONTDIR`, or place the fonts under `<Qt-install-path>/lib/fonts` which is the default font location.
- Check `QT_QPA_QNX_DISPLAY_CONFIG` for the number and order of available screens/displays.

### Physical screen size

Qt needs information about the physical dimensions of the attached display to determine DPI values and thus set correct font sizes. Usually, this information is provided by the Screen. In some cases you may see an invalid screen size such as 0mmx0mm. In such a case Qt requires an environment variable `QQNX_PHYSICAL_SCREEN_SIZE` set to according values to get the required information. If Qt applications exit with an error message saying that the physical screen size couldn't be determined, set the variable like this before starting the Qt application:

     export QQNX_PHYSICAL_SCREEN_SIZE=150,100

to inform Qt that the screen has a width of 150mm and a height of 100mm in this particular case. The physical screen size is measured in millimeters (mm) and should correspond to the actual physical size of the display in the final configuration.

### Troubleshooting the first start of a Qt application

The only drawback of the flexibility provided by QNX Neutrino RTOS is a risk that the run environment is slightly different on your target than what is expected by Qt. This is a common reason why a Qt application on a new target fails to start. A few generic environment variables can help locate the root cause for problems:

- Setting `QT_DEBUG_PLUGINS` to `1` helps to see why the QPA plugin cannot load.
- Setting `LD_DEBUG` to `1` helps to see where and how shared libraries are loaded. This can be used in combination with `QT_DEBUG_PLUGINS` when a plugin failed to load because it could not load other shared libraries.
- Setting `QT_LOGGING_TO_CONSOLE` will force sending all logging messages to `stderr` instead of `slog2`. This is useful for analyzing application startup problems, as you do not need to use another tool to see the messages.

Qt normally uses `fontconfig` to provide access to systemfonts. If a font cache hasn't been created earlier, it will be created at the start-up of the first Qt application. Depending on the setup it can take a very long time and delay applications' start-up significantly. If not needed, fontconfig can be disabled with -DFEATURE_fontconfig=OFF on configure time.

## Using QCursor on the QNX platform

Custom cursor support on QNX is disabled by default. To enable it, set the `QT_QPA_QNX_CUSTOM_CURSOR` environment variable before starting your Qt application:

     export QT_QPA_QNX_CUSTOM_CURSOR=1

When custom cursor support is enabled, QNX supports changing your cursor shape for a window, but you'll need to deploy and specify the images associated with the shapes you want to use through the Screen configuration file, `graphics.conf`. See the cursor-type parameter of Configure display subsection for more details. In addition to the default cursor, no additional cursors are provided in QNX. Therefore, any extra cursor graphics must be provided manually in bitmap format. The table below shows the cursor name used in `graphics.conf` for each Qt::CursorShape value.

Qt::CursorShape value | QNX Screen Configuration name
--- | ---
Qt::ArrowCursor | arrow
Qt::CrossCursor | cross
Qt::WaitCursor | wait
Qt::IBeamCursor | ibeam
Qt::PointingHandCursor | hand
Qt::OpenHandCursor | grab
Qt::ClosedHandCursor | grabbing
Qt::DragMoveCursor | move
All other cursor shapes | arrow (default)

Building Qt for QNX ◦ Qt for VxWorks