Análisis estático QML 1 - Configuración básica

Este capítulo presenta la estructura básica de un plugin de extensión qmllint, y cómo se puede utilizar con qmllint.

Para crear nuestro plugin, primero necesitamos que el módulo QmlCompiler esté disponible:

find_package(Qt6 REQUIRED COMPONENTS QmlCompiler)

Luego creamos un plugin, y lo enlazamos contra el módulo QmlCompiler.

qt_add_plugin(HelloWorldPlugin)

target_sources(HelloWorldPlugin
    PRIVATE
        helloplugin.h
        helloplugin.cpp
)

target_link_libraries(HelloWorldPlugin PRIVATE Qt::QmlCompiler)

La implementación sigue el patrón para extender Qt con un plugin: Subclasificamos QQmlSA::LintPlugin,

class HelloWorldPlugin : public QObject, public QQmlSA::LintPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID QmlLintPluginInterface_iid FILE "plugin.json")
    Q_INTERFACES(QQmlSA::LintPlugin)

public:
    void registerPasses(QQmlSA::PassManager *manager, const QQmlSA::Element &rootElement) override;
};

El plugin hace referencia a un archivo plugin.json, que contiene información importante:

{
    "name": "HelloWorld",
    "author": "Qt Example",
    "description": "Demonstrates how to write a qmllint plugin",
    "version": "1.0",
    "loggingCategories": [
        {
            "name": "hello-world",
            "settingsName": "HelloWorld",
            "description": "Used to create test messages"
        }
    ]
}

name, author, version y description son metadatos que describen el plugin.

Cada complemento puede tener una o más categorías de registro, que se utilizan para agrupar temáticamente las advertencias. loggingCategories toma una matriz de categorías, cada una de las cuales consiste en

• nameque se utiliza para identificar la categoría, y como el nombre de la bandera en qmllint,
• settingsName, que se utiliza para configurar la categoría en qmllint.ini
• description, que debe describir qué tipo de mensajes de advertencia se etiquetan con la categoría

En nuestro ejemplo, sólo tenemos una categoría de registro, hello-world. Para cada categoría, tenemos que crear un objeto LoggerWarningId en nuestro plugin.

static constexpr QQmlSA::LoggerWarningId helloWorld { "Plugin.HelloWorld.hello-world" };

Lo construimos con una cadena literal que debe tener el formato Plugin.<plugin name>.<category name>.

Por último, para que nuestro plugin haga algo realmente útil, tenemos que implementar la función registerPasses.

void HelloWorldPlugin::registerPasses(QQmlSA::PassManager *manager, const QQmlSA::Element &rootElement) { const bool pluginIsEnabled =  manager->isCategoryEnabled(helloWorld);    qDebug() << "Hello World plugin is" << (pluginIsEnabled ? "enabled" : "disabled");
   if (!pluginIsEnabled) return; // omitimos el registro si el plugin está deshabilitado de todos modos // aquí registraremos más tarde nuestros pases}

Comprobamos si nuestra categoría está habilitada, e imprimimos un diagnóstico indicando su estado a través de qDebug. Nótese que actualmente el plugin no hace nada útil, ya que no registramos ningún pase. Esto se hará en la siguiente parte de este tutorial.

Sin embargo, ya podemos verificar que nuestro plugin se detecta correctamente. Usamos el siguiente comando para comprobarlo:

qmllint -P /path/to/the/directory/containing/the/plugin --Plugin.HelloWorld.hello-world info test.qml

Las opciones de -P indican a qmllint que busque plugins en la carpeta especificada. Para evitar conflictos con las categorías internas de Qt, las categorías de plugins siempre van precedidas de "Plugin", seguido de un punto, el nombre del plugin, otro punto y finalmente la categoría. Ejecutando el comando debería imprimir Hello World Plugin is enabled.