Use the Generator

This topic describes how to use the QtIF generator.

Introduction

The Generator is a Python script that can be run manually or using the Build System Integration. This script uses QFace as the autogenerator framework which parses the Interface Definition Language (IDL) file, generates the domain model (similar to an Abstract Syntax Tree (AST)) and then feeds it to the generator. Depending on the type of the project to generate, different formats are specified.

Command Line Parameters

To run the generation, use the following command:

$$[QT_HOST_LIBEXECS]/ifcodegen/generate.py -T $$[QT_INSTALL_DATA]/ifcodegen-templates
--format=backend_simulator interface.qface out_dir

The options and parameters are:

Currently, based on the --template value, the generator can generate multiple types of projects with a given IDL file:

Configure the Generator

The generator's Python script parses the input files and creates a domain model. This domain model is then passed as a context to the Jinja template engine. Use the Generation YAML file to specify which files to generate. Afterwards, you can use an Annotation YAML file to add more information to the IDL file, which is generator specific.

Generation YAML

After the domain model tree is created, this tree is traversed and each leaf of the domain model object tree (module, interface, structure, and so on) is passed to a specific Jinja template defined by the configuration file.

The Generation YAML file defines which template to use to generate which file. Suppose you want to generate a header file for each module in your domain model. But, a module can have multiple interfaces, so, you want to use a different header file for each interface and structure. In this case, the Generation YAML file defines a set of rules to specify which template file to use and how to name them.

This YAML file must have the following structure:

frontend:
    module:
        documents:
            - "{{module.module_name|lower}}plugin.h": "plugin.h.tpl"
    interface:
        documents:
            - '{{interface|lower}}backend.h': 'backend.h.tpl'

For every entity, there's a list of templates that must be called, when traversing this entity in the domain model tree. Here, the YAML file defines a list of documents, which need to be generated for all modules and a list for all interfaces. Every list entry consists of two parts; the first part is the name of the file that needs to be created, as specified in the Jinja template language format. The value of the object property used in the template's name is processed and substituted into the template, thus forming the final name of the file to create. The second part is the name of the template to use. For the Interface Framework generator, you must specify rules for three kinds of entities: modules, interfaces and structures. See the QFace Rule Base Generation Documentation for more information.

Annotations YAML

Currently, not all aspects of the interface description can be expressed using the IDL itself. For instance, there is no language construct to define a default value for a property or a range of valid values a property can take. Still, this can be achieved via a mechanism called Annotations. Annotations provide freedom and flexibility to express any concepts and constructs.

The code snippet below shows an example of using annotations in the IDL. Here, we define an interface that is zoned, and specify its ID.

@config: {zoned: true, id: "org.qt-project.interfaceframework.ClimateControl/1.2"}

It does not make sense to place all of the annotations in the main IDL file. For instance, you may need to define some aspects of the auto-test code generation. Such annotations can be put in the YAML file that accompanies the main IDL file, with the same name. During the parse phase QFace automatically picks this file up and merges the annotation specified in this YAML file with those defined in the IDL file.

Since the accompanying YAML file is always picked up automatically, it won't work for annotations that you need for some specific projects, such as when generating a backend plugin. For this use case, you can pass multiple additional annotation YAML files to the generator.

In QtInterfaceFramework, the following annotations are used to define IDLs:

@config: {interfaceBuilder: "FunctionName"}

@config: {zoned: true}

@config: {id: "org.qt.project.interfaceframework.ClimateControl/1.0"}

@config: {getter_name: "isHeaterEnabled"}

@config: {setter_name: "setHeaterEnabled"}

@config: {qml_name: "ClimateControl"}

@config: {qml_type: "ClimateControl"}

@designer: {categoryName: "QtInterfaceFramework - Vehicle Functions"}

@designer: {name: "Climate Control"}

@designer: {typeIcon: "images/climate.png"}

@designer: {libraryIcon: "images/climate.png"}

Annotations that are not logically part of the interface description, but rather the ones used to specify additional information, are put in the accompanying YAML file. Here is a list of annotations used to define the various aspects of generating a backend-simulator:

config_simulator:
    simulationFile: ":/qrc/simulation.qml"

config_simulator:
    zones: [ FrontLeft,
             FrontRight,
             Rear ]

config_simulator:
default:
    AirflowDirection.Floor |
    AirflowDirection.Dashboard

config_simulator:
default: {
    FrontLeft: 21.0,
    FrontRight: 22.5, =: 0.0
}

config_simulator:
minimum: 10

config_simulator:
maximum: 10

config_simulator:
range: [10, 20]

config_simulator:
domain: {10, 20, 30}

Structure for Generated Projects

In the generator output directory, first, a new subfolder is created and named after the module ID. All the generated files are placed in this folder. The tables below describe the files that are generated for the frontend and backend.

Frontend

Generates a QML-friendly C++ API based on the Dynamic Backend System.

QML Plugin

Generates a C++ QML Plugin which registers all types from the frontend in QML.

Backend Simulator

Provides a simulator backend using the QIfSimulationEngine to implement the simulation behavior in QML files.

QtRemoteObjects Backend

The backend_qtro template is only available if qmake finds the QtRemoteObjects module. This remote object backend is a client for connecting to the remote backend server; not the location to implement the actual backend logic.

QtRemoteObjects Server

The server_qtro template is only available if qmake finds the QtRemoteObjects module. The code produced only contains the source classes to inherit and the code for establishing the connection. The developer must implement the actual backend logic.

QtRemoteObjects Simulation Server

The server_qtro_simulator template is only available if qmake finds the QtRemoteObjects module. The code produced contains a fully-implemented server that uses the same implementation as the backend_simulator template, which uses the QIfSimulationEngine to implement the simulation behavior in QML.