This topic provides instructions to build the full Qt Quick Ultralite from sources, or only the platform library against the Qt Quick Ultralite evaluation packages.

Prerequisites

• Qt for MCUs SDK
• Qt Creator v13.0.0 or newer
• CMake 3.21.1 or newer
• Ninja 1.10.0 or newer
• Qt 6.2.4 (only needed for Desktop platform)

Command line setup

To get started from the command line, ensure that the following environment variables are set:

• Add the CMake and Ninja tools to your system PATH. If you installed these tools using Qt Online Installer, they are installed under <QT_INSTALL_PATH>\Tools.

QUL_ROOT and QUL_TOOLS are used in the command line examples below as if they were set as environment variables. For example:

export QUL_ROOT=$HOME/Qt/QtMCUs/2.9.0
export QUL_TOOLS=$HOME/Qt/Tools/QtMCUs

set QUL_ROOT=C:\Qt\QtMCUs\2.9.0
set QUL_TOOLS=C:\Qt\Tools\QtMCUs

To modify the Qt Quick Ultralite Desktop platform, set the QT_ROOT environment variable.

export QT_ROOT=$HOME/Qt/QtMCUs/6.2.4/<COMPILER>

set QT_ROOT=C:\Qt\6.2.4\<COMPILER>

where, <COMPILER> matches the development toolchain in your host environment (msvc2019_64, mingw_64, or gcc_64).

Qt 6.2.4 is the default version used by QulPackage. Change QT_ROOT to match the desired Qt version installed on your host environment.

Building Qt Quick Ultralite from sources

If your license provides access to the Qt Quick Ultralite sources, use these commands to build it.

Building from sources for target hardware

For example, the following builds Qt Quick Ultralite for NXP i.MX RT1050 on bare metal:

cd $QUL_ROOT
mkdir build
cd build
mkdir -p .cmake/api/v1/query && touch .cmake/api/v1/query/codemodel-v2
cmake .. -G "Ninja" -DQul_ROOT=$QUL_ROOT -DCMAKE_BUILD_TYPE=MinSizeRel -DCMAKE_TOOLCHAIN_FILE=../lib/cmake/Qul/toolchain/armgcc.cmake -DQUL_TARGET_TOOLCHAIN_DIR=$QUL_TOOLS/arm_gcc_12_3_1 -DQUL_BOARD_SDK_DIR=$QUL_TOOLS/NXP/SDK_2_15_000_EVKB-IMXRT1050 -DQUL_GENERATORS=../lib/cmake/Qul/QulGenerators.cmake -DQUL_PLATFORM=MIMXRT1050-EVK-baremetal
cmake --build .

cd %QUL_ROOT%
mkdir build
cd build
mkdir .cmake\api\v1\query && echo . > .cmake\api\v1\query\codemodel-v2
cmake .. -G "Ninja" -DQul_ROOT=%QUL_ROOT% -DCMAKE_BUILD_TYPE=MinSizeRel -DCMAKE_TOOLCHAIN_FILE=..\lib\cmake\Qul\toolchain\armgcc.cmake -DQUL_TARGET_TOOLCHAIN_DIR=%QUL_TOOLS%\arm_gcc_12_3_1 -DQUL_BOARD_SDK_DIR=%QUL_TOOLS%\NXP\SDK_2_15_000_EVKB-IMXRT1050 -DQUL_GENERATORS=..\lib\cmake\Qul\QulGenerators.cmake -DQUL_PLATFORM=MIMXRT1050-EVK-baremetal
cmake --build .

To build for a different hardware platform, update the CMAKE_TOOLCHAIN_FILE, QUL_TARGET_TOOLCHAIN_DIR, QUL_PLATFORM, and QUL_BOARD_SDK_DIR CMake variables accordingly. The value for the QUL_PLATFORM variable must be a combination of <BOARD-NAME> and <OS>. The following is a list of all the possible values that you can use:

• TVIIC2D4M-baremetal
• TVIIC2D4MLITE-baremetal
• TVIIC2D6M-baremetal
• TVIIC2D6MDDR-baremetal
• EK-RA6M3G-baremetal
• EK-RA6M3G-freertos
• MIMXRT1050-EVK-baremetal
• MIMXRT1050-EVK-freertos
• MIMXRT1060-EVKB-baremetal
• MIMXRT1064-EVK-baremetal
• MIMXRT1064-EVK-freertos
• MIMXRT1170-EVKB-freertos
• RH850-D1M1A-baremetal
• RH850-D1M1A-autosar
• STM32F769I-DISCOVERY-baremetal
• STM32F769I-DISCOVERY-freertos
• STM32H750B-DISCOVERY-baremetal
• STM32F469I-DISCOVERY-baremetal

Once Qt Quick Ultralite is built successfully, build one of the supported demos/examples using it and flash the resulting binary to the target hardware.

cmake --build . --target flash_<DEMO_OR_EXAMPLE_NAME>

Where, DEMO_OR_EXAMPLE_NAME is the name of a supported demo or an example.

Building from sources for desktop

Qt 6.2.4 is the default version used by QulPackage. Change QT_ROOT to match the desired Qt version installed on your host environment.

The following builds Qt Quick Ultralite for the Desktop target:

cd $QUL_ROOT
mkdir build
cd build
mkdir -p .cmake/api/v1/query && touch .cmake/api/v1/query/codemodel-v2
cmake .. -G "Ninja" -DQul_ROOT=$QUL_ROOT -DCMAKE_BUILD_TYPE=Release -DQUL_GENERATORS=../lib/cmake/Qul/QulGenerators.cmake -DQUL_PLATFORM=Qt -DCMAKE_PREFIX_PATH=$QUL_ROOT/bin
cmake --build .

cd %QUL_ROOT%
mkdir build
cd build
mkdir .cmake\api\v1\query && echo . > .cmake\api\v1\query\codemodel-v2
cmake .. -G "Ninja" -DQul_ROOT=%QUL_ROOT% -DCMAKE_BUILD_TYPE=Release -DQUL_GENERATORS=..\lib\cmake\Qul\QulGenerators.cmake -DQUL_PLATFORM=Qt -DCMAKE_PREFIX_PATH=%QUL_ROOT%\bin
cmake --build .

Building Qt Quick Ultralite platform library against the evaluation packages

With the evaluation version of Qt Quick Ultralite you can modify and rebuild the platforms that are already shipped together with Qt Quick Ultralite. For example, port to a slightly different board configuration.

For instructions on how to create your own platform library for a custom hardware platform, refer to the Qt Quick Ultralite Platform Porting Guide.

Building a platform library for target hardware

The following commands build the Qt Quick Ultralite platform library, using NXP i.MX RT1050 on bare metal as reference platform:

cd $QUL_ROOT
mkdir build
cd build
cmake .. -G "Ninja" -DQul_ROOT=$QUL_ROOT -DCMAKE_BUILD_TYPE=MinSizeRel -DCMAKE_TOOLCHAIN_FILE=$QUL_ROOT/lib/cmake/Qul/toolchain/armgcc.cmake -DQUL_TARGET_TOOLCHAIN_DIR=$QUL_TOOLS/arm_gcc_12_3_1 -DQUL_BOARD_SDK_DIR=$QUL_TOOLS/NXP/SDK_2_15_000_EVKB-IMXRT1050 -DQUL_PLATFORM=MIMXRT1050-EVK-baremetal -DQUL_BUILD_DEMOS=off -DQUL_BUILD_EXAMPLES=off -DQUL_BUILD_FRAMEWORK=off -DQUL_GENERATORS=$QUL_ROOT/lib/cmake/Qul/QulGenerators.cmake
cmake --build .

cd %QUL_ROOT%
mkdir build
cd build
cmake .. -G "Ninja" -DQul_ROOT=%QUL_ROOT% -DCMAKE_BUILD_TYPE=MinSizeRel -DCMAKE_TOOLCHAIN_FILE=%QUL_ROOT%\lib\cmake\Qul\toolchain\armgcc.cmake -DQUL_TARGET_TOOLCHAIN_DIR=%QUL_TOOLS%\arm_gcc_12_3_1 -DQUL_BOARD_SDK_DIR=%QUL_TOOLS%\NXP\SDK_2_15_000_EVKB-IMXRT1050 -DQUL_PLATFORM=MIMXRT1050-EVK-baremetal -DQUL_BUILD_DEMOS=off -DQUL_BUILD_EXAMPLES=off -DQUL_BUILD_FRAMEWORK=off -DQUL_GENERATORS=%QUL_ROOT%/lib/cmake/Qul/QulGenerators.cmake
cmake --build .

To update the Qt Creator integration to use the custom built platform library, set these two environment variables:

• CMAKE_INSTALL_PREFIX to Qt for MCUs install directory. It should match the Qt for MCUs version set in the Edit > Preferences > Devices > MCU option in Qt Creator.
• QUL_VERSION to the corresponding version number. For example, if Qt Creator is configured to use C:\Qt\QtMCUs\<VERSION>, where <VERSION> is the directory containing the Qt Quick Ultralite version you are using (for example 2.9.0).

After setting these variables, use the following commands to configure and install the platform library:

export QUL_VERSION=<VERSION>
cd $QUL_ROOT
mkdir build
cd build
cmake .. -G "Ninja" -DQul_ROOT=$QUL_ROOT -DCMAKE_BUILD_TYPE=MinSizeRel -DCMAKE_TOOLCHAIN_FILE=../lib/cmake/Qul/toolchain/armgcc.cmake -DQUL_PLATFORM=MIMXRT1050-EVK-baremetal -DQUL_TARGET_TOOLCHAIN_DIR=$QUL_TOOLS/arm_gcc_12_3_1 -DQUL_BOARD_SDK_DIR=$QUL_TOOLS/NXP/SDK_2_15_000_EVKB-IMXRT1050 -DQUL_BUILD_DEMOS=off -DQUL_BUILD_EXAMPLES=off -DQUL_BUILD_FRAMEWORK=off -DCMAKE_INSTALL_PREFIX=$QUL_ROOT -DQUL_VERSION=$QUL_VERSION -DQUL_GENERATORS=$QUL_ROOT/lib/cmake/Qul/QulGenerators.cmake
cmake --build .
cmake --install .

set QUL_VERSION=<VERSION>
cd %QUL_ROOT%
mkdir build
cd build
cmake .. -G "Ninja" -DQul_ROOT=%QUL_ROOT% -DCMAKE_BUILD_TYPE=MinSizeRel -DCMAKE_TOOLCHAIN_FILE=..\lib\cmake\Qul\toolchain\armgcc.cmake -DQUL_PLATFORM=MIMXRT1050-EVK-baremetal -DQUL_TARGET_TOOLCHAIN_DIR=%QUL_TOOLS%\arm_gcc_12_3_1 -DQUL_BOARD_SDK_DIR=%QUL_TOOLS%\NXP\SDK_2_15_000_EVKB-IMXRT1050 -DQUL_BUILD_DEMOS=off -DQUL_BUILD_EXAMPLES=off -DQUL_BUILD_FRAMEWORK=off -DCMAKE_INSTALL_PREFIX=%QUL_ROOT% -DQUL_VERSION=%QUL_VERSION% -DQUL_GENERATORS=%QUL_ROOT%/lib/cmake/Qul/QulGenerators.cmake
cmake --build .
cmake --install .

Building a platform library for desktop

The following commands build and install a custom Qt platform library (desktop simulator).

export QUL_VERSION=<VERSION>
cd $QUL_ROOT
mkdir build
cd build
cmake .. -G "Ninja" -DQul_ROOT=$QUL_ROOT -DCMAKE_BUILD_TYPE=Release -DQUL_BUILD_FRAMEWORK=OFF -DQUL_BUILD_TOOLS=OFF -DQUL_BUILD_TESTS=OFF -DQUL_BUILD_EXAMPLES=OFF -DQUL_BUILD_DEMOS=OFF -DCMAKE_INSTALL_PREFIX=$QUL_ROOT -DQUL_VERSION=$QUL_VERSION -DQUL_GENERATORS=$QUL_ROOT/lib/cmake/Qul/QulGenerators.cmake -DQUL_PLATFORM=Qt -DCMAKE_PREFIX_PATH=$QUL_ROOT/bin;$QT_ROOT
cmake --build .
cmake --install .

set QUL_VERSION=<VERSION>
cd %QUL_ROOT%
mkdir build
cd build
cmake .. -G "Ninja" -DQul_ROOT=%QUL_ROOT% -DCMAKE_BUILD_TYPE=Release -DQUL_BUILD_FRAMEWORK=OFF -DQUL_BUILD_TOOLS=OFF -DQUL_BUILD_TESTS=OFF -DQUL_BUILD_EXAMPLES=OFF -DQUL_BUILD_DEMOS=OFF -DCMAKE_INSTALL_PREFIX=%QUL_ROOT% -DQUL_VERSION=%QUL_VERSION% -DQUL_GENERATORS=%QUL_ROOT%/lib/cmake/Qul/QulGenerators.cmake -DQUL_PLATFORM=Qt -DCMAKE_PREFIX_PATH=%QUL_ROOT%\bin;%QT_ROOT%
cmake --build .
cmake --install .

Building applications using a custom built Qt Quick Ultralite

This section describes how to build an application using a custom-built Qt Quick Ultralite.

The following step-by-step instructions guide you build and install Qt Quick Ultralite, and use it to build an application:

1. Set up your development environment for the chosen target. as per the instructions in the Getting started topic.
2. Set environment variables according to chosen target and toolchain. For example, following are the commands for MIMXRT1170-EVKB with the ARM GCC toolchain. To build for another platform or toolchain, modify the QUL_PLATFORM_NAME, QUL_BOARD_SDK_DIR, CMAKE_TOOLCHAIN_FILE, QUL_TARGET_TOOLCHAIN_DIR, and FREERTOS_DIR environment variables accordingly. The FREERTOS_DIR parameter can be dropped if you are not building for the FreeRTOS platform. LinuxWindows

   export QUL_PLATFORM_NAME=mimxrt1170-evkb-freertos
   export QUL_BOARD_SDK_DIR=$QUL_TOOLS/NXP/SDK_2_14_0_MIMXRT1170-EVKB
   export CMAKE_TOOLCHAIN_FILE=$QUL_ROOT/lib/cmake/Qul/toolchain/armgcc.cmake
   export QUL_TARGET_TOOLCHAIN_DIR=$QUL_TOOLS/arm_gcc_12_3_1
   export FREERTOS_DIR=$QUL_TOOLS/NXP/SDK_2_14_0_MIMXRT1170-EVKB/rtos/freertos/freertos-kernel

   set QUL_PLATFORM_NAME=mimxrt1170-evkb-freertos
   set QUL_BOARD_SDK_DIR=%QUL_TOOLS%\NXP\SDK_2_14_0_MIMXRT1170-EVKB
   set CMAKE_TOOLCHAIN_FILE=%QUL_ROOT%\lib\cmake\Qul\toolchain\armgcc.cmake
   set QUL_TARGET_TOOLCHAIN_DIR=%QUL_TOOLS%\arm_gcc_12_3_1
   set FREERTOS_DIR=%QUL_TOOLS%\NXP\SDK_2_14_0_MIMXRT1170-EVKB\rtos\freertos\freertos-kernel

3. If you built and installed the platform library as described in the previous section, follow instructions in step 4 to build your application.

   Otherwise, this step guides you build Qt Quick Ultralite from the modified sources and install it to a custom location. Before you begin, copy the Qt for MCUs version that you used to build the customized version. This ensures that the customized version also includes the host tools (qmltocpp, qmlinterfacegenerator, and so on) and the CMake configuration. The following example show how to build and install a customized version to QUL_INSTALL_DIR. The build is done in the directory defined by QUL_BUILD_DIR.

   LinuxWindows

   export QUL_VERSION=2.9.0
   export QUL_INSTALL_DIR=some/path/custom_qul
   export QUL_BUILD_DIR=some/path/custom_qul_build
   
   mkdir -p $QUL_INSTALL_DIR
   
   cp -r $QUL_ROOT/* $QUL_INSTALL_DIR
   
   mkdir -p $QUL_BUILD_DIR
   cd $QUL_BUILD_DIR
   
   cmake $QUL_ROOT -DQul_ROOT=$QUL_ROOT -G "Ninja" -DCMAKE_INSTALL_PREFIX=$QUL_INSTALL_DIR -DCMAKE_BUILD_TYPE=MinSizeRel -DCMAKE_TOOLCHAIN_FILE=$CMAKE_TOOLCHAIN_FILE -DQUL_TARGET_TOOLCHAIN_DIR=$QUL_TARGET_TOOLCHAIN_DIR -DQUL_BOARD_SDK_DIR=$QUL_BOARD_SDK_DIR -DQUL_PLATFORM=$QUL_PLATFORM_NAME -DQUL_BUILD_DEMOS=OFF -DQUL_BUILD_EXAMPLES=OFF -DQUL_GENERATORS=$QUL_ROOT/lib/cmake/Qul/QulGenerators.cmake -DFREERTOS_DIR=$FREERTOS_DIR -DQUL_VERSION=$QUL_VERSION
   
   cmake --build .
   cmake --install .
   
   # Before the next step, update QUL_ROOT and CMAKE_TOOLCHAIN_FILE to point to your custom version
   export QUL_ROOT=$QUL_INSTALL_DIR
   export CMAKE_TOOLCHAIN_FILE=$QUL_INSTALL_DIR/lib/cmake/Qul/toolchain/armgcc.cmake

   set QUL_VERSION=2.9.0
   set QUL_INSTALL_DIR=some\path\custom_qul
   set QUL_BUILD_DIR=some\path\custom_qul_build
   
   mkdir %QUL_INSTALL_DIR%
   
   xcopy %QUL_ROOT% %QUL_INSTALL_DIR% /e /y /q
   
   mkdir %QUL_BUILD_DIR%
   cd %QUL_BUILD_DIR%
   
   cmake %QUL_ROOT% -DQul_ROOT=%QUL_ROOT% -G "Ninja" -DCMAKE_INSTALL_PREFIX=%QUL_INSTALL_DIR% -DCMAKE_BUILD_TYPE=MinSizeRel -DCMAKE_TOOLCHAIN_FILE=%CMAKE_TOOLCHAIN_FILE% -DQUL_TARGET_TOOLCHAIN_DIR=%QUL_TARGET_TOOLCHAIN_DIR% -DQUL_BOARD_SDK_DIR=%QUL_BOARD_SDK_DIR% -DQUL_PLATFORM=%QUL_PLATFORM_NAME% -DQUL_BUILD_DEMOS=OFF -DQUL_BUILD_EXAMPLES=OFF -DQUL_GENERATORS=%QUL_ROOT%/lib/cmake/Qul/QulGenerators.cmake -DFREERTOS_DIR=%FREERTOS_DIR% -DQUL_VERSION=%QUL_VERSION%
   
   cmake --build .
   cmake --install .
   
   rem Before the next step, update QUL_ROOT and CMAKE_TOOLCHAIN_FILE to point to your custom version
   set QUL_ROOT=%QUL_INSTALL_DIR%
   set CMAKE_TOOLCHAIN_FILE=%QUL_INSTALL_DIR%/lib/cmake/Qul/toolchain/armgcc.cmake

4. Use the custom-built Qt Quick Ultralite to build your application, by setting QUL_ROOT to the directory where it is installed. Since the installation step will not install QulGenerators.cmake, QUL_ROOT_ORIGINAL needs to point to the original Qt Quick Ultralite installation folder. LinuxWindows

   # You can use the minimal example from the SDK.
   export APP_DIR=some/path/custom_app
   export QUL_ROOT=some/path/custom_qul
   export QUL_ROOT_ORIGINAL=some/path/original_qul
   mkdir $APP_DIR
   cd $APP_DIR
   mkdir build
   cd build
   
   cmake .. -G "Ninja" -DQul_ROOT=$QUL_ROOT -DCMAKE_BUILD_TYPE=MinSizeRel -DCMAKE_TOOLCHAIN_FILE=$CMAKE_TOOLCHAIN_FILE -DQUL_TARGET_TOOLCHAIN_DIR=$QUL_TARGET_TOOLCHAIN_DIR -DQUL_GENERATORS=$QUL_ROOT_ORIGINAL/lib/cmake/Qul/QulGenerators.cmake -DQUL_PLATFORM=$QUL_PLATFORM_NAME -DQUL_BOARD_SDK_DIR=$QUL_BOARD_SDK_DIR
   
   cmake --build .
   cmake --build . --target flash_<TARGET_NAME>

   rem You can use the minimal example from the SDK.
   set APP_DIR=some\path\custom_app
   set QUL_ROOT=some\path\custom_qul
   set QUL_ROOT_ORIGINAL=some\path\original_qul
   mkdir %APP_DIR%
   cd %APP_DIR%
   mkdir build
   cd build
   
   cmake .. -G "Ninja" -DQul_ROOT=%QUL_ROOT% -DCMAKE_BUILD_TYPE=MinSizeRel -DCMAKE_TOOLCHAIN_FILE=%CMAKE_TOOLCHAIN_FILE% -DQUL_TARGET_TOOLCHAIN_DIR=%QUL_TARGET_TOOLCHAIN_DIR% -DQUL_GENERATORS=%QUL_ROOT_ORIGINAL%/lib/cmake/Qul/QulGenerators.cmake -DQUL_PLATFORM=%QUL_PLATFORM_NAME% -DQUL_BOARD_SDK_DIR=%QUL_BOARD_SDK_DIR%
   
   cmake --build .
   cmake --build . --target flash_<TARGET_NAME>