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

CMake target properties for fonts

Deprecated source file properties for images

Deprecated CMake commands

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

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

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"]
}

Images

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

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
}

Modules

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"
    ]
}

Translations

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

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>)

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"]
    }
}