Qt Quick Ultralite Platform Exporter

The Qt Quick Ultralite Platform Exporter exports the platform-specific code into a separate folder to enable importing and building.

Qt Quick Ultralite libraries are configured to use link-time optimization by default. This requires using the exact same compiler version that was used to build the Qt Quick Ultralite libraries.

Note: Since Qt for MCUs 2.5, the platformexporter executable has been replaced with qmlprojectexporter. The platformexporter executable is still available with Qt for MCUs for compatibility, but it calls qmlprojectexporter. Migrate to using the qmlprojectexporter as this executable may not be available with the future releases.

qmlprojectexporter can export platform-specific code into either a CMake project or a GHS Multi IDE project. You can trigger this by specifying the platform target and the project type for the export. The project type must be either "ghs" or "cmake". Specify the platform by either passing the metadata file for the platform, or let qmlprojectexporter locate the correct metadata file by using the --platform and --toolchain arguments.

Pass the --no-export-qml argument to qmlprojectexporter to get a project without any UI code.

Exporting a prebuilt platform

<QUL_DIR>/bin/platformexporter.exe \
    --infile <QUL_DIR>/lib/QulPlatformTargets_<PLATFORM_NAME>-export.json \

or with qmlprojectexporter:

<QUL_DIR>/bin/qmlprojectexporter.exe \
    --platform-metadata <QUL_DIR>/lib/QulPlatformTargets_<PLATFORM_NAME>-export.json \
    --project-type cmake \
    --no-export-qml \

Exporting platform sources

Create an empty file in the build directory <BUILD_DIR>/.cmake/api/v1/query/codemodel-v2, and reconfigure and rebuild the tree to let CMake produce a metadata file (PlatformExport CMake target is enough). The metadata file is located in the build directory at, <BUILD_DIR>/QulPlatformTargets_<PLATFORM_NAME>-export.json For example, the metadata file for the STM32F469 platform would be: QulPlatformTargets_stm32f469i-discovery-baremetal_24bpp_Linux_armgcc-export.json

<QUL_DIR>/bin/platformexporter.exe \
    --infile <BUILD_DIR>/lib/QulPlatformTargets_<PLATFORM_NAME>-export.json \
    --outdir <DESTINATION_FOLDER> \
    --builddir <BUILD_DIR>

or with qmlprojectexporter:

<QUL_DIR>/bin/qmlprojectexporter.exe \
    --platform-metadata <BUILD_DIR>/lib/QulPlatformTargets_<PLATFORM_NAME>-export.json \
    --project-type cmake \
    --no-export-qml \
    --outdir <DESTINATION_FOLDER> \
    --platform-build-dir <BUILD_DIR>

Exporting a QML application

Since Qt for MCUs 2.5, qmlprojectexporter is able to export UI sources and platform sources in a single GHS Multi IDE project. For the CMake project type, the generated UI sources must be added to the project manually.

GHS Multi IDE project

Use the following command to export a GHS Multi IDE project with its subprojects for the UI code, and exported platform sources:

<QUL_DIR>/bin/qmlprojectexporter \
    --include-dirs <QUL_SOURCE>,<BUILD_DIR>/include \
    --boarddefaults <QUL_SOURCE>/platform/boards/<SOME_BOARD>/cmake/BoardDefaults.qmlprojectconfig \
    --outdir my_project \
    --platform <SOME_BOARD> \
    --toolchain ghs \
    --project-type ghs \
    --board-sdk <BOARD_SDK_DIR> \
    --include-ide-generated-hw-code \

See qmlprojectexporter for more information about the generated project.

CMake or other build systems

Use qmlprojectexporter to generate UI sources based on the .qmlproject file.

<HOST_BUILD>/bin/qmlprojectexporter \
    --include-dirs <QUL_SOURCE>,<BUILD_DIR>/include \
    --boarddefaults <QUL_SOURCE>/platform/boards/<SOME_BOARD>/cmake/BoardDefaults.qmlprojectconfig \
    --outdir my_app \
    --toolchain <IAR|GCC> \

Integrate Qt for MCUs into your project

This is an example main.cpp to show the code that is required to integrate the exported UI and platform sources into your project.

#include "minimal.h"

#include <qul/application.h>
#include <qul/qul.h>

int main()
    Qul::Application _qul_app;
    static struct ::minimal _qul_item;
    return 0;

IDE settings

Follow these steps to integrate the exported source to a 3rd party IDE or build system.

Note: These steps are performed automatically for GHS Multi IDE projects. Follow the steps manually when using another IDE.

  1. Add the exported platform and application source files to your project in the IDE.
  2. Add assembly source files to the sources list of your project. Passing --toolchain GNU to the qmlprojectexporter enables generates binary files (incbin) for resources. In that case, qul_font_files_loader.S and qul_assets.S needs to be added to the sources. This option only applies to GNU GCC compiler. For other compilers, resources are generated as C++ arrays.
  3. Add board files which include pin muxing, clock configuration, and hardware initialization code.

    You can add these files using one of the following options:

    • Custom board files can be generated with MCU vendor tools such as STM32 CubeMX or NXP MCUXPresso config tools.
    • Use --includeIDEgeneratedHWCode with the platform exporter to export board files provided by Qt for MCUs for the reference boards. You can also specify a target directory using the --IDEsourcesdir <folderpath> option.

    For example:

    <QUL_DIR>/bin/platformexporter.exe \
        --infile <BUILD_DIR>/lib/QulPlatformTargets_<PLATFORM_NAME>-export.json \
        --outdir <DESTINATION_FOLDER> \
        --builddir <BUILD_DIR> \
        --IDEsourcesdir <IDE_PROJECT_ROOT_DIR>/board \

    or with qmlprojectexporter

    <QUL_DIR>/bin/qmlprojectexporter.exe \
        --platform-metadata <BUILD_DIR>/lib/QulPlatformTargets_<PLATFORM_NAME>-export.json \
        --outdir <DESTINATION_FOLDER> \
        --platform-build-dir <BUILD_DIR> \
        --ide-sources-outdir <IDE_PROJECT_ROOT_DIR>/board \
        --project-type cmake | ghs
  4. Add include paths, pre-defines, and toolchain flags.

    The <PLATFORM_EXPORT_DIR>/IDE-Import-Instructions.txt file lists all the required compiler and linker settings for the project. This includes architecture flags, include paths, and preprocessor defines for toolchain in use.

  5. Add path to the exported linker script in the project linker settings.

    Linker scripts for the Qt Quick Ultralite application require custom sections to be defined for resource data and caches. The exported linker scripts from the Platform Exporter tool can be used directly in the IDE.

    For ARMGCC: <QUL_EXPORT_FOLDER>/platform/boards/nxp/<board>/cmake/armgcc/<linker_file>.ld For IAR: <QUL_EXPORT_FOLDER>/platform/boards/nxp/<board>/cmake/iar/<linker_file>.icf

  6. Add the following prebuilt Qt Quick Ultralite libraries to the linker settings:
    • <BUILD_DIR>/libQulControlsTemplates_<ARCHITECTURE>-<COMPILER>-<BUILD_TYPE>.a
    • <BUILD_DIR>/libQulMonotypeUnicodeEngineShaperDisabled_<ARCHITECTURE>-<COMPILER>-<BUILD_TYPE>.a
    • <BUILD_DIR>/libQulMonotypeUnicode_<ARCHITECTURE>-<COMPILER>-<BUILD_TYPE>.a

Additional information


The architecture requires using the QUL_STD_STRING_SUPPORT CMake option while configuring your project, if the core library was built with it. Otherwise the application crashes.

Available under certain Qt licenses.
Find out more.