C

QmlProject Manual

Introduction

qmlprojectexporter is a tool that allows the automatic generation of C++ code for all the resources and .qml files included in your project. The resources can be Qml files, Images, Font files, Translation files, and C++ interfaces. You need to give a .qmlproject file as the main parameter to qmlprojectexporter. This file defines the project's structure and might depend on other .qmlproject module files.

qmlproject files

The syntax of a .qmlproject file uses the same syntax as Qml documents. The purpose of .qmlproject files is to describe the structure of a project.. Like QML documents, .qmlproject files consist of an import section followed by a hierarchy of nodes or objects, starting from the root Node (Project in this case), with each Node having a predefined set of properties. The import section consists mainly of "import QmlProject 1.3" which indicates that this is a .qmlproject file and specifies the version of the API that you are going to use.

Migration guide

You can migrate an existing project that depends on deprecated CMake APIs to use .qmlproject. Refer to the Migration guide to QmlProject for more information.

Exporting a project with platform sources

You can export a QmlProject together with platform sources using the qmlprojectexporter command-line utility. This simplifies the process of integrating Qt for MCUs into a 3rd party IDE or custom build system. See Exporting a Qt for MCUs project with platform sources for a detailed description of how to use this feature.

Nodes

Each Node configures a specific part of a project (Qml files, Images, Modules, among others). You might have the ability to define some nodes many times in the Project's root node, such as ImageFiles. Others you can only define once, for example, MCU.Module.

Warning: Currently, the depth of the .qmlproject file hierarchy is two, meaning the Project node is the only one containing nodes. Other nodes can only define properties.

Properties

You can consider Properties in .qmlproject files as configuration parameters. Each node has a predefined set of possible configurations.

You have the possibility to assign configurations to all nodes that support them in the project file when you place them in MCU.Config node, and the value defined in MCU.Config will take effect if the respective properties are not found in their default Node (such as ImageFiles). Those configuration properties have the "MCU." prefix. For more information, see MCU.Config.

Nodes

Project

Each qmlproject file has the Project node as its root node. This root node includes all other nodes that give more information about the project.

The qmlproject file structure has a limit of two levels: Project and its children. qmprojectexporter will ignore nodes placed in a third level.

Usage

Project {
    projectRootPath: "..."
    ...
    MCU.Config {...}
    ...
    ImageFiles {...}
    ...
}

following is the list of available properties in the Project node:

Project.importPaths

A list of paths where module files live.

Project.mainFile

The QML source file defines the first UI screen for an application.

Project.projectRootPath

The root path of the project

Project.qtForMCUs

A flag that marks the project as a Qt for MCUs project

QmlFiles

You can use this node to list QML files for a project. with the possibility to use both relative or absolute paths to the QML files.

Note: The relative path should be relative to the qmlproject file.

Usage

QmlFiles {
    files: ["src/other.qml"]
}

following is the list of available properties in the QmlFiles Node:

QmlFiles.copyQmlFiles

Enables copying the QML files into the output directory

QmlFiles.directory

A directory containing QML files

QmlFiles.fileSelector

A list of strings, specifies which variants to use when picking qml files.

QmlFiles.files

A list of QML files.

ImageFiles

The ImageFiles node adds the given image assets to the project.

Additionally, the properties specified in a given node affect how the qulrcc-tool encodes these assets.

You can have more than one ImageFiles in the same project, you will need it when setting different properties per group of images.

If you do not define a given property in an ImageFiles node, qmlprojectexporter will use the default value provided in the MCU.Config node. If not defined there, then it will rely on global default values.

Usage

Project {
    ...
    ImageFiles {
        files: [...]
        MCU.resourceOptimizeForRotation: true
    }
    ...
}

following is the list of available properties in the ImageFiles node:

ImageFiles.MCU.base

Defines the base path for the assets.

ImageFiles.MCU.prefix

Adds a common prefix to the file's URI.

ImageFiles.MCU.resourceAnimatedSprite

Identifies images that you can use as frames for AnimatedSpriteDirectory.

ImageFiles.MCU.resourceAnimatedSpriteFrameHeight

Specifies frame height for resource optimization of sprite animation.

ImageFiles.MCU.resourceAnimatedSpriteFrameWidth

Specifies frame width for resource optimization of sprite animation.

ImageFiles.MCU.resourceAnimatedSpriteOptimizations

Specifies the cropping image optimization mode to be used.

ImageFiles.MCU.resourceCachePolicy

Defines the image cache policy.

ImageFiles.MCU.resourceCompression

Store image in compressed format.

ImageFiles.MCU.resourceImagePixelFormat

Set the preferred pixel format for the image assets.

ImageFiles.MCU.resourceOptimizeForRotation

Enable optimizations for rotating the image at runtime.

ImageFiles.MCU.resourceOptimizeForScale

Enable optimizations for scaling the image at runtime.

ImageFiles.MCU.resourceRuntimeAllocationType

Define the asset runtime allocation type.

ImageFiles.MCU.resourceStorageSection

Define the asset's storage section.

ImageFiles.directory

Adds a directory containing the image assets.

ImageFiles.fileSelector

A list of strings, specifies which variants to use when picking image files.

ImageFiles.files

A list of image assets.

Experimental properties:

ImageFiles.MCU.Experimental.resourceAlignment

Byte alignment for texture data

ImageFiles.MCU.Experimental.resourceSplitImageOptimization

Enable optimization for splitting the image into opaque segments.

FontFiles

You can use this node to list font files required in a project. Refer to font formats for supported font file formats.

Usage

Project {
    ...
    FontFiles {
        files: [...]
    }
    ...
}

following is the list of available properties in the FontFiles node:

FontFiles.directory

Adds all the font files in the given directory.

FontFiles.fileSelector

A list of strings, specifies which variants to use when picking font files.

FontFiles.files

A list of the font files to be added.

TranslationFiles

You can use this node to add translation files to a project (.ts).

qmlprojectexporter calls the corresponding tool to convert these translation files into .qm files, which is a binary format used by Qt for managing the translations.

In the QML sources, you can either use qsTr() or qsTrId() to mark the translatable strings. At runtime, the translation system looks for the matching string in the translation file for the current system locale.

Usage

Project {
    ...
    TranslationFiles {
        files: [...]
    }
    ...
}

The following properties are supported in the TranslationFiles node:

TranslationFiles.MCU.omitSourceLanguage

Indicates whether to include or exclude source language strings.

TranslationFiles.directory

Adds a directory containing the translation files.

TranslationFiles.fileSelector

A list of strings, specifies which variants to use when picking translation files.

TranslationFiles.files

Adds the list of the translations files.

InterfaceFiles

This node provides the C++ interface-specific configuration. It is possible to define C++ interfaces and make them visible to Qml, without requiring to import them in a QML file. The qmlprojectexporter generates the QML code based on the header files for these C++ interfaces, so that another QML file in the same project could reference them.

Usage

Project {
    ...
    InterfaceFiles {
        files: [...]
    }
    ...
}

following is the list of available properties in the InterfaceFiles node:

InterfaceFiles.MCU.qmlImports

Lists the QML imports.

InterfaceFiles.directory

Provides a directory containing the C++ interface files.

InterfaceFiles.fileSelector

A list of strings, specifies which variants to use when picking header files.

InterfaceFiles.files

List the C++ interface files.

MCU.Config

You can use this node to define default values for the QmlProject file. Properties defined within the context of this node do not need the "MCU." prefix, which you would need to use if the same property was part of a specific node such as ImageFiles, FontFiles, and so on.

Usage

//node1
MCU.Config {
  // Project-wide default value for resourceOptimizeForRotation.
  resourceOptimizeForRotation: true
}

ImageFiles {
  // Here resourceOptimizeForRotation was explicitly defined for a specific ImageFiles node.
  MCU.resourceOptimizeForRotation: false // requires the "MCU."prefix
}

//node2
ImageFiles {
  // MCU.resourceOptimizeForRotation was not defined but the value \c true will be
  // picked from MCU.Config.
}

following is the list of available properties in MCU.Config:

MCU.Config.addDefaultFonts

Adds the default font files from Qt for MCUs to the project.

MCU.Config.autoGenerateGlyphs

This option controls automatic glyph generation.

MCU.Config.binaryAssetOptions

Defines how to include the binary asset data for the image resources

MCU.Config.complexTextRendering

Enables rendering complex scripts

MCU.Config.controlsStyle

Selects the style of the Qt Quick Controls.

MCU.Config.debugBytecode

Indicates whether to include JavaScript bytecode

MCU.Config.debugLineDirectives

Indicates whether to add #line directives to QML sources.

MCU.Config.defaultFontFamily

Sets a default font family for Text items.

MCU.Config.defaultFontQuality

Sets a default font quality for Text items.

MCU.Config.fileSelector

A list of strings, specifies which variants to use by default for nodes in the qmlproject file.

MCU.Config.fontCachePrealloc

Controls the font cache buffer preallocation.

MCU.Config.fontCachePriming

Controls font cache priming.

MCU.Config.fontCacheSize

Set maximum cache size used by font engine.

MCU.Config.fontEngine

Selects a font engine for the project.

MCU.Config.fontFilesCachePolicy

Configure copying of the application's font files to RAM for faster access.

MCU.Config.fontFilesRuntimeAllocationType

Control copying pre-rasterized glyph data to RAM.

MCU.Config.fontFilesStorageSection

Configures the resource storage section for the font files.

MCU.Config.fontHeapPrealloc

Controls preallocation of the heap buffer used by the font engine.

MCU.Config.fontHeapSize

Defines a maximum heap size for the font engine.

MCU.Config.fontVectorOutlinesDrawing

Controls whether to use vector outlines for text rendering

MCU.Config.glyphsCachePolicy

Configure copying of pre-rasterized glyph data to RAM for faster access.

MCU.Config.glyphsRuntimeAllocationType

Configure the runtime allocation type used when copying pre-rasterized glyph data to RAM.

MCU.Config.glyphsStorageSection

Configure the resource storage section used for pre-rasterized glyph data.

MCU.Config.maxParagraphSize

Set the maximum paragraph size in characters.

MCU.Config.maxResourceCacheSize

Defines the maximum resource cache size for a runtime allocation type.

MCU.Config.mergeStaticTextGlyphs

Combine the glyphs for a StaticText item into a single image.

MCU.Config.platformAlphaCompressedLosslessResourcePixelFormat

Defines a default format for lossless compression of transparent image assets.

MCU.Config.platformAlphaPixelFormat

The default pixel format for transparent image assets.

MCU.Config.platformImageAlignment

Defines the minimum alignment for image data.

MCU.Config.platformOpaqueCompressedLosslessResourcePixelFormat

Defines a default pixel format for lossless compression of opaque image assets.

MCU.Config.platformOpaquePixelFormat

Defines a default pixel format for opaque image assets.

MCU.Config.platformPixelWidthAlignment

Defines required pixel alignment for images.

MCU.Config.platformRenderBatchHeight

Sets the render batch height for the given platform.

MCU.Module

This node's role is to declare a qmlproject file as a module. Modules can contain assets, interfaces, QML components and translations. A qmlproject-based project can make use of a qmlproject-based module by use of QmlProject's ModuleFiles node.

Note: A qmlproject file can contain one instance of the MCU.Module node.

Usage

// mymodule.qmlproject
import QmlProject 1.3
Project {
  MCU.Module {
    uri: "custom.module"
  }
  QmlFiles {
    files: ["CustomBox.qml"]
  }
}

// CustomBox.qml
// ... some qml code

// main.qmlproject
import QmlProject 1.3
Project {
  QmlFiles {
    files: ["main.qml"]
  }
  ModuleFiles {
    files: ["mymodule.qmlproject"]
  }

// main.qml
import QtQuick 2.15
import custom.module
Rectangle {
  CustomBox {}
}

Qul Modules

Qul comes with 4 predefined modules that projects can use with ModuleFiles.MCU.qulModules:

  • Controls
  • ControlsTemplates
  • Shapes
  • Timeline

following is the list of available properties in the MCU.Module node:

MCU.Module.generateQmltypes

Generates a type information file for the module.

MCU.Module.uri

Defines a URI for the module.

ModuleFiles

You can use this node to import QML modules into a project.

Usage

Project {
    ...
    ModuleFiles {
        MCU.qulModules: [...]
        ...
    }
    ...
}

following is the list of available properties in the ModuleFiles node:

ModuleFiles.MCU.qulModules

A list of Qt Quick Ultralite modules that the project should link to.

ModuleFiles.directory

Adds a directory containing the QML module files.

ModuleFiles.fileSelector

A list of strings, specifies which variants to use when picking module files.

ModuleFiles.files

Adds a list of the qmlproject files.

Command line reference

qmlprojectexporter

Use the qmlprojectexporter to export the QML sources, image assets and fonts into compilable c++ code. It parses a .qmlproject file listing the assets with exporting options. In addition, qmlprojectexporter also exports plain-text lists of the imported and exported files, for convenient automatic use by a 3rd party build system, such as CMake.

Usage of qmlprojectexporter in a CMake project

Using qmlprojectexporter with a CMake build system is straightforward and the custom CMake macro qul_add_target already takes care of calling qmlprojectexporter with the right parameters, and it requires defining the QML_PROJECT argument followed by a qmlproject file as shown next.

// Adding the \l GENERATE_ENTRYPOINT option will generate an application entrypoint automatically,
// but it requires setting the \l Project.mainFile property
qul_add_target(my_project QML_PROJECT my_project.qmlproject GENERATE_ENTRYPOINT)

// Note for a working Qul application with CMake it is still required to call \l app_target_setup_os macro
// after adding the qmlproject target.
app_target_setup_os(myproject)

When using qmlprojectexporter, the following CMake macros are not needed as calling qmlprojectexporter implies performing the same function.

All CMake flags replaced by a QmlProject alternative are marked as deprecated in CMake Manual.

Using standalone qmlprojectexporter

When using a build system other than CMake it is still possible to use qmlprojectexporter directly. You can use the generated assets files in a build system of choice.

qmlprojectexporter --outdir output_directory myproject.qmlproject

Here is the extended list of qmlprojectexporter's command-line arguments:

--boarddefaults

Path to the BoardDefaults<@op>.</@op>qmlprojectconfig file with default property values for a board

--controls-style

Override controls style

--generate-default-values

Generate a file containing global default values and optional board defaults

--generate-entrypoint

Controls if qmlprojectexporter generates a default application entry-point

--help

List the command-line parameters.

--ide-sources-outdir

The output directory for hardware code source files copied from an IDE.

--include-dirs

Comma-separated list of include dirs.

--include-ide-generated-hw-code

Include IDE generated hardware code in the project

--infineon-resource-generator

Path to ResourceGenerator.exe (for RLE support with Traveo II boards)

--no-export-configuration

A command-line option to disable exporting configuration information for build systems.

--no-export-cpp

Disables exporting C++ sources.

--no-export-modules

Disables exporting modules within a project.

--outdir

The output directory.

--platform

An optional identifier of the targeted platform.

--platform-build-dir

The build directory for the customized platform.

--platform-metadata

The metadata file describing the platform target.

--platform-outdir

The output directory for exported platform sources.

--project-outdir

The output directory for IDE project files.

--project-type

Sets the type of the exported project

--qml-mappings-dir

Specify the path to the directory containing files with mappings of custom QML modules to default modules.

--qmlproject-outdir

The output directory for generated files.

--resource-compiler

Path to rc.exe (for MSVC toolchain).

--selector

A comma-separated list of selectors to pick a project variant.

--skip-qml-generation

Skip exporting a QmlProject.

--target-type

Specify the type of target using the generated source files.

--toolchain

Specify the toolchain used for compiling the generated files.

--update-translations

Enable updating the translation files.

--verbose

Print calls to other tools to standard output.

qmlprojectfile

The path to the qmlproject file.

qmlprojectexporter's generated files

The files generated in the output directory vary depending on which command line arguments you are using. To better understand what role qmlprojectexporter plays in the project build process see Qt Quick Ultralite tools Following is the list of possible generated files depending on the next example:

Considering the following startup project files:

ConstantDescription
my_project.qmlprojectthe project's main configuration file
main.qmlthe entrypoint file to the project

No Export

qmlprojectexporter --no-export-cpp --no-export-modules --no-export-configuration --outdir output my_project.qmlproject

Running this command will create the output directory but no files within it, as the command disables all exports.

Export Configurations

qmlprojectexporter --no-export-cpp --no-export-modules --outdir output my_project.qmlproject

Removing the --no-export-configuration argument will result in the following files :

ConstantDescription
output/config/my_project.1.compiler_outputs.txtLists all the files generated by Qt Quick Ultralite tools.
output/config/my_project.1.input.txtIndicates which input files qmlprojectexporter used to generate c++ files, in the my_project case it's only main.qml.
output/config/my_project.1.libraries.txtLists which libraries a build system needs to link against for a successful build.
output/config/my_project.1.linker_options.txtTells which linker options the build system has to add to build the project.

The earlier command gives the possibility to fetch information on what resources or configurations the project expects without the overhead of generating the files.

Export CPP files

qmlprojectexporter --no-export-modules --outdir output my_project.qmlproject

While removing --no-export-configuration will list the configurations, removing --no-export-cpp will generate all the actual CPP files for the project. Qt Quick Ultralite tools gives an introduction to which tools are responsible for which files.

Export Modules

qmlprojectexporter --outdir output my_project.qmlproject

Running qmlprojectexporter on the earlier example without the --no-export-modules will not have a big effect on the output folder as the example does not use any module file. however two files will show up on the output directory used by 3rd party tools when the project is fully exported with its modules, those files are:

ConstantDescription
output/config/input.jsonA structured file listing all the input used by the project, which files the module imported by the project uses and recursively for files modules imported in imported modules use.
generate_files.txtHolds key,value pairs and that CMake uses to deduce which entrypoint files qmlprojectexporter generates, used mainly when specifying --generate-entypoint, as the generated files can vary depending on the application's target type (executable|static_library).

To see the main effect of --no-export-modules consider the new project files

ConstantDescription
module1/module1.qmlprojectA Configuration file for module1, imported in my_project.qmlproject using ModuleFiles
module1/module1.qmlA Qml file present in the module1 QmlFiles and used in main.qml

Running the earlier qmlprojectexporter command with the new files will result in the following

ConstantDescription
output/module1/*The folder containing the generated CPP files for module1 similar to the output/ folder
output/config/module1.1.compiler_outputs.txtLists all the files that Qt Quick Ultralite tools generate for module1.
output/config/module1.1.input.txtIndicates the files used to generate module1 c++ files.
output/config/module1.1.libraries.txtmore library dependencies introduced by module1.
output/config/module1.1.linker_options.txtTells more linker options introduced by module1.

qmlprojectexporter will generate configuration txt files if you omit --no-export-modules and use --no-export-cpp.

Export Modules

The generated files in the next step are not required when you have an existing entrypoint. Considering the following command.

//[1]
qmlprojectexporter --generate-entrypoint --target-type executable --outdir output my_project.qmlproject
//[2]
qmlprojectexporter --generate-entrypoint --target-type static_library --outdir output my_project.qmlproject

qmlprojectexporter introduces new files to the list of generated files depending on the --target-type flag. When using executable:

ConstantDescription
output/main.cppthe main.cpp containing the main() function for the application.

When using static_library:

ConstantDescription
output/qul_run.hthe The interface for the static library
output/my_project_qul_run.cppThe implementation of the static library interface.

Available under certain Qt licenses.
Find out more.