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
In addition to the instructions below you can refer to the IDE-specific configurations here
Trigger project generation by choosing a project type and platform target. The available project types are
"none". Use the --project-type command-line argument to choose a type.
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,
qmlprojectexporterlocates 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>/libfor installer packages and in the build directory for custom platform builds. The metadata file name uses the following format:
<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
Note: If the interfaces included in the
.qmlproject rely on external source files, add them manually to the project.
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
Note: Currently, you can only extend a GHS project. Refer to Extending a GHS project for more specific details.
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
To update an existing project that is already extended (or created) with Qt for MCUs sources and subprojects, provide the main project and
<QUL_ROOT>/bin/qmlprojectexporter.exe my_project.qmlproject --update-project my_project/main_project_file.gpj
Note: This assumes that the
qmlprojectexporter settings cache file (
exporter_settings.json) is found in the project's base directory.
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 Entry point to Qt Quick Ultralite application 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.
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.
--outdir is not set,
qmlprojectexporter uses the current working directory.
- Exported platform sources are located in
- UI sources generated from the QmlProject are located in
- IDE project files are located in
<outdir>/<project-type>. If the project-type is
ghs, then the IDE files path is
You can override the default directories using the corresponding command-line arguments:
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.
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 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.
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.
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.
<QUL_DIR>/bin/qmlprojectexporter.exe \ --platform-metadata <QUL_DIR>/QulPlatformTargets_<PLATFORM_NAME>-export.json \ --project-type cmake \ --no-export-qml \ --outdir <DESTINATION_FOLDER>
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:
<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>
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.
- Add the exported platform and application source files to your project in the IDE.
- Add assembly source files to the sources list of your project. Passing
--toolchain GNUto the qmlprojectexporter enables generates binary files (incbin) for resources. In that case,
qul_assets.Sneeds to be added to the sources. This option only applies to GNU GCC compiler. For other compilers, resources are generated as C++ arrays.
- 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.
qmlprojectexporterto 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
- Add include paths, pre-defines, and toolchain flags.
<PLATFORM_EXPORT_DIR>/IDE-Import-Instructions.txtfile lists all the required compiler and linker settings for the project. This includes architecture flags, include paths, and preprocessor defines for toolchain in use.
- 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.
- Add the following prebuilt Qt Quick Ultralite libraries to the linker settings:
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.