QML Static Analysis 1 - Configuration de base

Ce chapitre présente la structure de base d'un plugin d'extension qmllint, et comment il peut être utilisé avec qmllint.

Pour créer notre plugin, nous devons d'abord rendre le module QmlCompiler disponible :

find_package(Qt6 REQUIRED COMPONENTS QmlCompiler)

Nous créons ensuite un plugin et le lions au module QmlCompiler.

qt_add_plugin(HelloWorldPlugin)

target_sources(HelloWorldPlugin
    PRIVATE
        helloplugin.h
        helloplugin.cpp
)

target_link_libraries(HelloWorldPlugin PRIVATE Qt::QmlCompiler)

L'implémentation suit le modèle d'extension de Qt avec un plugin: Nous sous-classons le module 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;
};

Le plugin fait référence à un fichier plugin.json, qui contient des informations importantes :

{
    "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, et sont des méta-données qui décrivent le plugin. version description

Chaque plugin peut avoir une ou plusieurs catégories de journalisation, qui sont utilisées pour regrouper thématiquement les avertissements. loggingCategories prend un tableau de catégories, chacune étant composée de

• namequi est utilisé pour identifier la catégorie, et comme nom de drapeau dans qmllint,
• settingsNamequi est utilisé pour configurer la catégorie dans qmllint.ini
• descriptionqui doit décrire le type de messages d'avertissement qui sont étiquetés avec la catégorie

Dans notre exemple, nous n'avons qu'une seule catégorie de journalisation, hello-world. Pour chaque catégorie, nous devons créer un objet LoggerWarningId dans notre plugin.

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

Nous le construisons avec une chaîne littérale qui doit avoir le format Plugin.<plugin name>.<category name>.

Enfin, pour que notre plugin puisse faire quelque chose d'utile, nous devons implémenter la fonction 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; // ignore l'enregistrement si le plugin est de toute façon désactivé // ici nous enregistrerons plus tard nos passes}

Nous vérifions si notre catégorie est activée et nous imprimons un diagnostic indiquant son état via qDebug. Notez que le plugin ne fait actuellement rien d'utile, car nous n'enregistrons aucun laissez-passer. Cela sera fait dans la prochaine partie de ce tutoriel.

Nous pouvons cependant déjà vérifier que notre plugin est correctement détecté. Nous utilisons la commande suivante pour le vérifier :

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

L'option -P indique à qmllint de rechercher les plugins dans le dossier spécifié. Pour éviter les conflits avec les catégories internes de Qt, les catégories de plugins sont toujours préfixées par "Plugin", suivi d'un point, du nom du plugin, d'un autre point et enfin de la catégorie. L'exécution de la commande devrait permettre d'imprimer Hello World Plugin is enabled.