This page is about the usage of the QtIVI auto-generator.

Introduction

The Generator is a Python script that can be run manually or using the QMake Integration. This script uses QFace as the autogenerator framework which parses the IDL file, generates the domain-model (similar to AST) and then feeds it to the actual generator. Depending on the type of the generated project, different formats are specified.

Command line parameters

The generation is run using the following command:

$$[QT_HOST_BINS]/ivigenerator/generate.py --format=backend_simulator interface.qface out_dir

The options and parameters are:

At the moment the generator is able to generate 5 kinds of projects given an interface IDL file based on the --format option value. These are:

YAML configuration

The Python script is responsible for parsing the input files and for the creation of a domain model. This domain model is passed as a context to the Jinja template engine. To control which files are generated, the "Generation YAML" can be used. In addition, an "Annotations YAML" can be used to add more information to the IDL file, which are generator specific.

Generation YAML

After the domain model tree has been created, this tree is traversed and each leaf of the domain model object tree (module, interface, structure, etc) is passed to a specific Jinja template defined by the configuration file. This file must be in YAML format and for every particular generation format its name is defined in the script. This file must have the following structure:

generate_rules:
    module_rules:
        -   dest_file:  "{{module.module_name|lower}}plugin.h"
          template_file:  "plugin.h.tpl"
    interface_rules:
        -   dest_file: '{{interface|lower}}backend.h'
          template_file: 'backend.h.tpl'
    struct_rules:

For every entity there is a list of templates needed to be called when traversing this entity in the domain model tree. Here, dest_file is a name of the file need to be created specified in the Jinja template language format: the value of the object property used in the name template will be processed and substituted into the template, thus forming the final name of the file to create. dest_file is a name of the template to be used. For the IVI generator, rules for three kinds of entities need to be specified: modules, interfaces and structures.

Annotations YAML

At the moment not all aspects of the interface description cannot be expressed using the IDL itself. For instance there is no language construct to define default value for the property or values the property can take on. Still this can be achieved via a mechanism called Annotations. Annotations allow great freedom and flexibility of expressing any concepts and constructs.

Below is an example of using annotations in the IDL. Here it's defined that interface is zoned and its identifier is specified.

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

Not all of the annotations make sense to be put in the main IDL file either. For instance, one may need to define some aspects of generation of the auto-testing code. Such annotations can be put in the YAML file accompanying the main IDL file and named after it. During the parse phase QFace picks this file up automatically and merges annotation specified in this YAML file with those defined in the IDL file.

As the accompanying YAML file is automatically picked up in all cases, this doesn't work for annoations which are only needed for some specific projects e.g. when generating a backend plugin. For this use case you can pass multiple additional annotation YAML files to the generator.

For QtIvi there are following annotations used for the IDL definition:

The annotations that are not logically part of the interface description but rather the ones used for specifying additional information are put in the accompanying YAML file. Here is the list of annotations used for defining various aspects of the generation of the 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}

Generated projects structure

In the generator output directory first a new subfolder with the name of the module id will be created. All the generated files will be put in this folder. The following files will be generated:

Frontend

Backend simulator

Control Panel

The control_panel template is only available if the QtSimulator module was found. Please see the Configuration Page for more information.

Note: Currently the control_panel template doesn't support all qface features. At the moment models and structs are NOT supported.

QtRemoteObjects Backend

The backend_qtro template is only available if the QtRemoteObjects module was found. Despite the name, the remote object backend is not the location for the implementation of the actual backend logic, but just a client for connecting to the remote backend server.

QtRemoteObjects server

The server_qtro template is only available if the QtRemoteObjects module was found. The produced code contains merely the source classes to inherit and code for establishing the connection. It is up to the developer to implement the actual backend logic.