Analyse statique QML 1 - Configuration de base

Ce chapitre présente la structure de base d'un plugin d'extension qmllint et explique comment l'utiliser 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 XML à l'aide d'un plugin: nous créons une sous-classe de ` 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, version et description sont des métadonnées permettant de décrire le plugin.

Chaque plugin peut disposer d’une ou plusieurs catégories de journalisation, qui servent à regrouper les avertissements par thème. loggingCategories prend en paramètre un tableau de catégories, chacune composée de

• name, qui sert à identifier la catégorie, et comme nom de drapeau dans qmllint,
• settingsName, qui sert à configurer la catégorie dans qmllint.ini
• description, qui doit décrire le type de messages d'avertissement associés à cette 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 à l'aide d'une chaîne littérale qui doit respecter le format Plugin.<plugin name>.<category name>.

Enfin, pour que notre plugin fasse réellement 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; // ignorer l'enregistrement si le plugin est de toute façon désactivé
    // c'est ici que nous enregistrerons nos passes ultérieurement
}

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

Nous pouvons toutefois 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 tout conflit 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 afficher « Hello World Plugin is enabled ».