QML-Statikanalyse 1 – Grundlegende Einrichtung

In diesem Kapitel werden die grundlegende Struktur eines qmllint-Erweiterungs-Plugins sowie dessen Verwendung mit qmllint vorgestellt.

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

find_package(Qt6 REQUIRED COMPONENTS QmlCompiler)

Anschließend 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 zur Erweiterung von Qt durch ein Plugin: Wir erstellen eine Unterklasse von „ 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 verweist auf 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 zur Beschreibung des Plugins.

Jedes Plugin kann eine oder mehrere Protokollierungskategorien haben, die dazu dienen, Warnungen thematisch zu gruppieren. ` loggingCategories ` erwartet ein Array von Kategorien, die jeweils aus

• name, das zur Identifizierung der Kategorie dient, sowie als Flag-Name in qmllint,
• settingsName, das zur Konfiguration der Kategorie in der Datei „qmllint.ini“ dient
• description, das beschreiben sollte, 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 in unserem Plugin ein „ LoggerWarningId “-Objekt anlegen.

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

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

Damit unser Plugin schließlich tatsächlich etwas Sinnvolles bewirkt, 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; // Registrierung überspringen, 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 über ` qDebug` eine Meldung aus, die den Status anzeigt. Beachten Sie, dass das Plugin derzeit noch keine nützlichen Funktionen ausführt, da wir noch keine Pässe registrieren. Dies wird im nächsten Teil dieses Tutorials behandelt.

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

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

Die Option „ -P “ weist qmllint an, im angegebenen Ordner nach Plugins zu suchen. Um Konflikte mit Qt-internen Kategorien zu vermeiden, erhalten Plugin-Kategorien immer das Präfix „Plugin“, gefolgt von einem Punkt, dem Plugin-Namen, einem weiteren Punkt und schließlich der Kategorie. Bei Ausführung des Befehls sollte „ Hello World Plugin is enabled “ ausgegeben werden.