This guide tells you what is needed to start developing with Qt Quick Ultralite on Linux targets.

Supported architectures, platforms and Linux toolchains

Qt Quick Ultralite supports the following hardware:

Development environment requirements

Prerequisites

To build Qt Quick Ultralite for Linux, you'll need following things:

• A Boot to Qt package for the given target, from the Qt Maintenance Tool.
• Or, any other Yocto sysroot and toolchain for the given target.

Environment setup

You need to specify a custom toolchain file using the CMAKE_TOOLCHAIN_FILE option, telling CMake which tools and sysroot to use when building the project for the Linux target.

Using the qt.toolchain.cmake toolchain file from a Boot to Qt package

If there's a Boot to Qt package for the target board, the qt.toolchain.cmake toolchain file from the host sysroot can be used with QT_TOOLCHAIN_INCLUDE_FILE set to the supplemental boot2qt.cmake toolchain file from the Qt for MCUs installation. Here's an example for the MCIMX93-EVK board:

export QUL_ROOT=$HOME/Qt/QtMCUs/2.9.0
export BOOT2QT_DIR=$HOME/Qt/6.6.3/Boot2Qt
cd $QUL_ROOT
mkdir custom_build
cd custom_build
cmake .. -G "Ninja" -DCMAKE_BUILD_TYPE=MinSizeRel -DQul_ROOT=$QUL_ROOT -DCMAKE_TOOLCHAIN_FILE=$BOOT2QT_DIR/imx93-11x11-lpddr4x-evk/toolchain/sysroots/x86_64-pokysdk-linux/usr/lib/cmake/Qt6/qt.toolchain.cmake -DQT_TOOLCHAIN_INCLUDE_FILE=$QUL_ROOT/lib/cmake/Qul/toolchain/boot2qt.cmake -DQUL_GENERATORS=$QUL_ROOT/lib/cmake/Qul/QulGenerators.cmake -DQUL_PLATFORM=generic-linux -DQUL_LINUX_RENDER_BACKEND=linuxfb -DQUL_BUILD_EXAMPLES=off -DQUL_BUILD_DEMOS=off
cmake --build .

set QUL_ROOT=C:\Qt\QtMCUs\2.9.0
set BOOT2QT_DIR=C:\Qt\6.6.3\Boot2Qt
cd %QUL_ROOT%
mkdir custom_build
cd custom_build
cmake .. -G "Ninja" -DCMAKE_BUILD_TYPE=MinSizeRel -DQul_ROOT=%QUL_ROOT% -DCMAKE_TOOLCHAIN_FILE=%BOOT2QT_DIR%\imx93-11x11-lpddr4x-evk\toolchain\sysroots\x86_64-w64-mingw32\usr\lib\cmake\Qt6\qt.toolchain.cmake -DQT_TOOLCHAIN_INCLUDE_FILE=%QUL_ROOT%\lib\cmake\Qul\toolchain\boot2qt.cmake -DQUL_GENERATORS=%QUL_ROOT%\lib\cmake\Qul\QulGenerators.cmake -DQUL_PLATFORM=generic-linux -DQUL_LINUX_RENDER_BACKEND=linuxfb -DQUL_BUILD_EXAMPLES=off -DQUL_BUILD_DEMOS=off
cmake --build .

Manually creating a toolchain file

For an arbitrary Linux target, it's necessary to manually create a toolchain file telling CMake where to find the compiler tools, the target sysroot, and which compiler flags to use. Below is an example toolchain file that can be customized depending on the specific target.

set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)

SET(COMPILER_FOLDER_NAME "armgcc")
SET(QUL_COMPILER_NAME "armgcc")

IF(WIN32)
    SET(TOOLCHAIN_EXT ".exe")
ELSE()
    UNSET(TOOLCHAIN_EXT)
ENDIF()

set(QT_HOST_PATH "/path/to/Qt/<version>/<target>")
set(TOOLCHAIN_PREFIX "/path/to/target/toolchain/aarch64-poky-linux")
set(CMAKE_SYSROOT "/path/to/target/sysroot")

set(CMAKE_C_COMPILER ${TOOLCHAIN_PREFIX}-gcc${TOOLCHAIN_EXT})
set(CMAKE_CXX_COMPILER ${TOOLCHAIN_PREFIX}-g++${TOOLCHAIN_EXT})
set(CMAKE_ASM_COMPILER ${TOOLCHAIN_PREFIX}-gcc${TOOLCHAIN_EXT})
set(CMAKE_AR ${TOOLCHAIN_PREFIX}-gcc-ar${TOOLCHAIN_EXT})
set(CMAKE_RANLIB ${TOOLCHAIN_PREFIX}-gcc-ranlib${TOOLCHAIN_EXT})

set(COMPILER_FLAGS "-mcpu=cortex-a55\
    -march=armv8.2-a+crypto -mbranch-protection=standard \
    -fstack-protector-strong")

set(CMAKE_C_FLAGS_INIT "${COMPILER_FLAGS}")
set(CMAKE_CXX_FLAGS_INIT "${COMPILER_FLAGS}")

set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

The toolchain file can then be used like this to build the generic-linux platform:

export QUL_ROOT=$HOME/Qt/QtMCUs/2.9.0
mkdir custom_build
cd custom_build
cmake .. -G "Ninja" -DCMAKE_BUILD_TYPE=MinSizeRel -DQul_ROOT=$QUL_ROOT -DCMAKE_TOOLCHAIN_FILE=$HOME/path/to/custom-toolchain.cmake -DQUL_PLATFORM=generic-linux -DQUL_GENERATORS=$QUL_ROOT/lib/cmake/Qul/QulGenerators.cmake -DCMAKE_INSTALL_PREFIX=$QUL_ROOT -DQUL_LINUX_RENDER_BACKEND=linuxfb -DQUL_BUILD_EXAMPLES=off -DQUL_BUILD_DEMOS=off
cmake --build .

set QUL_ROOT=C:\Qt\QtMCUs\2.9.0
cd %QUL_ROOT%
mkdir custom_build
cd custom_build
cmake .. -G "Ninja" -DCMAKE_BUILD_TYPE=MinSizeRel -DQul_ROOT=%QUL_ROOT% -DCMAKE_TOOLCHAIN_FILE=C:\path\to\custom-toolchain.cmake -DQUL_PLATFORM=generic-linux -DQUL_GENERATORS=%QUL_ROOT%\lib\cmake\Qul\QulGenerators.cmake -DCMAKE_INSTALL_PREFIX=%QUL_ROOT% -DQUL_LINUX_RENDER_BACKEND=linuxfb -DQUL_BUILD_EXAMPLES=off -DQUL_BUILD_DEMOS=off
cmake --build .

Qt Quick Ultralite on Linux renderer backend

The Qt Quick Ultralite on Linux platform port has two renderer backends: drm and linuxfb. The renderer backend is responsible for allocating framebuffers and presenting new content on the display.

To use the drm renderer backend, specify -DQUL_LINUX_RENDER_BACKEND=drm when running the cmake configuration command. Otherwise, specify -DQUL_LINUX_RENDERER_BACKEND=linuxfb to use the linuxfb renderer backend.

Qt Quick Ultralite on Linux input

By default, the Qt Quick Ultralite on Linux platform port will try to use the libinput library for touch and keyboard input, and additionally the xkbcommon library for advanced keymap support.

To disable advanced keymap support, configure with -DQUL_LINUX_ENABLE_XKBCOMMON=off. To disable touch and keyboard input completely, configure with QUL_LINUX_ENABLE_LIBINPUT=off.