C

Migration guide to QmlProject

Description

Since Qt Quick Ultralite 2.4, QmlProject files (a file with the extension .qmlproject) describe a project with all its sources, resources, modules and configuration settings. This guide describes how you can migrate an existing Qt for MCUs project from CMake to QmlProject. When migrating an existing project, replace the deprecated CMake APIs with the corresponding nodes in QmlProject. Refer to QmlProject Manual for an explanation of the QmlProject API and how to use it. The CMake Manual has more information about CMake APIs.

The qmlprojectexporter tool processes the .qmlproject, and invokes other tools to generate the required sources for the project. It lets you define your Qt for MCUs project independent of CMake. You can also use it together with CMake, by using qul_add_target() with the QML_PROJECT option. This custom CMake command invokes qmlprojectexporter behind the scenes. The CMakeLists.txt example that you find later in the guide, illustrates how you can do this using CMake.

List of deprecated CMake APIs and their replacements

Deprecated CMake variables

Note: The variables with the PLATFORM prefix apply to a platform port, and their replacements belong in the platform's BoardDefaults.qmlprojectconfig file. See Platform Migration Guide to Qt for MCUs 2.3 for more details.

Deprecated CMake variablesQmlProject replacementDescription
QUL_DEBUG_BYTECODEMCU.Config.debugBytecodeAdds JavaScript bytecode as comments into generated sources
QUL_DEBUG_LINE_DIRECTIVESMCU.Config.debugLineDirectivesAdds #line directives into the generated sources.
QUL_PLATFORM_DEFAULT_RESOURCE_COMPRESSED_LOSSLESS_PIXEL_FORMAT_ALPHAMCU.Config.platformAlphaCompressedLosslessResourcePixelFormatDefines a default format for lossless compression of the transparent image assets.
QUL_PLATFORM_DEFAULT_RESOURCE_COMPRESSED_LOSSLESS_PIXEL_FORMAT_OPAQUEMCU.Config.platformOpaqueCompressedLosslessResourcePixelFormatThe default pixel format for lossless compression of opaque image assets.
QUL_PLATFORM_DEFAULT_RESOURCE_PIXEL_FORMAT_ALPHAMCU.Config.platformAlphaPixelFormatThe default pixel format for transparent image assets.
QUL_PLATFORM_DEFAULT_RESOURCE_PIXEL_FORMAT_OPAQUEMCU.Config.platformOpaquePixelFormatThe default pixel format for opaque image assets.
QUL_PLATFORM_REQUIRED_IMAGE_ALIGNMENTMCU.Config.platformImageAlignmentThe minimum alignment required for image data on the given platform.
QUL_PLATFORM_REQUIRED_PIXEL_WIDTH_ALIGNMENTMCU.Config.platformPixelWidthAlignmentThe image width will be a multiple of this value on the given platform.

CMake target properties for fonts

Deprecated CMake target propertiesQmlProject replacementDescription
QUL_FONT_FILESFontFiles.filesList of paths of font files.
QUL_AUTO_GENERATE_GLYPHSMCU.Config.autoGenerateGlyphsThis option controls automatic glyph generation for static font engine.
QUL_COMPLEX_TEXT_RENDERINGMCU.Config.complexTextRenderingEnables rendering complex scripts.
QUL_DEFAULT_FONT_FAMILYMCU.Config.defaultFontFamilyDefault font family for Text elements.
QUL_DEFAULT_FONT_QUALITYMCU.Config.defaultFontQualityDefault font quality for Text elements.
QUL_FONT_CACHE_PREALLOCMCU.Config.fontCachePreallocControls preallocation of the font cache buffer.
QUL_FONT_CACHE_PRIMINGMCU.Config.fontCachePrimingEnable font cache priming.
QUL_FONT_CACHE_SIZEMCU.Config.fontCacheSizeSet maximum cache size used by font engine.
QUL_FONT_ENGINEMCU.Config.fontEngineEnables provided font engine.
QUL_FONT_FILES_RESOURCE_CACHE_POLICYMCU.Config.fontFilesCachePolicyConfigure copying of the application's font files.
QUL_FONT_FILES_RESOURCE_RUNTIME_ALLOCATION_TYPEMCU.Config.fontFilesRuntimeAllocationTypeConfigure runtime allocation type used when copying the application's font files.
QUL_FONT_FILES_RESOURCE_STORAGE_SECTIONMCU.Config.fontFilesStorageSectionConfigure the resource storage section used for the application's font files.
QUL_FONT_HEAP_PREALLOCMCU.Config.fontHeapPreallocControls preallocation of the heap buffer used by font engine.
QUL_FONT_HEAP_SIZEMCU.Config.fontHeapSizeSet maximum heap size for the font engine.
QUL_FONT_VECTOR_OUTLINES_DRAWINGMCU.Config.fontVectorOutlinesDrawingUse vector outlines for text rendering.
QUL_GLYPHS_RESOURCE_CACHE_POLICYMCU.Config.glyphsCachePolicyConfigure copying of pre-rasterized glyph data to RAM for faster access.
QUL_GLYPHS_RESOURCE_RUNTIME_ALLOCATION_TYPEMCU.Config.glyphsRuntimeAllocationTypeConfigure runtime allocation type used when copying pre-rasterized glyph data to RAM
QUL_GLYPHS_RESOURCE_STORAGE_SECTIONMCU.Config.glyphsStorageSectionConfigure the resource storage section used for pre-rasterized glyph data to RAM.
QUL_MAX_PARAGRAPH_SIZEMCU.Config.maxParagraphSizeSet the maximum paragraph size.
QUL_CONTROLS_STYLEMCU.Config.controlsStyleOverrides the Controls style.

Deprecated source file properties for images

Deprecated CMake source file propertiesQmlProject replacementDescription
QUL_RESOURCE_CACHE_POLICYImageFiles.MCU.resourceCachePolicyDefine the image cache policy.
QUL_RESOURCE_COMPRESSIONImageFiles.MCU.resourceCompressionStore image in compressed format.
QUL_RESOURCE_IMAGE_PIXEL_FORMATImageFiles.MCU.resourceImagePixelFormatSet the preferred pixel format for the image.
QUL_RESOURCE_OPTIMIZE_FOR_ROTATIONImageFiles.MCU.resourceOptimizeForRotationEnable optimizations for rotating the image at runtime.
QUL_RESOURCE_OPTIMIZE_FOR_SCALEImageFiles.MCU.resourceOptimizeForScaleEnable optimizations for scaling the image at runtime.
QUL_RESOURCE_RUNTIME_ALLOCATION_TYPEImageFiles.MCU.resourceRuntimeAllocationTypeDefine the asset runtime allocation type.
QUL_RESOURCE_STORAGE_SECTIONImageFiles.MCU.resourceStorageSectionDefine the asset storage section.

Deprecated CMake commands

Deprecated CMake commandsQmlProject replacementDescription
qul_add_qml_moduleModuleFiles (Node in <MainProject>.qmlproject)Adds a QML module to the project. The module must have its own .qmlproject file.
MCU.Module (Node in <module>.qmlproject)This node designates the .qmlproject file as belonging to a module, and defines its URI.
qul_add_resourceImageFiles (Node)Adds image resources to the target.
qul_set_maximum_resource_cache_sizeMCU.Config.maxResourceCacheSize (Property)Sets the maximum resource cache size for a given runtime allocation type.
qul_target_embed_translationsTranslationFiles (Node)Embeds translations from .ts files.
qul_target_generate_interfacesInterfaceFiles (Node)Exposes the exported C++ classes to the QML context.
qul_target_qml_sourcesQmlFiles (Node)Adds QML source files to a target.

Migrating an existing project

To migrate your project to Qt for MCUs 2.4 or later, add a .qmlproject file. This file can have any name, but this guide uses <MainProject>.qmlproject. Your project's CMakeLists.txt needs significant changes to remove the use of deprecated CMake APIs. Their replacement belong in the .qmlproject file.

QML files

Deprecated CMake commandsQmlProject replacementDescription
qul_target_qml_sourcesQmlFiles (Node)Adds QML source files to a target.

The QmlFiles node is responsible for adding QML source files to the project. It accepts a list of source files in its files property. This node replaces the qul_target_qml_sources() custom CMake command. Remove references to this from the CMake project file when migrating to Qt for MCUs 2.4.

# DEPRECATED
qul_target_qml_sources(<target> WelcomeScreen.qml Menu.qml)

Replace all references to qul_target_qml_source in the CMakeLists.txt with the following in the .qmlproject file, <MainProject>.qmlproject:

QmlFiles {
    files: [
        "WelcomeScreen.qml",
        "Menu.qml"
    ]
}

C++ interfaces

Deprecated CMake commandsQmlProject replacementDescription
qul_target_generate_interfacesInterfaceFiles (Node)Exposes the exported C++ classes to the QML context.

Use the InterfaceFiles node to add the C++ header files into the project and generate interfaces that are accessible in the QML context. The files property accepts a list of C++ header files and adds them to the project. You can also use the MCU.qmlImports property to add the extra QML imports that the interfaces need.

The InterfaceFiles node and its properties replace the deprecated CMake command qul_target_generate_interfaces(). Remove all references to this command from your project when migrating to Qt for MCUs 2.4 or later.

Older versions of Qt for MCUs trigger interface generation in CMakeLists.txt:

# DEPRECATED
qul_target_generate_interfaces(
    <target>
    interface1.h interface2.h
    QML_IMPORTS SomeQmlModule
)

Replace all instances of this CMake command with the InterfaceFiles node in your project's .qmlproject file:

InterfaceFiles {
    files: [
        "interface1.h",
        "interface2.h"
    ]
    MCU.qmlImports: ["SomeQmlModule"]
}

Note: qmlprojectexporter stores the interfaces that it generates in the output directory. QmlProject does not have a replacement for the OUTPUT_DIRECTORY argument in qul_target_generate_interfaces().

Images

Deprecated CMake commandsQmlProject replacementDescription
qul_add_resourceImageFiles (Node)Adds image resources to the target.
Deprecated CMake source file propertiesReplacement (ImageFiles properties)Description
QUL_RESOURCE_CACHE_POLICYMCU.resourceCachePolicy (Property)Define the image cache policy.
QUL_RESOURCE_COMPRESSIONMCU.resourceCompression (Property)Store image in compressed format.
QUL_RESOURCE_IMAGE_PIXEL_FORMATMCU.resourceImagePixelFormat (Property)Set the preferred pixel format for the image.
QUL_RESOURCE_OPTIMIZE_FOR_ROTATIONMCU.resourceOptimizeForRotation (Property)Enable optimizations for rotating the image at runtime.
QUL_RESOURCE_OPTIMIZE_FOR_SCALEMCU.resourceOptimizeForScale (Property)Enable optimizations for scaling the image at runtime.
QUL_RESOURCE_RUNTIME_ALLOCATION_TYPEMCU.resourceRuntimeAllocationType (Property)Define the asset runtime allocation type.
QUL_RESOURCE_STORAGE_SECTIONMCU.resourceStorageSection (Property)Define the asset storage section.

Use the ImageFiles node to add image files to the project, and configure their properties. You can list the image assets under the files property. If you need to change the default configuration of these assets, add it to the ImageFiles node that adds the asset. This node replaces the qul_add_resource() and set_source_files_properties() CMake APIs.

The following snippet uses deprecated CMake APIs in a project's CMakeLists.txt:

# DEPRECATED
set_source_files_properties(
    img1.png
    img2.png
    PROPERTIES
        QUL_RESOURCE_COMPRESSION ON
)
set_source_files_properties(
    img2.png
    PROPERTIES
        QUL_RESOURCE_OPTIMIZE_FOR_ROTATION ON
)

# DEPRECATED
qul_add_resource(<target> FILES img1.png img2.png)

When you migrate to Qt for MCUs 2.4 or newer, replace these with two ImageFiles nodes in your <MainProject>.qmlproject, one for each set of property configurations:

ImageFiles {
    files: ["img1.png"]
    MCU.resourceCompression: true
}

ImageFiles {
    files: ["img2.png"]
    MCU.resourceCompression: true
    MCU.resourceOptimizeForRotation: true
}

Project default properties

It is possible to define default values for a set of image properties in the MCU.Config node. This value then applies for all resources added to the project, except for assets specifically overriding it in their ImageFiles node.

Using the example in the earlier section, the following snippet illustrates how to enable resourceCompression by default. It uses the MCU.Config node for this so that it applies to all resources in the project. If a resource needs to override the default setting, it can do so in the ImageFiles node that adds the resource. The last ImageFiles node illustrates this by disabling compression for the "img3.png" resource only.

The following example shows how to set the project-level default values for a property using the MCU.Config node:

MCU.Config {
    MCU.resourceCompression: true
}

ImageFiles {
    files: ["img1.png"]
}

ImageFiles {
    files: ["img2.png"]
    MCU.resourceOptimizeForRotation: true
}

ImageFiles {
    files: ["img3.png"]
    MCU.resourceCompression: false
}

Fonts

Deprecated CMake target propertiesFontFiles propertiesDescription
QUL_FONT_FILESfiles (Property)List of paths of font files.
Deprecated CMake target propertiesMCU.Config propertiesDescription
QUL_AUTO_GENERATE_GLYPHSautoGenerateGlyphs (Property)This option controls automatic glyph generation for static font engine.
QUL_COMPLEX_TEXT_RENDERINGcomplexTextRendering (Property)Enables rendering complex scripts.
QUL_CONTROLS_STYLEcontrolsStyle (Property)Overrides the Controls style.
QUL_DEFAULT_FONT_FAMILYdefaultFontFamily (Property)Default font family for Text elements.
QUL_DEFAULT_FONT_QUALITYdefaultFontQuality (Property)Default font quality for Text elements.
QUL_FONT_CACHE_PREALLOCfontCachePrealloc (Property)Controls preallocation of the font cache buffer.
QUL_FONT_CACHE_PRIMINGfontCachePriming (Property)Enable font cache priming.
QUL_FONT_CACHE_SIZEfontCacheSize (Property)Set maximum cache size used by font engine.
QUL_FONT_ENGINEfontEngine (Property)Enables provided font engine.
QUL_FONT_FILES_RESOURCE_CACHE_POLICYfontFilesCachePolicy (Property)Configure copying of the application's font files.
QUL_FONT_FILES_RESOURCE_RUNTIME_ALLOCATION_TYPEfontFilesRuntimeAllocationType (Property)Configure runtime allocation type used when copying the application's font files.
QUL_FONT_FILES_RESOURCE_STORAGE_SECTIONfontFilesStorageSection (Property)Configure the resource storage section used for the application's font files.
QUL_FONT_HEAP_PREALLOCfontHeapPrealloc (Property)Controls preallocation of the heap buffer used by font engine.
QUL_FONT_HEAP_SIZEfontHeapSize (Property)Set maximum heap size for the font engine.
QUL_FONT_VECTOR_OUTLINES_DRAWINGfontVectorOutlinesDrawing (Property)Use vector outlines for text rendering.
QUL_GLYPHS_RESOURCE_CACHE_POLICYglyphsCachePolicy (Property)Configure copying of pre-rasterized glyph data to RAM for faster access.
QUL_GLYPHS_RESOURCE_RUNTIME_ALLOCATION_TYPEglyphsRuntimeAllocationType (Property)Configure runtime allocation type used when copying pre-rasterized glyph data to RAM
QUL_GLYPHS_RESOURCE_STORAGE_SECTIONglyphsStorageSection (Property)Configure the resource storage section used for pre-rasterized glyph data to RAM.
QUL_MAX_PARAGRAPH_SIZEmaxParagraphSize (Property)Set the maximum paragraph size.

You can add the font files to your project, by using its files property in a FontFiles node. This node replaces the QUL_FONT_FILES CMake target property. You can add the font-specific configuration, such as the font engine selection, using the MCU.Config node. All the font properties in the earlier list replace the corresponding CMake target properties, which you should remove from the project when migrating to Qt for MCUs 2.4 or later.

# DEPRECATED
set_target_properties(<target>
    PROPERTIES
        QUL_FONT_FILES MyFont.ttf
        QUL_FONT_ENGINE Spark
        QUL_DEFAULT_FONT_FAMILY default
        QUL_MAX_PARAGRAPH_SIZE 80
)

You have to use two different nodes to define this configuration in the QmlProject:

FontFiles {
    files: ["MyFont.ttf"]
}

MCU.Config {
    fontEngine: "Spark"
    defaultFontFamily: "default"
    maxParagraphSize: 80
}

Note: The addDefaultFonts property does not have a corresponding CMake API. It lets you control the use of default fonts that you get with the Qt for MCUs SDK. This property is true by default. If you don't need the default fonts, set it to false.

Modules

Deprecated CMake commandsQmlProject replacementDescription
qul_add_qml_moduleModuleFiles (Node in <MainProject>.qmlproject)Adds a QML module to the project. The module must have its own .qmlproject file.
MCU.Module (Node in <Module>.qmlproject)This node designates the .qmlproject file as belonging to a module, and defines its URI.

Since Qt for MCUs 2.4, a module should have its own .qmlproject file. This file works similarly to the main project's .qmlproject file, but it must include exactly one instance of the MCU.Module node defining the module's URI. As shown in the table, the combination of a ModuleFiles node in <MainProject>.qmlproject and a separate .qmlproject file for each custom module replaces the deprecated CMake command qul_add_qml_module().

Including the module in the main project

The files property of a ModuleFiles node accepts a list of paths to the custom modules' .qmlproject files.

In older versions of Qt for MCUs, you could add a module to a project using the qul_add_qml_module CMake API. The following example demonstrates how it's done:

# DEPRECATED
qul_add_qml_module(
    <target>
    URI MyModule
    QML_FILES CustomComponent.qml
)

Since Qt for MCUs 2.4, you can add a module to a project's .qmlproject file. The following example demonstrates how it's done in <MainProject>.qmlproject:

ModuleFiles {
    files: ["<Module>.qmlproject"]
}

Creating a custom module

A module's .qmlproject file must have exactly one instance of the MCU.Module node defining the module's URI. Except for this node, a module's .qmlproject file works the same as any other .qmlproject file.

The following snippet is the complete contents of <Module>.qmlproject used in the earlier section. It describes a module with the URI, MyModule, which has a single QML file, CustomComponent.qml.

import QmlProject 1.3

Project {
    MCU.Module {
        uri: "MyModule"
    }

    QmlFiles {
        files: ["CustomComponent.qml"]
    }
}

Qt Quick Ultralite modules

The ModuleFiles node can also add modules that are part of the Qt for MCUs SDK to the project. If you are using a ModuleFiles node for this purpose, remove the corresponding target_link_libraries() from the project's CMakeListst.txt.

The ModuleFiles node has the property MCU.qulModules, which expects a list of strings specifying which module to add to the project.

ModuleFiles {
    MCU.qulModules: [
        "Controls",
        "ControlsTemplates",
        "Shapes",
        "Timeline"
    ]
}

Note: You can also use a ModuleFiles node to link to the Qt for MCUs modules, besides the custom modules. It is possible to combine adding both the custom modules and Qt for MCUs modules in the same ModuleFiles node.

Translations

Deprecated CMake commandsQmlProject replacementDescription
qul_target_embed_translationsTranslationFiles (Node)Embeds translations from .ts files.

The TranslationFiles node replaces the deprecated custom CMake command qul_target_embed_translations(). When you port to Qt for MCUs 2.4 or later, remove all references to this command.

This node accepts a list of translation files (with extension .ts) in the files property. The MCU.omitSourceLanguage boolean property lets you control whether to use the source language in the application.

CMakeLists.txt using the deprecated command:

# DEPRECATED
qul_target_embed_translations(
    <target>
    translation.nb_NO.ts
    translation.lv_LV.ts
    [OMIT_SOURCE_LANGUAGE]
)

A TranslationFiles node in <MainProject>.qmlproject replaces the above command:

TranslationFiles {
    files: [
        "translation.nb_NO.ts",
        "translation.lv_LV.ts"
    ]
    MCU.omitSourceLanguage: true|false
}

Maximum resource cache size

Deprecated CMake commandQmlProject replacement (MCU.Config node)Description
qul_set_maximum_resource_cache_sizemaxResourceCacheSize (Property)Sets the maximum resource cache size for a given runtime allocation type.

All projects that use older versions of Qt for MCUs, define resource cache sizes for different allocation types using the qul_set_maximum_resource_cache_size() CMake API. Since Qt for MCUs 2.4, this CMake API is deprecated. Replace all references to it by its corresponding node in QmlProject, which is the maxResourceCacheSize property in the MCU.Config node.

The following snippet shows an example using qul_set_maximum_resource_cache_size() in the project's CMakeLists.txt:

# DEPRECATED
qul_set_maximum_resource_cache_size(
    <target>
    CACHE_SIZE 512
)
qul_set_maximum_resource_cache_size(
    <target>
    CACHE_SIZE 1024
    RUNTIME_ALLOCATION_TYPE 1
)
qul_set_maximum_resource_cache_size(
    <target>
    CACHE_SIZE 2048
    RUNTIME_ALLOCATION_TYPE 128
)

The maxResourceCacheSize property in the <MainProject>.qmlproject file replaces the above snippet as follows:

MCU.Config {
    maxResourceCacheSize: [
        [512],      // 512 bytes cache for resources using the default runtime allocation type
        [1024, 1],  // 1024 bytes cache for resources using runtime allocation type 1
        [2048, 128] // 2048 bytes cache for resources using runtime allocation type 128
    ]
}

Target and application variants

Sometimes it is necessary to use different source files or different property configurations for the same application on different target platforms, or to configure application variants. This section describes how to do this in Qt for MCUs 2.4 and later.

File variants

The idea of file selectors provides a simple way to differentiate which variant of a source file or resource to use when building the project for a specific target. When using file selectors, place the file variants in the correct directory. See the documentation for fileSelector for a more detailed description of how to use selectors properly. When adding a target in CMake, use the SELECTORS argument in qul_add_target() to pick a file variant for a specific target.

# This target uses the default variant of all files
qul_add_target(<target>
    QML_PROJECT <MainProject>.qmlproject
)

# This target uses the "big" variant of all files where the variant is available
qul_add_target(<target_big>
    QML_PROJECT <MainProject>.qmlproject
    SELECTORS big
)

It is also possible to use file selectors only in certain .qmlproject files or in specific nodes of a QmlProject file using the fileSelector property. The following snippet uses the small file selector for all nodes where it is available, and uses the landscape selector only for the MainScreen.qml source file.

import QmlProject 1.3
Project {
    MCU.Config {
        fileSelector: ["small"]
    }

    QmlFiles {
        files: ["MainScreen.qml"]
        fileSelector: ["landscape"]
    }

    ImageFiles {
        files: ["img.png"]
    }
}

A QmlProject file for each target

If each target handles certain resources like images or fonts differently, the settings for this is usually found in the MCU.Config node or an ImageFiles node in the .qmlproject file. In this case, it might be necessary to have different .qmlproject files for the different configurations. For example, a project for two different target platforms, where only one of them has insufficient flash memory and needs to compress certain image assets. In such a case, create two separate qmlproject files.

<MainProject>.qmlproject:

ImageFiles {
    files: ["img.png"]
}

<MainProject>_smallflash.qmlproject:

ImageFiles {
    files: ["img.png"]
    MCU.resourceCompression: true
}

In this case, pass the correct QmlProject must to the target in CMake, as in the following snippet

# Adding target with limited flash memory
qul_add_target(
    <target_smallflash>
    QML_PROJECT <MainProject>_smallflash.qmlproject
)

# Adding target with more flash memory
qul_add_target(
    <target>
    QML_PROJECT <MainProject>.qmlproject
)

Custom platform ports

The process for custom platform ports is the same as for Qt for MCUs 2.3. Refer to Platform Migration Guide for instructions on how to migrate a custom platform port to Qt for MCUs 2.4 and newer.

Migrating platform ports

A .qmlprojectconfig file should have the default settings for a platform. This file has the same syntax as a .qmlproject file, and qmlprojectexporter uses it as the source for platform-level default values.

Platform ports since Qt for MCUs 2.3 should already have this file in place. For detailed instruction for porting an older platform to Qt for MCUs 2.3 and newer, refer to the Platform Migration Guide to Qt for MCUs 2.3.

Using QmlProject with CMake

Since Qt for MCUs 2.4, the qmlprojectexporter tool parses a project's .qmlproject file(s) and runs the relevant tools to generate code for the target platform. qmlprojectexporter places all the generated files in a predetermined output directory. This makes it easier to integrate Qt for MCUs into a build system of your choice. For more details on what qmlprojectexporter does and how to use it manually, refer to the qmlprojectexporter documentation. The following section demonstrates how to use this tool from CMake.

Compared to earlier versions of Qt for MCUs, changes to the CMake API are significant. All the assets, source files, and property configurations now live in a .qmlproject file. The existing qul_add_target() custom CMake command accepts a .qmlproject file as argument. This argument prompts CMake to run qmlprojectexporter and generate source files for the project and create a build target for those files. The following snippet demonstrates how to build a Qt for MCUs project using CMake with a .qmlproject file.

cmake_minimum_required(VERSION 3.21.1)

project(<project_title> VERSION 0.0.1 LANGUAGES C CXX ASM)

find_package(Qul)

# This is where qmlprojectexporter is invoked
qul_add_target(<target>
    QML_PROJECT <MainProject>.qmlproject
    [GENERATE_ENTRYPOINT]
)

app_target_setup_os(<target>)

Note: When using the GENERATE_ENTRYPOINT option in qul_add_target() to prompt entrypoint generation, the .qmlproject file must define the entrypoint QML file with the mainFile property. See qul_add_target for details.

Project migration example

The following example demonstrates how to migrate an existing CMake project to the QmlProject format in Qt for MCUs 2.4 and later. The example only demonstrates the contents of a sample CMakeLists.txt and .qmlproject files.

The migrated project is still built with CMake, but without the deprecated APIs, CMakeLists.txt is much simpler. The project has two new .qmlproject files: one for the module and another for the main project.

CMake project

This example project uses deprecated CMake APIs, so the next section demonstrates how you can migrate it. The following is the original project's CMakeLists.txt:

CMakeFiles.txt:

cmake_minimum_required(VERSION 3.21.1.)

project(<project> VERSION 1.0 LANGUAGES C CXX ASM)

find_package(Qul)

qul_add_target(<target>)

# DEPRECATED
# Add QML sources
qul_target_qml_sources(<target> MainScreen.qml Menu.qml)

# DEPRECATED
# Generate QML interfaces to C++ code
qul_target_generate_interfaces(<target> test_model.h QML_IMPORTS QtQuick)

# DEPRECATED
# Add QML module
qul_add_qml_module(
    <target>
    URI MyModule
    QML_FILES CustomComponent.qml
)

# DEPRECATED
# Add translation files (keep source language)
qul_target_embed_translations(<target> translation.fr_FR.ts translation.de_DE.ts)

# DEPRECATED
# Set default setting for resource compression
set(QUL_DEFAULT_RESOURCE_COMPRESSION ON)

# DEPRECATED
# Set resource file properties
set_source_files_properties(
    progress_spinner.png
    PROPERTIES
        QUL_OPTIMIZE_FOR_ROTATION ON
)
set_source_files_properties(
    background_city.png
    background_forest.png
    PROPERTIES
        QUL_RESOURCE_CACHE_POLICY "OnDemand"
        QUL_RESOURCE_STORAGE_SECTION "CustomSegment"
        QUL_RESOURCE_RUNTIME_ALLOCATION_TYPE "128"
        QUL_RESOURCE_COMPRESSION OFF
)

# DEPRECATED
# Add image resources
qul_add_resource(
    <target> FILES
        progress_spinner.png
        background.png
        background_city.png
        background_forest.png
)

# DEPRECATED
# Add fonts
set_target_properties(
    <target>
    PROPERTIES
        QUL_FONT_ENGINE "Spark"
        QUL_FONT_FILES "font.ttf"
        QUL_DEFAULT_FONT_FAMILY "default"
        QUL_MAX_PARAGRAPH_SIZE 80
)

# DEPRECATED
# Define resource cache sizes
qul_set_maximum_resource_cache_size(
    <target>,
    32800
)
qul_set_maximum_resource_cache_size(
    <target>,
    15600,
    RUNTIME_ALLOCATION_TYPE 1
)
qul_set_maximum_resource_cache_size(
    <target>,
    512900,
    RUNTIME_ALLOCATION_TYPE 128
)

# Link the Qul::Controls library
target_link_libraries(<target> PRIVATE Qul::Controls)

# Setup os (baremetal or freertos)
app_target_setup_os(<target>)

# Generate default entrypoint from QML source
app_target_default_entrypoint(<target> MainScreen)

Migrated project

Since Qt for MCUs 2.4, this project needs two .qmlproject files, one for the module and another for the main project.

When building with CMake, the qul_add_target command takes the main project's .qmlproject file as the QML_PROJECT argument, prompting qmlprojectexporter to generate the required files.

CMakeLists.txt:

cmake_minimum_required(VERSION 3.21.1.)

project(<project> VERSION 1.0 LANGUAGES C CXX ASM)

find_package(Qul)

# Add the target using a QmlProject file
# Generate a custom entrypoint based on the mainFile property with GENERATE_ENTRYPOINT
qul_add_target(<target> QML_PROJECT MainProject.qmlproject GENERATE_ENTRYPOINT)

app_target_setup_os(<target>)

MainProject.qmlproject:

import QmlProject 1.3

Project {

    mainFile: "MainScreen.qml"

    QmlFiles {
        files: ["Menu.qml"]
    }

    InterfaceFiles {
        files: ["test_model.h"]
        MCU.qmlImports: ["QtQuick"]
    }

    ModuleFiles {
        files: ["MyModule.qmlproject]
        MCU.qulModules: [
            "Qul::Controls"
        ]
    }

    // Image resources are added in ImageFiles nodes.
    // Use one node per unique configuration of properties
    ImageFiles {
        files: [
            "background_city.png",
            "background_forest.png"
        ]
        MCU.resourceCachePolicy: "OnDemand"
        MCU.resourceStorageSection: "CustomSegment"
        MCU.resourceRuntimeAllocationType: 128
        MCU.resourceCompression: false
    }

    ImageFiles {
        files: ["progress_spinner.png"]
        MCU.resourceOptimizeForRotation: true
    }

    ImageFiles {
        files: ["background.png"]
    }

    FontFiles {
        files: ["font.ttf"]
    }

    TranslationFiles {
        files: [
            "translation.fr_FR.ts",
            "translation.de_DE.ts"
        ]
    }

    MCU.Config {
        // Font properties
        fontEngine: "Spark"
        defaultFontFamily: "default"
        maxParagraphSize: 80

        // Image properties
        resourceCompression: true

        // Storage
        maxResourceCacheSize: [
            [32800],
            [15600, 1],
            [512900, 128]
        ]

    }
}

MyModule.qmlproject:

import QmlProject 1.3

Project {
    MCU.Module {
        uri: "MyModule"
    }

    QmlFiles {
        files: ["CustomComponent.qml"]
    }
}

See also QmlProject Manual.

Available under certain Qt licenses.
Find out more.