QML Statische Analyse 1 - Grundlegende Einrichtung

In diesem Kapitel wird die grundlegende Struktur eines qmllint-Erweiterungs-Plugins vorgestellt und wie es mit qmllint verwendet werden kann.

Um unser Plugin zu erstellen, müssen wir zunächst das Modul QmlCompiler verfügbar machen:

find_package(Qt6 REQUIRED COMPONENTS QmlCompiler)

Dann erstellen wir ein Plugin und verknüpfen es mit dem QmlCompiler-Modul.

qt_add_plugin(HelloWorldPlugin)

target_sources(HelloWorldPlugin
    PRIVATE
        helloplugin.h
        helloplugin.cpp
)

target_link_libraries(HelloWorldPlugin PRIVATE Qt::QmlCompiler)

Die Implementierung folgt dem Muster für die Erweiterung von Qt mit einem Plugin: Wir subclassifizieren die 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;
};

Das Plugin referenziert eine plugin.json Datei, die einige wichtige Informationen enthält:

{
    "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 und description sind Metadaten, die das Plugin beschreiben.

Jedes Plugin kann eine oder mehrere Protokollierungskategorien haben, die verwendet werden, um Warnungen thematisch zu gruppieren. loggingCategories nimmt ein Array von Kategorien, die jeweils bestehen aus

• namedie zur Identifizierung der Kategorie und als Flag-Name in qmllint verwendet wird,
• settingsName, die zur Konfiguration der Kategorie in qmllint.ini verwendet wird
• descriptiondie beschreiben soll, welche Art von Warnmeldungen mit der Kategorie gekennzeichnet werden

In unserem Beispiel haben wir nur eine Protokollierungskategorie, hello-world. Für jede Kategorie müssen wir ein LoggerWarningId Objekt in unserem Plugin erstellen.

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

Wir konstruieren es mit einem String-Literal, das das Format Plugin.<plugin name>.<category name> haben sollte.

Damit unser Plugin überhaupt etwas Nützliches tun kann, müssen wir die Funktion registerPasses implementieren.

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; // Überspringen Sie die Registrierung, wenn das Plugin ohnehin deaktiviert ist // hier werden wir später unsere Pässe registrieren}

Wir prüfen, ob unsere Kategorie aktiviert ist, und geben eine Diagnose aus, die ihren Status über qDebug anzeigt. Beachten Sie, dass das Plugin derzeit nichts Nützliches tut, da wir keine Pässe registrieren. Dies wird im nächsten Teil des Tutorials nachgeholt.

Wir können jedoch bereits überprüfen, ob unser Plugin korrekt erkannt wird. Wir verwenden den folgenden Befehl, um dies zu überprüfen:

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

Mit den Optionen -P wird qmllint angewiesen, im angegebenen Ordner nach Plugins zu suchen. Um Konflikte mit Qt-internen Kategorien zu vermeiden, werden Plugin-Kategorien immer mit "Plugin" vorangestellt, gefolgt von einem Punkt, dem Plugin-Namen, einem weiteren Punkt und schließlich der Kategorie. Die Ausführung des Befehls sollte Hello World Plugin is enabled ausgeben.