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.

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:

QmlFiles

This node is used to List QML files for a project. Both relative or absolute paths to the QML files can be used.

Usage

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

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

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:

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:

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:

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:

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:

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.

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:

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:

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:

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:

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 :

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:

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

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

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:

When using static_library: