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.

In addition to the instructions below you can refer to the type-specific configurations here

• GHS Multi IDE
• CMake
• CMSIS
• Zephyr

Usage

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

Generating a project for the first time

When generating a project for the first time, platform sources and generated sources from the .qmlproject file are included by default. To override the default behavior, use --export-platform, --no-export-platform or --no-export-qml.

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 your Qt for MCUs install directory. Example:

  <QUL_ROOT>/bin/qmlprojectexporter.exe --platform stm32f769i-discovery-baremetal --toolchain iar --project-type cmake --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_stm32f769i-discovery-baremetal_32bpp_Windows_iar-export.json --project-type cmake --outdir my_project my_project.qmlproject

For some target platforms and IDEs, you need the driver sources from the board SDK to run the platform code. Use the --board-sdk and --include-ide-generated-hw-code command-line arguments to include these sources in the generated project.

The following example command generates a project with Qt for MCUs platform sources, driver code from the board SDK, and generated UI sources based on the specified .qmlproject. If you also add the --generate-entrypoint command-line argument, qmlprojectexporter generates a main() or a qul_run() function, which enables running the project on the target:

<QUL_ROOT>/bin/qmlprojectexporter.exe --platform rh850-d1m1a-baremetal --toolchain ghs --project-type ghs --outdir my_project --include-ide-generated-hw-code --board-sdk /path/to/board-sdk my_project.qmlproject --generate-entrypoint

If you have an existing project, you can use qmlprojectexporter to add Qt for MCUs platform and UI code to it with the --extend-project command-line argument. Extending a project requires the same information as when generating a project from scratch, see the example below:

<QUL_ROOT>/bin/qmlprojectexporter.exe --platform rh850-d1m1a-baremetal --toolchain ghs --project-type ghs my_project.qmlproject --extend-project my_project/main_project_file.gpj

If you do not set an output directory with --outdir, qmlprojectexporter uses the base directory of the main project file specified in --extend-project.

Updating an existing project

When qmlprojectexporter adds Qt for MCUs to a project, it simultaneously stores the command-line arguments used for exporting in exporter_settings.json. This simplifies subsequent updates if anything changes in the .qmlproject.

To update an existing project that is already extended (or created) with Qt for MCUs sources and subprojects, provide the main project and .qmlproject file:

<QUL_ROOT>/bin/qmlprojectexporter.exe my_project.qmlproject --update-project my_project/main_project_file.gpj

For GHS projects a preconfigured workspace is added to the main project, check GHS Multi IDE QUL Workspace for how to use it to trigger the update.

If an existing project already has the application entrypoint, see Running Qt Quick Ultralite in applications for instructions on how to integrate Qt for MCUs into a custom main() function. If it does not, use the --generate-entrypoint argument to create one and add it to the project.

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.

• Exported platform sources are located in <outdir>/QtMCUs/platform.
• UI sources generated from the QmlProject are located in <outdir>/QtMCUs/generated.
• IDE project files are located in <outdir>/<project-type>. If the project-type is ghs, then the IDE files path is <outdir>/GHS.

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

• --qmlproject-outdir
• --platform-outdir
• --project-outdir

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. Refer to Generated GHS project content for a detailed description of the generated project content.

Project type CMake

Use --project-type cmake to generate a CMake package and export platform sources into the output directory.

See Generating CMake projects on how to use the package in your CMake project.

Project type Zephyr

Use --project-type zephyr to generate a CMake package containing the Qt Quick Ultralite application sources, platform sources, and a Zephyr project. This can be only used with reference Zephyr platform ports.

See Generating projects for Zephyr for more info.

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 --no-export-qml.

Exporting a prebuilt platform

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

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 \
    --no-export-qml \
    --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.

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 need to be added to the sources. This option only applies to GNU GCC compilers. 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 --include-ide-generated-hw-code 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 \
       --include-ide-generated-hw-code \
       --project-type cmake | ghs \
       --no-export-qml

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>/libQulCore_<ARCHITECTURE>-<COMPILER>-<BUILD_TYPE>.a
   • <BUILD_DIR>/libQulControls_<ARCHITECTURE>-<COMPILER>-<BUILD_TYPE>.a
   • <BUILD_DIR>/libQulPNGDecoderLodePNG_<ARCHITECTURE>-<COMPILER>-<BUILD_TYPE>.a
   • <BUILD_DIR>/libQulPNGDecoderNull_<ARCHITECTURE>-<COMPILER>-<BUILD_TYPE>.a
   • <BUILD_DIR>/libQulShapes_<ARCHITECTURE>-<COMPILER>-<BUILD_TYPE>.a
   • <BUILD_DIR>/libQulControlsTemplates_<ARCHITECTURE>-<COMPILER>-<BUILD_TYPE>.a
   • <BUILD_DIR>/libQulTimeline_<ARCHITECTURE>-<COMPILER>-<BUILD_TYPE>.a
   • <BUILD_DIR>/libQulMonotypeUnicodeEngineShaperDisabled_<ARCHITECTURE>-<COMPILER>-<BUILD_TYPE>.a
   • <BUILD_DIR>/libQulMonotypeUnicode_<ARCHITECTURE>-<COMPILER>-<BUILD_TYPE>.a

Additional information

QUL_STD_STRING_SUPPORT CMake option

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.