Exporting a Qt for MCUs project with platform sources

You can use qmlprojectexporter to generate a Qt for MCUs project with platform sources for your selected target, and generated UI sources for each .qmlproject file.


Trigger project generation by choosing a project type and platform target. The available project types are "ghs", "cmake", and "none". Use --project-type command-line argument to choose a type.

A Qt for MCUs installation comes with platform metadata, which are used for export. Specify a platform target using one of the following two methods:

  • Specify the platform with the --platform command-line argument, and the toolchain with --toolchain. Using this information, qmlprojectexporter locates the correct metadata file in our Qt for MCUs install directory. Example:
    <QUL_ROOT>/bin/qmlprojectexporter.exe --platform rh850-d1m1a-baremetal --toolchain ghs --project-type ghs --outdir my_project my_project.qmlproject
  • Specify the platform metadata file with the --platform-metadata command-line argument. The platform metadata file is located in <QUL_ROOT>/lib for installer packages and in the build directory for custom platform builds. The metadata file name uses the following format: QulPlatformTargets_<PLATFORM_NAME>-export.json. Example:
    <QUL_ROOT>/bin/qmlprojectexporter.exe --platform-metadata <QUL_ROOT>/lib/QulPlatformTargets_rh850-d1m1a-baremetal_32bpp_Windows_ghs-export.json--project-type ghs --outdir my_project my_project.qmlproject

Project structure

Specify the output directory for the project with the --outdir command-line argument. By default, the platform sources, the generated UI sources, and the project files including them are placed in separate directories under the output directory.

Note: If --outdir is not set, qmlprojectexporter uses the current working directory.

  • Exported platform sources are located in <outdir>/QtMCUs/platform.
  • UI sources generated from the QmlProject are located in <outdir>/QtMCUs/generated.
  • GHS MULTI IDE project files are located in <outdir>/GHS.

You can override the default directories using the corresponding command-line arguments:

Project types

Project type None

The default project type is "none", which means qmlprojectexporter will not export the platform sources and IDE-specific project files. Generated UI files are placed directly in the output directory specified by --outdir. In this case it is not necessary to specify a platform target.

Project type GHS

To generate a GHS MULTI IDE project with Qt for MCUs sources, use --project-type ghs.

The generated project consists of the following GHS MULTI IDE project files:

  1. <outdir>/GHS/project.gpj The main project file defines the target architecture and some macros simplifying paths in subprojects.
  2. <outdir>/GHS/prj/program.gpj The main program file contains program-wide compile defines, compile options, linker directives, include directories and linker scripts. It also lists the subprojects used by the application.
  3. <outdir>/GHS/prj/drivers.gpj The subproject file including all the low level drivers included from the board SDK which are needed by Qt for MCUs. This project may be empty if the --include-ide-generated-hw-code flag is not set.
  4. <outdir>/GHS/prj/application.gpj An empty subproject for your convenience. Add main.cpp and other backend code to this subproject.
  5. <outdir>/GHS/prj/QtMCUs/qul_platform.gpj A subproject for the exported Qt for MCUs platform sources.
  6. <outdir>/GHS/prj/QtMCUs/qul_app.gpj A subproject adding UI files generated from the main .qmlproject file.
  7. <outdir>/GHS/prj/QtMCUs/qul_module_<ModuleName>.gpj A subproject for each .qmlproject module, adding the UI source files generated for the module.

Project type CMake

Use --project-type cmake to generate a CMakeLists.txt and export platform sources into the output directory. The platform sources are also added to the Qt4MCUPlatform target in the CMake project file.

Use this project type to export a project for other 3rd party IDEs or build systems. Refer to the IDE-Import-Instructions.txt file in <outdir>/platform for more information.

Note: The qmlprojectexporter command-line utility is not designed to export a standalone CMake project. If building a Qt for MCUs project with CMake exclusively, do not use the command-line utility directly. See Usage of qmlprojectexporter in a CMake project for further instructions.

Platform export

You can use qmlprojectexporter to export Qt for MCUs platform sources without a QmlProject. To do this, specify a project type and platform as described above, together with the additional command-line argument --skip-qml-generation.

Note: 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.

Exporting a prebuilt platform

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

Exporting sources from a custom platform build

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 (It is enough to build the PlatformExport CMake target). 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/qmlprojectexporter.exe \
    --platform-metadata <QUL_DIR>/QulPlatformTargets_<PLATFORM_NAME>-export.json \
    --project-type cmake \
    --skip-qml-generation \
    --outdir <DESTINATION_FOLDER> \
    --platform-build-dir <BUILD_DIR>

Integrating Qt for MCUs into a 3rd party IDE

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 qmlprojectexporter to export board files provided by Qt for MCUs for the reference boards. You can also specify a target directory using the --ide-sources-outdir option.

    For example (Use the "cmake" project type unless specifically exporting a GHS MULTI IDE project):

    <QUL_DIR>/bin/qmlprojectexporter.exe \
        --platform-metadata $BUILD_DIR/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 export 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.