qmllint

qmllint est un outil fourni avec Qt qui vérifie la validité syntaxique des fichiers QML. Vous pouvez intégrer qmllint à votre système de compilation pour plus de facilité d'utilisation. Il signale également certains anti-modèles QML. Consultez la section Configuration des avertissements de qmllint pour savoir comment désactiver un type d'avertissement spécifique.

Par défaut, certains problèmes génèrent des avertissements qui s’affichent. S’il y a plus d’avertissements qu’une limite pouvant être configurée avec --max-warnings, le code de sortie sera différent de zéro. Les problèmes mineurs (tels que les importations inutilisées) ne sont toutefois, par défaut, que des messages d’information et n’affecteront jamais le code de sortie. qmllint est très configurable et permet de désactiver les avertissements ou de modifier la manière dont ils sont traités.

qmllint signale :

• Les accès non qualifiés aux propriétés
• L’utilisation de gestionnaires de signaux sans signal correspondant
• L'utilisation d'instructions `with` en QML
• Problèmes liés à la compilation du code QML
• Importations inutilisées
• Composants et propriétés obsolètes
• Et bien d'autres choses encore

Consultez la section « Avertissements et erreurs de QML Lint » pour savoir comment corriger les avertissements et les erreurs signalés par qmllint.

Pour obtenir un aperçu et une explication de toutes les options de ligne de commande disponibles, exécutez ` qmllint --help`.

Avertissements du compilateur

qmllint peut vous signaler le code qui ne peut pas être compilé par qmlsc.

Ces avertissements ne sont pas activés par défaut. Pour les activer, configurez qmllint afin qu’il utilise la catégorie d’avertissements du compilateur.

Utilisation de qmllint avec CMake

Pour les projets utilisant l’API CMake ` qt_add_qml_module()` pour créer des modules QML, des cibles pratiques telles que ` all_qmllint ` sont créées automatiquement. Celles-ci exécutent qmllint sur tous les fichiers QML d’un module spécifique ou du projet.

Application automatique des suggestions de correction

La résolution des avertissements émis par qmllint peut nécessiter un travail manuel considérable de modification et de validation. Certains avertissements émis par qmllint s’accompagnent d’une suggestion de correction associée qui peut être déclenchée pour résoudre automatiquement l’avertissement. Pour déclencher ces corrections, vous pouvez :

• Passer « --fix » à qmllint.
• Activer les corrections depuis votre IDE.

Appliquer toutes les corrections à l’ensemble de votre projet en une seule fois peut représenter un changement trop important. Il est donc recommandé de diviser le travail en parties plus faciles à gérer. Vous pouvez fractionner le travail en ne vérifiant qu’un sous-ensemble de fichiers, ou en n’exécutant que certaines catégories.

qmllint --only-explicit-categories --ignore-settings --fix --unqualified=warning <files>

Cela permettra d’appliquer les corrections disponibles uniquement aux accès non qualifiés, en désactivant toutes les autres catégories d’avertissements à l’aide de ` --only-explicit-categories ` et ` --ignore-settings`.

Si vous avez des doutes concernant une modification, utilisez --dry-run pour prévisualiser en toute sécurité le résultat d’une analyse sans modifier réellement les fichiers.

Marquage des composants et des propriétés comme obsolètes

qmllint vous permet de marquer à la fois les propriétés et les composants comme obsolètes :

@Deprecated { reason: "Use NewCustomText instead" }
Text {
    @Deprecated { reason: "Use newProperty instead" }
    property int oldProperty
    property int newProperty
    Component.onCompleted: console.log(oldProperty);  // Warning: XY.qml:8:40: Property "oldProperty" is deprecated (Reason: Use newProperty instead)
}

Des avertissements de dépréciation pour les composants s'afficheront à chaque fois que le composant est créé.

Désactivation des avertissements en ligne

Vous pouvez à tout moment désactiver temporairement les avertissements dans un fichier à l'aide de ` // qmllint disable`.

Vous pouvez le faire à la fin d’une ligne lorsqu’une seule ligne génère des avertissements :

Item {
    property string foo
    Item {
        property string bar: foo // qmllint disable unqualified
    }
}

Vous pouvez également désactiver les avertissements pour un bloc de lignes en plaçant le commentaire dans une ligne ne contenant que « // qmllint disable », et en terminant le bloc par « // qmllint enable » :

Item {
    property string foo
    Item {
        // qmllint disable unqualified
        property string bar: foo
        property string bar2: foo
        // qmllint enable unqualified
    }
}

qmllint interprète tous les commentaires d’une seule ligne commençant par qmllint comme des directives. Vous ne devez donc pas commencer un commentaire de cette manière, sauf si vous souhaitez activer ou désactiver des avertissements.

Configuration des avertissements de qmllint

Vous pouvez configurer les avertissements émis par qmllint ainsi que leur niveau de gravité. Ces niveaux peuvent être info, {warning}, error ou disable. Vous pouvez personnaliser les avertissements à l’aide du fichier de paramètres .qmllint.ini ou en passant des options de ligne de commande à qmllint. Les options de ligne de commande prévalent sur les valeurs par défaut et sur le fichier de paramètres.

Pour personnaliser le niveau d’une catégorie d’avertissement via la ligne de commande, définissez l’option de ligne de commande correspondante sur le niveau souhaité.

Par exemple, pour désactiver les avertissements concernant les éléments obsolètes, appelez qmllint avec l’option --deprecated=disable. Et pour transformer les importations inutilisées en erreur, passez l’option --unused-imports=error.

Pour personnaliser les avertissements de manière plus permanente, vous pouvez modifier le fichier de configuration. Reportez-vous à la section suivante sur les fichiers de configuration ( Settings ) pour plus de détails.

Configuration

Outre les options de ligne de commande, vous pouvez également configurer qmllint via un fichier de paramètres. L’ --write-defaults de ligne de commande vous en générera un.

Les fichiers de configuration sont nommés « .qmllint.ini » et se présentent comme suit :

[General]
DisableDefaultImports=false
MaxWarnings=-1

[Warnings]
AccessSingletonViaObject=warning
AliasCycle=warning
AssignmentInCondition=warning
AttachedPropertyReuse=disable
BadSignalHandlerParameters=warning
Comma=warning
CompilerWarnings=disable
ComponentChildrenCount=warning
ConfusingExpressionStatement=warning
ConfusingMinuses=warning
ConfusingPluses=warning
ContextProperties=warning
Deprecated=warning
DuplicateEnumEntries=warning
DuplicateImport=warning
DuplicateInlineComponent=warning
DuplicatePropertyBinding=warning
DuplicatedName=warning
EnumEntryMatchesEnum=warning
EnumsAreNotTypes=warning
EqualityTypeCoercion=warning
Eval=warning
FunctionUsedBeforeDeclaration=disable
ImportFailure=warning
IncompatibleType=warning
InheritanceCycle=warning
InvalidLintDirective=warning
LintPluginWarnings=disable
LiteralConstructor=warning
MissingEnumEntry=warning
MissingProperty=warning
MissingType=warning
MultilineStrings=info
NonListProperty=warning
NonRootEnum=warning
PreferNonVarProperties=warning
PrefixedImportType=warning
PropertyAliasCycles=warning
QtDesignStudio.FunctionsNotSupportedInQmlUi=warning
QtDesignStudio.ImperativeCodeNotEditableInVisualDesigner=warning
QtDesignStudio.InvalidIdeInVisualDesigner=warning
QtDesignStudio.ReferenceToParentItemNotSupportedByVisualDesigner=warning
QtDesignStudio.UnsupportedRootTypeInQmlUi=warning
QtDesignStudio.UnsupportedTypeInQmlUi=warning
Quick.Anchors=warning
Quick.AttachedPropertyReuse=disable
Quick.AttachedPropertyType=warning
Quick.Color=warning
Quick.ControlsAttachedPropertyReuse=disable
Quick.ControlsNativeCustomize=warning
Quick.LayoutsPositioning=warning
Quick.PropertyChangesParsed=warning
Quick.StateNoChildItem=warning
Quick.UnexpectedVarType=warning
ReadOnlyProperty=warning
RedundantOptionalChaining=warning
RequiredProperty=warning
RestrictedType=warning
StalePropertyRead=warning
TopLevelComponent=warning
TranslationFunctionMismatch=warning
UncreatableType=warning
UnintentionalEmptyBlock=warning
UnqualifiedAccess=warning
UnreachableCode=warning
UnresolvedAlias=warning
UnresolvedType=warning
UnterminatedCase=warning
UnusedImports=info
UseProperFunction=warning
VarUsedBeforeDeclaration=warning
Void=disable
WithStatement=warning

Les niveaux d’avertissement peuvent être définis sur « info », « warning », « error » ou « disable », tout comme avec les options de ligne de commande.

qmllint recherchera automatiquement un fichier de paramètres à l’emplacement du fichier QML en cours d’analyse. Il parcourt également tous les répertoires parents pour trouver ce fichier et applique automatiquement les paramètres qu’il contient. Vous pouvez désactiver ce comportement en utilisant ` --ignore-settings`. Vous pouvez toujours remplacer ces valeurs par défaut en spécifiant des paramètres de ligne de commande qui ont priorité sur les niveaux d’avertissement définis dans les paramètres.

Paramètres des propriétés de contexte

Les propriétés de contexte peuvent être définies ou ignorées par leur nom dans leur propre fichier de paramètres. Les paramètres des propriétés de contexte permettent une approche plus fine pour désactiver les avertissements d’accès non qualifié liés à l’utilisation des propriétés de contexte, tandis que ` .qmllint.ini ` permet uniquement de désactiver tous les avertissements d’accès non qualifié, y compris potentiellement ceux qui ne sont pas liés aux propriétés de contexte.

Les paramètres des propriétés de contexte sont nommés .contextProperties.ini et doivent se trouver dans le dossier source de votre projet. Ils se présentent comme suit :

[General]
disableUnqualifiedAccess = "myContextProperty1,myContextProperty2"
warnOnUsage = "myContextProperty3,myContextProperty4,myContextProperty5"
disableHeuristic = false

Pour désactiver les avertissements de qmllint concernant l’accès non qualifié à un nom de propriété de contexte, ajoutez le nom de la propriété de contexte à ` disableUnqualifiedAccess`. Séparez les noms de propriétés de contexte multiples par une virgule.

Pour générer un avertissement concernant les utilisations de propriétés de contexte, ajoutez le nom de la propriété de contexte à ` warnOnUsage`. Séparez les noms de propriétés de contexte multiples par une virgule.

Pour contrôler l’heuristique de qmllint, définissez ` disableHeuristic ` sur ` true ` ou ` false`.

Scripts

qmllint peut générer ou afficher du JSON via l’option --json <file>, qui renvoie un JSON valide contenant les messages d’avertissement, l’emplacement des avertissements dans le fichier et sur la ligne, ainsi que leur niveau de gravité. Utilisez le nom de fichier spécial « - » pour écrire sur stdout plutôt que dans un fichier. Cela permet d’intégrer plus facilement qmllint dans vos hooks de pré-commit ou vos tests d’intégration continue (CI).