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. The main parameter that needs to be provided to qmlprojectexporter
is a .qmlproject
file. This file defines the project's structure and might depend on other .qmlproject module files.
qmlproject files
The syntax of .qmlproject file is based on the same syntax as Qml documents. They are used to describe the project structure. Similar to Qml documents, the .qmlproject files are composed 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 which version of the API should be used.
Nodes
Each Node configures a specific part of a project (Qml files, Images, Modules, among others). Some nodes can be defined multiple times in the Project root node, such as ImageFiles. Others should be defined only 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
Properties in .qmlproject files can be considered configuration parameters. Each node has a predefined set of possible configurations.
Configurations can be assigned for all nodes that support them in the project file when defined 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 are prefixed with "MCU.". For more information, see MCU.Config.
Nodes
Project
Each qmlproject
file contains the Project
node as its root node. This root node includes all other nodes that provide additional information about the project.
The qmlproject
file structure is limited to two levels: Project
and its children. Nodes introduced in a third level will be ignored.
Usage
Project { projectRootPath: "..." ... MCU.Config {...} ... ImageFiles {...} ... }
following is the list of available properties in the Project node:
A list of paths where module files live. | |
The QML source file defines the first UI screen for an application. | |
The root path of the project | |
A flag that marks the project as a QtMCUs project |
QmlFiles
This node is used to List QML files for a project. Both relative or absolute paths to the QML files can be used.
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:
Enables copying the QML files into the output directory | |
A directory containing QML files | |
A list of strings, specifies which variants to use when picking qml files. | |
A list of QML files. |
ImageFiles
The ImageFiles node adds the given image assets into the project.
Additionally, the properties specified in a given node affect how these assets are encoded. More than one ImageFiles node can be defined in a same project, for setting different properties per group of images.
If a given property is not defined in an ImageFiles node, the default value provided in the MCU.Config node is used. If not defined there, then a global default value is used.
Usage
Project { ... ImageFiles { files: [...] MCU.resourceOptimizeForRotation: true } ... }
following is the list of available properties in the ImageFiles node:
Defines the base path for the assets. | |
Adds a common prefix to the file's URI. | |
Identifies images that you can use as frames for AnimatedSpriteDirectory. | |
Specifies frame height for resource optimization of sprite animation. | |
Specifies frame width for resource optimization of sprite animation. | |
Defines the image cache policy. | |
Store image in compressed format. | |
Set the preferred pixel format for the image assets. | |
Enable optimizations for rotating the image at runtime. | |
Enable optimizations for scaling the image at runtime. | |
Define the asset runtime allocation type. | |
Define the asset's storage section. | |
Adds a directory containing the image assets. | |
A list of strings, specifies which variants to use when picking image files. | |
A list of image assets. |
Byte alignment for texture data | |
Enable optimization for splitting the image into opaque segments. |
FontFiles
This node is used for listing 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:
Adds all the font files in the given directory. | |
A list of strings, specifies which variants to use when picking font files. | |
A list of the font files to be added. |
TranslationFiles
This node can be used to add translation files to a project. More than one TranslationFiles node can be specified to add the translation files (.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, the function tr() can be used to wrap the translatable strings that are going to be referenced by the files provided here.
Usage
Project { ... TranslationFiles { files: [...] } ... }
following is the list of available properties in the TranslationFiles node:
Indicates whether to include or exclude source language strings. | |
Adds a directory containing the translation files. | |
A list of strings, specifies which variants to use when picking translation 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 they can be referenced in another QML file in the same project.
Usage
Project { ... InterfaceFiles { files: [...] } ... }
following is the list of available properties in the InterfaceFiles node:
Lists the QML imports. | |
Provides a directory containing the C++ interface files. | |
A list of strings, specifies which variants to use when picking header files. | |
List the C++ interface files. |
MCU.Config
This node is used to define default values for the QmlProject file. Nodes defined within the context of this node do not need the "MCU."
prefix, which is required if the same node 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 // "MCU." prefix is required } //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:
Adds the default font files from Qt for MCUs to the project. | |
This option controls automatic glyph generation. | |
Defines how to include the binary asset data for the image resources | |
Enables rendering complex scripts | |
Selects the style of the Qt Quick Controls. | |
Indicates whether to include JavaScript bytecode | |
Indicates whether to add #line directives to QML sources. | |
Sets a default font family for Text items. | |
Sets a default font quality for Text items. | |
A list of strings, specifies which variants to use by default for nodes in the qmlproject file. | |
Controls the font cache buffer preallocation. | |
Controls font cache priming. | |
Set maximum cache size used by font engine. | |
Selects a font engine for the project. | |
Configure copying of the application's font files to RAM for faster access. | |
Control copying pre-rasterized glyph data to RAM. | |
Configures the resource storage section for the font files. | |
Controls preallocation of the heap buffer used by the font engine. | |
Defines a maximum heap size for the font engine. | |
Controls whether to use vector outlines for text rendering | |
Configure copying of pre-rasterized glyph data to RAM for faster access. | |
Configure the runtime allocation type used when copying pre-rasterized glyph data to RAM. | |
Configure the resource storage section used for pre-rasterized glyph data. | |
Set the maximum paragraph size in characters. | |
Defines the maximum resource cache size for a runtime allocation type. | |
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. |
The default pixel format for transparent image assets. | |
Defines the minimum alignment for image data. | |
MCU.Config.platformOpaqueCompressedLosslessResourcePixelFormat | Defines a default pixel format for lossless compression of opaque image assets. |
Defines a default pixel format for opaque image assets. | |
Defines required pixel alignment for images. | |
Sets the render batch height for the given platform. |
MCU.Module
This node can be used to declare a qmlproject file as a module. Modules can provide 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 than can be used by qml projects using ModuleFiles.MCU.qulModules:
- Controls
- ControlsTemplates
- Shapes
- Timeline
following is the list of available properties in the MCU.Module node:
Generates a type information file for the module. | |
Defines a URI for the module. |
ModuleFiles
This node is used to import QML modules into the project.
Usage
Project { ... ModuleFiles { MCU.qulModules: [...] ... } ... }
following is the list of available properties in the ModuleFiles node:
A list of Qt Quick Ultralite modules that the project should link to. | |
Adds a directory containing the QML module files. | |
A list of strings, specifies which variants to use when picking module files. | |
Adds a list of the qmlproject files. |
Commandlines
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 plaintext 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 Qul 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 the \l Project.mainFile to be set 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 they are handled by the qmlprojectexporter call.
- qul_target_qml_sources
- qul_target_generate_interfaces
- qul_target_embed_translations
- qul_add_qml_module
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. The generated assets files can then be used by a build system of choice.
qmlprojectexporter --outdir output_directory myproject.qmlproject
Here is the extended list of qmlprojectexporter
's commandline arguments:
A path to BoardDefaults.qmlprojectconfig file holding default property values of a board. | |
Override controls style | |
Generate a file containing global default values and optional board defaults | |
Controls if a default entry point to the application will be generated | |
List the commandline parameters. | |
Comma separated list of include dirs. | |
Path to ResourceGenerator.exe (for RLE support with Traveo II boards) | |
A flag to disable exporting configuration information for build systems. | |
Disables exporting cpp sources. | |
Disables exporting modules within a project. | |
The output directory. | |
An optional identifier of the targeted platform. | |
Specify the path where the mapping of custom qml modules to default modules are listed . | |
Path to rc.exe (for MSVC toolchain). | |
A comma-separated list of selectors to pick a project variant. | |
Specify the type of target the generated source files are intended to. | |
An identifier of the toolchain that will be used for compiling the generated files. | |
Enable updating the translation files. | |
Print calls to other tools to standard output. | |
The path to the qmlproject file. |
qmlprojectexporter's generated files
The files generated in the output directory vary depending on which command line arguments were used. To understand better 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:
Constant | Description |
---|---|
my_project.qmlproject | the project's main configuration file |
main.qml | the 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 all the export arguments are disabled.
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 :
Constant | Description |
---|---|
output/config/my_project.1.compiler_outputs.txt | Lists all the files that would be generated by Qt Quick Ultralite tools. |
output/config/my_project.1.input.txt | Indicates which file will be used to generate c++ files, in the my_project case it's only main.qml. |
output/config/my_project.1.libraries.txt | Lists which libraries are needed to link against for a successful build. |
output/config/my_project.1.linker_options.txt | Tells which linker options are to be used to build the project. the previous arguments' configuration can be used to fetch information on what files or configurations are expected to be in the project 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 previous 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:
Constant | Description |
---|---|
output/config/input.json | A structured file listing all the input used by the project, which files are used by the modules imported by the project and recursively which files are sued by modules imported in imported modules. |
generate_files.txt | Holds key,value pairs and is used by CMake to deduce which files are generated, used mainly when --generate-entypoint is specified as the generated files can vary depending on the target type of the application (executable|static_library). |
To see the main effect of --no-export-modules consider the new project files
Constant | Description |
---|---|
module1/module1.qmlproject | A Configuration file for module1, should be imported in my_project.qmlproject using ModuleFiles |
module1/module1.qml | A Qml file listed in the module1 files and used in main.qml |
Running the previous qmlprojectexporter
command with the new files will result in the following
Constant | Description |
---|---|
output/module1/* | The folder containing the generated CPP files for module1 similar to the output/ folder |
output/config/module1.1.compiler_outputs.txt | Lists all the files that would be generated by Qt Quick Ultralite tools for module1. |
output/config/module1.1.input.txt | Indicates which file will be used to generate module1 c++ files. |
output/config/module1.1.libraries.txt | Additional library dependencies introduced by module1. |
output/config/module1.1.linker_options.txt | Tells Additional linker options introduced by module1. |
The configuration txt files will also be generated if --no-export-modules was omitted and --no-export-cpp was used.
Export Modules
The generated files in this step are not required and can be replaced by a custom entrypoint when needed. 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
New files will be introduced to the list of generated files depending on the --target-type flag. When using executable:
Constant | Description |
---|---|
output/main.cpp | the main.cpp containing the main() function for the application. |
When using static_library:
Constant | Description |
---|---|
output/qul_run.h | the The interface for the static library |
output/my_project_qul_run.cpp | The implementation of the static library interface. |
Available under certain Qt licenses.
Find out more.