使用生成器

本主题描述了如何使用 QtIF 生成器。

简介

生成器是一个 Python 脚本，可以手动运行或使用 构建系统集成。此脚本使用 QFace 作为自动生成框架，解析接口定义语言 (IDL) 文件，生成域模型（类似于抽象语法树 (AST)）并将其提供给生成器。根据要生成的项目类型，指定了不同的 格式。

命令行参数

要运行生成，请使用以下命令

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

选项和参数如下

目前，根据–template值，生成器可以使用给定的IDL文件生成多种类型的项目

配置生成器

生成器的Python脚本解析输入文件并创建领域模型。然后将此领域模型作为上下文传递给Jinja模板引擎。使用生成YAML文件指定要生成的文件。之后，可以使用注释YAML文件向IDL文件添加更多生成器特有的信息。

生成器YAML

创建领域模型树后，遍历此树，并将领域模型对象树的每个叶（模块、接口、结构等）传递给配置文件定义的特定Jinja模板。

生成器YAML文件定义了用来生成哪些文件的模板。假设你想要为你的领域模型中的每个模块生成一个头文件。但，一个模块可以有多个接口，因此你想为每个接口和结构使用不同的头文件。在这种情况下，生成器YAML文件定义了一组规则来指定使用哪个模板文件以及如何命名它们。

此YAML文件必须具有以下结构

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

对于每个实体，在遍历领域模型树中的该实体时，都需要调用一系列模板。在这里，YAML文件定义了一个文档列表，该列表需要为所有模块和所有接口生成。每个列表条目包含两部分；第一部分是需要创建的文件名称，按照Jinja模板语言的格式指定。模板名称中使用的对象属性值将被处理并替换到模板中，从而形成创建文件的最终名称。第二部分是使用模板的名称。对于接口框架生成器，您必须为三种类型的实体指定规则：模块、接口和结构。请参阅QFace规则基生成文档获取更多信息。

额外的Jinja过滤器

有时由ifcodegen提供的Jinja过滤器不足以满足需要，但您可以编写自己的过滤器使用Python。如果您在模板中添加一个名为filters.py的Python脚本，它将被自动加载。您可以使用以下模板代码

# Copyright (C) 2021 The Qt Company Ltd.
# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GPL-3.0-only WITH Qt-GPL-exception-1.0

import json
import inspect

from qface.idl.domain import Module, Interface, Property, Parameter, Field, Struct
from qface.helper.generic import lower_first, upper_first
from qface.helper.qtcpp import Filters

from generator.global_functions import jinja_error, jinja_warning
from generator.filters import deprecated_filter

def custom_filter(s):
    jinja_warning("Test calling a function from the ifcodegen within our own filters")
    return

filters['custom_filter'] = custom_filter

为了在模板之间共享过滤器，还可以指定其他应加载的Python脚本。这需要在生成YAML文件中完成。

以下示例生成了插件.h并从名为extra-filter的文件夹中加载了额外的过滤器

frontend:
    extra_filters: [ "extra-filter/filters.py" ]
    module:
        documents:
            - "{{module.module_name|lower}}plugin.h": "plugin.h.tpl"

注释YAML

目前，使用IDL本身无法表达接口描述的所有方面。例如，没有语言构造来定义属性的默认值或属性可以接受的值范围。然而，这可以通过称为注释的机制来实现。注释提供了自由和灵活性，可以表达任何概念和构造。

下面的一段代码展示了在IDL中使用注释的示例。这里，我们定义一个有区域界定（zoned）的接口，并指定其ID。

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

将所有注释放置在主IDL文件中并不合理。例如，您可能需要定义一些自动测试代码生成的方面。这些注释可以放入与主IDL文件同名的YAML文件中。在解析阶段，QFace会自动拾取此文件，并将YAML文件中指定的注释与在IDL文件中定义的注释合并。

由于伴随的YAML文件总是自动拾取，因此它不适用于需要用于某些特定项目的注释，例如生成后端插件时的注释。对于此用例，您可以将多个额外的注释YAML文件传递给生成器。

在QtInterfaceFramework中，以下注释用于定义IDL

@config: {namespace: "module"}

@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: "Smart Home Components"}

@designer: {name: "Climate Control"}

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

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

@config: { configurationId: "smarthome"}

注释不属于接口描述的逻辑部分，而是用于指定其他信息的注释，放入附带的YAML文件中。

以下是定义生成的后端和服务器的各种方面的注释列表

backend_simulator

config_simulator:
    serviceObjectId: "smarthome_simulation"

config_simulator:
    configurationId: "smarthome"

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

config_simulator:
    defaultApplicationMode: "gui"

config_simulator:
    zones: [ Left,
             Right
           ]

config_simulator:
default:
    MyFlag.Value1 |
    MyFlag.Value2

config_simulator:
default: {
    Left: 21.0,
    Right: 22.5,
    =: 0.0
}

config_simulator:
minimum: 10

config_simulator:
maximum: 10

config_simulator:
range: [10, 20]

config_simulator:
domain: {10, 20, 30}

config_simulator:
unsupported: yes

backend_qtro

config_qtro:
    serviceObjectId: "smarthome_qtro"

config_qtro:
    configurationId: "smarthome"

config_server_qtro

config_server_qtro:
    useGeneratedMain: true

生成的项目结构

在生成输出目录中，首先创建一个新的子目录，并以模块ID命名。所有生成的文件都放在这个文件夹中。下表描述了为前端和后端生成的文件。

前端

基于动态后端系统生成一个适合QML的C++ API。

QML插件

生成一个C++ QML插件，它会在QML中注册前端的所有类型。

后端仿真

提供一个使用QIfSimulationEngine实现的仿真器后端，以在QML文件中实现仿真行为。

QtRemoteObjects 后端

QtRemoteObjects 模块在构建qtinterfaceframework仓库时检测到，此后端_qtro模板才可用。此后端是连接到远程后端服务器的客户端；不是实现实际后端逻辑的位置。

QtRemoteObjects 服务器

当构建qtinterfaceframework仓库时检测到QtRemoteObjects模块，此server_qtro模板才可用。生成的代码仅包含继承的源类代码以及建立连接的代码。开发者必须实现实际的后端逻辑。

QtRemoteObjects 模拟服务器

当构建qtinterfaceframework仓库时检测到QtRemoteObjects模块，此server_qtro模板才可用。生成的代码包含一个完全实施的服务器，该服务器可能与backend_simulator模板使用相同的实现，该实现使用QIfSimulationEngine在QML中实现模拟行为。

默认情况下，在生成的服务器中使用QCoreApplication，使服务器可以作为无头服务器运行。为了允许在模拟QML代码中实例化UI控制，服务器可以以GUI模式（–gui选项）启动。可以通过config_simulator_defaultServerMode批注更改默认模式。

后端特定配置选项

一些生成的后端可以使用QIfConfiguration类提供的服务设置。以下表格描述了每个模板可用的设置

后端模拟器

生成的代码没有进行任何服务设置，但它将serviceSettings传递给QML模拟。手写的QML模拟可以使用BackendInterface对象的serviceSettings属性来改变设置设置时的行为。

QtRemoteObjects后端

除了这些全局设置之外，还可以针对后端接口提供值，这允许后端连接到多个远程对象实例。特定于接口的设置需要以前端名称作为前缀。以下示例创建一个配置，它应用于 cluster 群组中的所有Items。应用于当前连接后端的服务设置使用全局的 connectionTimeout 和集群模块中InstrumentCluster接口的特定 connectionUrl，而其他所有接口使用默认的 connectionUrl

    InterfaceFrameworkConfiguration {
        name: "cluster"
        serviceSettings: {
            "connectionTimeout": 1000,
            "cluster.InstrumentCluster": {
                "connectionUrl": "tcp://127.0.0.1:1234"
            }
        }
    }

    Instead of providing settings per interface, it is also possible to provide the settings on a
    per module basis using the module name as a key.