qt_add_qml_module

Définit un module QML.

Cette commande a été introduite dans Qt 6.2.

La commande est définie dans le composant « Qml » du paquet « Qt6 », qui peut être chargé comme suit :

find_package(Qt6 REQUIRED COMPONENTS Qml)

Syntaxe

qt_add_qml_module(
    target
    URI uri
    [VERSION version]
    [PAST_MAJOR_VERSIONS ...]
    [STATIC | SHARED]
    [PLUGIN_TARGET plugin_target]
    [OUTPUT_DIRECTORY output_dir]
    [RESOURCE_PREFIX resource_prefix]
    [CLASS_NAME class_name]
    [TYPEINFO typeinfo]
    [IMPORTS ...]
    [OPTIONAL_IMPORTS ...]
    [DEFAULT_IMPORTS ...]
    [DEPENDENCIES ...]
    [IMPORT_PATH ...]
    [SOURCES ...]
    [QML_FILES ...]
    [RESOURCES ...]
    [OUTPUT_TARGETS out_targets_var]
    [DESIGNER_SUPPORTED]
    [FOLLOW_FOREIGN_VERSIONING]
    [NAMESPACE namespace]
    [NO_PLUGIN]
    [NO_PLUGIN_OPTIONAL]
    [NO_CREATE_PLUGIN_TARGET]
    [NO_GENERATE_PLUGIN_SOURCE]
    [NO_GENERATE_QMLTYPES]
    [NO_GENERATE_QMLDIR]
    [NO_GENERATE_EXTRA_QMLDIRS]
    [NO_GENERATE_QTCONF]                          # since Qt 6.12
    [NO_GENERATE_AOT_VALIDATION]                  # since Qt 6.12
    [NO_LINT]
    [NO_CACHEGEN]
    [NO_RESOURCE_TARGET_PATH]
    [NO_IMPORT_SCAN]
    [DISCARD_QML_CONTENTS]
    [ENABLE_TYPE_COMPILER]
    [TYPE_COMPILER_NAMESPACE namespace]
    [QMLTC_EXPORT_DIRECTIVE export_macro]
    [QMLTC_EXPORT_FILE_NAME header_defining_export_macro]

)

Si les commandes sans version sont désactivées, utilisez plutôt qt6_add_qml_module(). Elle prend en charge les mêmes arguments que cette commande.

Consultez les sections Créer une application QML et Créer un module QML réutilisable pour obtenir des exemples de définition de modules QML.

Description

Cette commande définit un module QML pouvant être constitué de sources C++, de fichiers « .qml » ou des deux. Elle garantit que les informations essentielles relatives au module sont fournies et cohérentes. Elle configure et coordonne également des éléments tels que la compilation en cache des sources « .qml », l’intégration des ressources, les vérifications de linting et la génération automatique de certains fichiers clés du module.

Pour un aperçu conceptuel accompagné d’exemples d’utilisation courants, consultez la section « Tout mettre en place avec CMake ». Pour les sujets avancés tels que les structures de répertoires personnalisées et la gestion des versions, consultez la section « Écrire des modules QML ».

Structure de la cible

Un module QML peut être structuré de plusieurs façons différentes. Les scénarios suivants correspondent aux configurations les plus courantes :

Cibles « backing » et « plugin » distinctes

Il s'agit de la configuration recommandée pour la plupart des modules QML. Toutes les fonctionnalités du module sont implémentées dans la cible « backing », qui est spécifiée comme premier argument de commande. Les sources C++, les fichiers d'.qml s et les ressources doivent tous être ajoutés à la cible « backing ». La cible « backing » est une bibliothèque qui doit être installée au même emplacement que toutes les autres bibliothèques définies par le projet.

La structure du répertoire source dans lequel la cible de support est créée doit correspondre au chemin cible du module QML (le chemin cible correspond à l’URI du module, les points étant remplacés par des barres obliques). Si la structure du répertoire source ne correspond pas au chemin cible, l’ qt_add_qml_module() émettra un avertissement.

L’exemple suivant illustre une structure de répertoires source adaptée à un module QML dont l’URI est MyThings.Panels. L’appel à ` qt_add_qml_module() ` se trouverait dans le fichier ` CMakeLists.txt ` présenté.

src
 +-- MyThings
      +-- Panels
           +-- CMakeLists.txt

Une cible « plugin » distincte est associée au module QML. Elle est utilisée lors de l’exécution pour charger le module de manière dynamique lorsque l’application n’est pas déjà liée à la cible sous-jacente. La cible « plugin » est également une bibliothèque et est normalement installée dans le même répertoire que le fichier `qmldir` du module.

Idéalement, la cible du plugin ne devrait contenir rien de plus qu’une implémentation triviale de la classe de plugin. Cela permet de désigner le plugin comme optionnel dans le fichier ` qmldir `. D’autres cibles peuvent alors se lier directement à la cible de base et le plugin ne sera pas nécessaire lors de l’exécution, ce qui peut améliorer les performances au chargement. Par défaut, un fichier source C++ définissant une classe de plugin minimale sera automatiquement généré et ajouté à la cible « plugin ». Dans les cas où le module QML nécessite une implémentation personnalisée de la classe de plugin, les options NO_GENERATE_PLUGIN_SOURCE et, généralement, NO_PLUGIN_OPTIONAL seront nécessaires.

Les modules QML « STATIC » génèrent également des plugins QML statiques si l’option « NO_PLUGIN » n’est pas spécifiée. Les cibles qui importent ces modules QML « STATIC » doivent également se lier explicitement aux plugins QML correspondants.

Cible de plugin sans cible de support

Un module QML peut être défini avec la cible « plugin » servant de cible de support à lui-même. Dans ce cas, le module doit être chargé dynamiquement lors de l’exécution et ne peut pas être lié directement par d’autres cibles. Pour créer cette configuration, il faut utiliser le mot-clé « PLUGIN_TARGET », en répétant « target » comme nom de la cible « plugin ». Par exemple :

qt_add_qml_module(someTarget
    PLUGIN_TARGET someTarget
    ...
)

Bien que cette configuration puisse sembler légèrement plus simple à déployer, il est préférable d’utiliser une cible de support distincte dans la mesure du possible, en raison des performances potentiellement meilleures au niveau du temps de chargement.

Exécutable en tant que module QML

Une cible exécutable peut servir de cible de support pour un module QML. Dans ce cas, il n’y aura pas de bibliothèque de plugin, puisque le module QML sera toujours chargé directement en tant que partie intégrante de l’application. La commande ` qt_add_qml_module() ` détectera lorsqu’un exécutable est utilisé comme cible de support et désactivera automatiquement la création d’un plugin distinct. N’utilisez aucune des options dont le nom contient « PLUGIN » lorsque vous utilisez cette configuration.

Lorsqu’un exécutable est utilisé comme cible de base, la structure du répertoire source ne doit pas nécessairement correspondre au chemin cible du module QML. Consultez la section Mise en cache des sources QML compilées pour connaître les différences supplémentaires de chemin cible concernant les ressources compilées.

Génération automatique des fichiers « qmldir » et « typeinfo »

Par défaut, un fichier `qmldir ` et un fichier `typeinfo` sont générés automatiquement pour le module QML en cours de définition. Le contenu de ces fichiers est déterminé par les différents arguments fournis à cette commande, ainsi que par les fichiers sources et ` .qml ` ajoutés à la cible de base. L’argument OUTPUT_DIRECTORY détermine l’emplacement où les fichiers « qmldir » et « typeinfo » seront enregistrés. Si le module QML dispose d’un plugin, celui-ci sera également créé dans le même répertoire que le fichier « qmldir ».

Si la politique QTP0004 est définie sur « NEW », un fichier « qmldir » supplémentaire est généré pour chaque répertoire contenant des fichiers « .qml ». Ces fichiers « qmldir » supplémentaires se contentent de rediriger vers le répertoire de base du module via une directive « prefer ». Cela permet à tous les composants QML d’un module de se communiquer entre eux, quel que soit le répertoire dans lequel ils sont stockés.

Si vous utilisez une version statique de Qt, les fichiers ` .qml ` de la cible sous-jacente seront analysés lors de l’exécution de la configuration CMake afin de déterminer les importations utilisées par le module et de configurer les relations de liaison (le mot-clé ` NO_IMPORT_SCAN ` peut être utilisé pour désactiver cette fonctionnalité). Lorsqu’un fichier « .qml » est ajouté au module ou supprimé de celui-ci, CMake se relance normalement automatiquement et les fichiers concernés sont à nouveau analysés, puisqu’un fichier « CMakeLists.txt » a été modifié. Au cours du développement, un fichier ` .qml ` existant peut ajouter ou supprimer une importation ou un type. En soi, cela ne provoquerait pas le relancement automatique de CMake ; vous devez donc relancer explicitement CMake pour forcer la régénération du fichier ` qmldir ` et la mise à jour de toutes les relations de liaison.

Les sources C++ de la cible sous-jacente sont analysées au moment de la compilation afin de générer un fichier typeinfo et un fichier C++ permettant d'enregistrer les types associés. Le fichier C++ généré est automatiquement ajouté à la cible sous-jacente en tant que source. Cela nécessite que l'option « AUTOMOC » soit activée sur la cible. Il incombe au projet de s’en assurer, généralement en définissant la variable ` CMAKE_AUTOMOC ` sur ` TRUE ` avant d’appeler ` qt_add_qml_module()`, ou en transmettant une cible existante dont la propriété ` AUTOMOC ` est déjà définie sur ` TRUE`. Le fait que ` AUTOMOC ` soit désactivé sur la cible ne constitue pas une erreur, mais le projet est alors responsable de la gestion des conséquences. Cela peut notamment impliquer de générer manuellement le fichier `typeinfo` au lieu de le laisser s’en générer automatiquement avec des détails manquants, et d’ajouter du code C++ pour enregistrer les types.

Les projets devraient privilégier l’utilisation des fichiers `typeinfo` et ` qmldir ` générés automatiquement dans la mesure du possible. Ils sont plus faciles à maintenir et ne présentent pas la même vulnérabilité aux erreurs que les fichiers rédigés manuellement. Néanmoins, dans les cas où le projet doit fournir ces fichiers lui-même, la génération automatique peut être désactivée. L’option NO_GENERATE_QMLDIR désactive la génération automatique de qmldir et l’option NO_GENERATE_QMLTYPES désactive la génération automatique des fichiers typeinfo et de l’enregistrement des types C++. Si le fichier typeinfo généré automatiquement est acceptable, mais que le projet souhaite utiliser un nom différent pour ce fichier, il est possible de remplacer le nom par défaut à l’aide de l’option TYPEINFO (mais cela ne devrait généralement pas être nécessaire).

Mise en cache des sources QML compilées

Tous les fichiers .qml, .js et .mjs ajoutés au module via l’argument QML_FILES seront compilés en bytecode et mis en cache directement dans la cible de support. Cela améliore les performances du module au chargement. Les fichiers originaux non compilés sont également stockés dans les ressources de la cible de support, car ceux-ci peuvent encore être nécessaires dans certaines situations par le moteur QML.

Le chemin d’accès à la ressource de chaque fichier est déterminé par son chemin relatif par rapport au répertoire source actuel (CMAKE_CURRENT_SOURCE_DIR). Ce chemin d’accès à la ressource est ajouté à un préfixe formé en concaténant RESOURCE_PREFIX et le chemin de la cible (mais voir NO_RESOURCE_TARGET_PATH pour une exception à cette règle).

Si la politique QTP0001 est définie sur NEW, RESOURCE_PREFIX prend par défaut la valeur /qt/qml/, qui correspond au chemin d’importation par défaut du moteur QML. Cela garantit que les modules sont placés dans le chemin d’importation QML et peuvent être localisés sans configuration supplémentaire.

En règle générale, le projet doit viser à placer les fichiers .qml au même emplacement relatif que celui qu’ils occuperaient dans les ressources. Si le fichier .qml se trouve dans un répertoire relatif différent de son chemin d’accès souhaité aux ressources, son emplacement dans les ressources doit être explicitement spécifié. Pour ce faire, il faut définir la propriété du fichier source QT_RESOURCE_ALIAS, qui doit être définie avant l’ajout du fichier .qml. Par exemple :

set_source_files_properties(path/to/somewhere/MyFrame.qml PROPERTIES
    QT_RESOURCE_ALIAS MyFrame.qml
)

qt_add_qml_module(someTarget
    URI MyCo.Frames
    RESOURCE_PREFIX /my.company.com/imports
    QML_FILES
        path/to/somewhere/MyFrame.qml
        AnotherFrame.qml
)

Dans l’exemple ci-dessus, le chemin cible sera MyCo/Frames. Une fois les propriétés du fichier source prises en compte, les deux fichiers .qml se trouveront aux chemins de ressources suivants :

• /my.company.com/imports/MyCo/Frames/MyFrame.qml
• /my.company.com/imports/MyCo/Frames/AnotherFrame.qml

Dans les rares cas où vous souhaiteriez remplacer le choix automatique du programme qmlcachegen à utiliser, vous pouvez définir la propriété « QT_QMLCACHEGEN_EXECUTABLE » sur la cible du module. Par exemple :

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_EXECUTABLE qmlcachegen
)

Cela sélectionne explicitement qmlcachegen comme programme à utiliser, même si de meilleures alternatives sont disponibles.

De plus, vous pouvez passer des arguments supplémentaires à qmlcachegen en définissant l’option ` QT_QMLCACHEGEN_ARGUMENTS `. En particulier, l’option ` --only-bytecode ` désactive la compilation du code de script QML en C++. Par exemple :

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_ARGUMENTS "--only-bytecode"
)

Un autre argument important est ` --direct-calls`. Vous pouvez l'utiliser pour activer le mode direct du compilateur de scripts QML si les extensions ` Qt Quick Compiler ` sont installées. Si ces extensions ne sont pas installées, l'argument est ignoré. Il existe une forme abrégée appelée ` QT_QMLCACHEGEN_DIRECT_CALLS ` pour cet argument.

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_DIRECT_CALLS ON
)

Enfin, l’argument --verbose peut être utilisé pour afficher les messages de diagnostic de qmlcachegen :

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_ARGUMENTS "--verbose"
)

Lorsque ce drapeau est activé, qmlcachegen affiche des avertissements pour chaque fonction qu’il ne parvient pas à compiler en C++. Certains de ces avertissements signalent des problèmes dans votre code QML, tandis que d’autres indiquent que certaines fonctionnalités du langage QML ne sont pas implémentées dans le générateur de code C++. Dans les deux cas, qmlcachegen continuera à générer du bytecode pour ces fonctions. Si vous souhaitez uniquement identifier les problèmes présents dans votre code QML, vous devriez plutôt utiliser qmllint et les cibles générées pour cet outil.

Analyse des sources QML

Une cible de linting distincte sera automatiquement créée si des fichiers ` .qml ` sont ajoutés au module via le mot-clé ` QML_FILES `, ou par un appel ultérieur à `qt_target_qml_sources()`. Le nom de la cible de linting sera ` target ` suivi de ` _qmllint`. Une cible ` all_qmllint `, qui dépend de toutes les cibles individuelles ` *_qmllint `, est également fournie pour plus de commodité.

Une cible de compilation globale « dump_qml_context_properties » est automatiquement créée ; elle exécute `qmlcontextpropertydump` lorsqu’aucun fichier de vidage des propriétés de contexte QML n’existe encore. `qmlcontextpropertydump` crée un fichier de vidage des propriétés de contexte QML qui est lu par `qmllint` afin de signaler les utilisations des propriétés de contexte dans QML.

Une cible de compilation globale « clean_qml_context_properties » permet de supprimer un fichier de vidage des propriétés de contexte QML déjà existant, et peut être utilisée pour recalculer ce fichier lors d’une future exécution de la cible de compilation globale « dump_qml_context_properties ».

Les cibles de linting dépendent de la cible de compilation « dump_qml_context_properties » lorsque la variable QT_QMLLINT_CONTEXT_PROPERTY_DUMP est activée.

Conventions de nommage pour les fichiers « .js »

Les noms de fichiers JavaScript destinés à être traités comme des composants doivent commencer par une majuscule.

Vous pouvez également utiliser des noms de fichiers en minuscules et définir la propriété du fichier source QT_QML_SOURCE_TYPENAME sur le nom de type souhaité.

Singletons

Si un module QML contient des fichiers d'.qml s fournissant des types singleton, la propriété source « QT_QML_SINGLETON_TYPE » de ces fichiers doit être définie sur « TRUE » afin de garantir que la commande « singleton » soit inscrite dans le fichier qmldir. Cette opération doit être effectuée en plus de l'ajout de la directive « pragma Singleton » dans le fichier QML. La propriété source doit être définie avant la création du module auquel appartient le singleton.

Voir qt_target_qml_sources() pour un exemple illustrant comment définir la propriété « QT_QML_SINGLETON_TYPE ».

Compilation de QML en C++ avec le compilateur de types QML

Si un module QML contient des fichiers .qml, vous pouvez les compiler en C++ à l’aide de qmltc. Contrairement à la compilation en bytecode, vous devez activer explicitement qmltc via l’argument ENABLE_TYPE_COMPILER. Dans ce cas, les fichiers .qml spécifiés sous QML_FILES seront compilés. Les fichiers se terminant par .js et .mjs sont ignorés, car qmltc ne compile pas le code JavaScript. De plus, les fichiers marqués avec la propriété de fichier source QT_QML_SKIP_TYPE_COMPILER sont également ignorés.

Par défaut, qmltc crée des fichiers en minuscules .h et .cpp pour un fichier .qml donné. Par exemple, Foo.qml est finalement compilé en foo.h et foo.cpp.

Les fichiers C++ créés sont placés dans un sous-répertoire dédié, .qmltc/<target>/, de l’ BINARY_DIR de l’ target. Ces fichiers sont ensuite automatiquement ajoutés aux sources cibles et compilés en tant que code Qt C++ avec les autres fichiers source.

Lors du traitement de QML_FILES, les propriétés suivantes des fichiers source sont prises en compte :

• QT_QMLTC_FILE_BASENAME: utilisez cette propriété de fichier source pour spécifier un nom de fichier .h et .cpp différent de celui par défaut, ce qui peut s’avérer utile, par exemple, pour résoudre des conflits de noms de fichiers (imaginez que vous ayez un fichier main.qml en cours de compilation, mais que main.h existe déjà ; dans ce cas, #include "main.h" pourrait ne pas produire le résultat escompté). QT_QMLTC_FILE_BASENAME doit être un nom de fichier (sans extension) ; tout répertoire précédent est donc ignoré. Contrairement au comportement par défaut, QT_QMLTC_FILE_BASENAME n’est pas converti en minuscules.
• QT_QML_SKIP_TYPE_COMPILER: utilisez cette propriété de fichier source pour spécifier qu’un fichier QML doit être ignoré par qmltc.

Arguments

Les arguments de ` qt_add_qml_module ` sont classés dans les catégories suivantes :

Arguments indispensables

L'option target spécifie le nom de la cible sous-jacente pour le module QML. Par défaut, celle-ci est créée sous forme de bibliothèque partagée si Qt a été compilé en bibliothèques partagées, ou sous forme de bibliothèque statique dans le cas contraire. Ce choix peut être explicitement remplacé par les options STATIC ou SHARED.

Chaque module QML doit définir une URI. Celle-ci doit être spécifiée en notation URI pointée, par exemple QtQuick.Layouts. Chaque segment doit être un nom d’identifiant ECMAScript bien formé. Cela signifie, par exemple, que les segments ne doivent pas commencer par un chiffre et ne doivent pas contenir de caractères « - » (trait d’union). Comme l’ URI sera converti en noms de répertoires, vous devez le limiter aux caractères alphanumériques de l’alphabet latin, aux traits de soulignement et aux points. D'autres modules QML peuvent utiliser ce nom dans des instructions d'importation pour importer le module. L'URI sera utilisé dans la ligne « module » du fichier qmldir généré. L'URI est également utilisé pour former le chemin cible en remplaçant les points par des barres obliques.

Voir Modules identifiés pour une discussion plus approfondie sur l’URI du module.

Versions

Un module QML peut également définir une version majeure ( VERSION ) sous la forme Major.Minor, où Major et Minor doivent tous deux être des nombres entiers. Un composant .Patch supplémentaire peut être ajouté, mais il sera ignoré. Une liste des versions majeures antérieures pour lesquelles le module fournit des types peut également être indiquée de manière facultative après le mot-clé PAST_MAJOR_VERSIONS (voir ci-dessous). Consultez la section Modules identifiés pour une analyse plus approfondie de la numérotation des versions, la section Enregistrement des versions majeures antérieures pour l’enregistrement des versions majeures antérieures, et la section Synchronisation des versions des modules pour la synchronisation des versions des modules.

Si vous n’avez pas besoin de versions, vous devez omettre l’argument ` VERSION `. La valeur par défaut est la version la plus élevée possible. La gestion interne des versions des modules QML présente certains défauts fondamentaux. Vous devriez utiliser un mécanisme externe de gestion des paquets pour gérer les différentes versions de vos modules QML.

Ajout de sources et de ressources au module

SOURCES spécifie une liste de sources non-QML à ajouter à la cible de support. Cette fonctionnalité est fournie à titre de commodité et équivaut à l’ajout des sources à la cible de support à l’aide de la commande CMake intégrée ` target_sources() `.

QML_FILES répertorie les fichiers ` .qml`, ` .js ` et ` .mjs ` du module. Ceux-ci seront automatiquement compilés en bytecode et intégrés à la cible de support, sauf si l’option ` NO_CACHEGEN ` est spécifiée. Le fichier non compilé est toujours stocké dans les ressources intégrées de la cible de support, même si ` NO_CACHEGEN ` est spécifié. À moins que l’option ` NO_LINT ` ne soit spécifiée, les fichiers non compilés seront également traités par ` qmllint ` via une cible de compilation personnalisée distincte. Par défaut, ces fichiers serviront également à remplir les informations de type dans le fichier `qmldir ` généré. L’option ` NO_GENERATE_QMLDIR ` peut être spécifiée pour désactiver la génération automatique du fichier ` qmldir `. Cette option doit normalement être évitée, mais elle peut être utilisée dans les cas où le projet doit fournir son propre fichier ` qmldir `. Depuis Qt 6.8, lorsque l'option QTP0004 est activée, la commande « qt_add_qml_module » crée des fichiers « qmldir » supplémentaires pour chaque sous-répertoire du module QML, ce qui garantit que chaque fichier QML importera son propre module via l’importation implicite. Ce comportement peut être désactivé pour un module QML en lui transmettant le drapeau « NO_GENERATE_EXTRA_QMLDIRS ». L’option « NO_GENERATE_QMLDIR » implique « NO_GENERATE_EXTRA_QMLDIRS ».

RESOURCES répertorie tous les autres fichiers requis par le module, tels que les images référencées depuis le code QML. Ces fichiers seront ajoutés en tant que ressources compilées (voir RESOURCE_PREFIX pour une explication du répertoire de base sous lequel ils seront placés). Si nécessaire, leur emplacement relatif peut être contrôlé en définissant la propriété source « QT_RESOURCE_ALIAS », tout comme pour les fichiers d’ .qml (voir Mise en cache des sources QML compilées).

RESOURCE_PREFIX est destiné à encapsuler un espace de noms pour le projet et sera souvent le même pour tous les modules QML définis par le projet.

Cependant, il est préférable de définir plutôt la politique CMake « QTP0001 ». Celle-ci définit un préfixe de ressource par défaut qui garantit que votre module QML se retrouve dans l’un des chemins d’importation par défaut du moteur QML.

Si vous définissez un « RESOURCE_PREFIX », vous devez également l’ajouter aux chemins d’importation afin que le moteur QML puisse trouver le module QML.

Si QTP0001 est activé (par exemple via ` qt_standard_project_setup(REQUIRES 6.5)`), la valeur par défaut est ` "/qt/qml/"` ; sinon, elle est ` "/"`.

Lorsque divers fichiers sont ajoutés aux ressources intégrées à la compilation, ils sont placés sous un chemin formé par la concaténation de l’ RESOURCE_PREFIX et du chemin cible. Dans le cas particulier où la cible sous-jacente est un exécutable, il peut être préférable de placer les fichiers ` .qml ` du module et les autres ressources directement sous le ` RESOURCE_PREFIX `. Pour ce faire, il suffit de spécifier l’option ` NO_RESOURCE_TARGET_PATH `, qui ne peut être utilisée que si la cible sous-jacente est un exécutable.

Enregistrement des versions majeures antérieures

PAST_MAJOR_VERSIONS contient une liste des versions majeures supplémentaires prises en charge par le module. Pour chacune de ces versions et chaque fichier QML ne comportant pas de paramètre « QT_QML_SOURCE_VERSIONS », une entrée supplémentaire sera générée dans le fichier qmldir afin de spécifier la version supplémentaire. De plus, le code d’enregistrement du module généré enregistrera les versions majeures antérieures à l’aide de la fonction ` qmlRegisterModule()` côté C++. Le code d’enregistrement du module est généré automatiquement pour votre module QML, sauf si vous spécifiez ` NO_GENERATE_QMLTYPES ` (mais l’utilisation de cette option est fortement déconseillée). L’utilisation de ` PAST_MAJOR_VERSIONS ` ajoute une certaine surcharge lors de l’importation de votre module. Vous devriez incrémenter la version majeure de votre module le moins souvent possible. Dès que vous pouvez être certain que tous les fichiers QML important ce module omettent la version dans leurs importations, vous pouvez sans risque omettre ` PAST_MAJOR_VERSIONS`. Tous les fichiers QML importeront alors la dernière version de votre module. Si vous devez prendre en charge les importations versionnées, envisagez de ne prendre en charge qu’un nombre limité de versions majeures antérieures.

Déclaration des dépendances du module

IMPORTS fournit une liste des autres modules QML que ce module importe. Chaque module répertorié ici sera ajouté en tant qu’entrée import dans le fichier qmldir généré. Si un fichier QML importe ce module, il importe également tous les modules répertoriés sous IMPORTS. En option, une version peut être spécifiée en l’ajoutant après une barre oblique, par exemple QtQuick/2.0. Si la version est omise, c’est la version la plus récente disponible qui sera importée. Vous pouvez spécifier uniquement la version majeure, comme dans QtQuick/2. Dans ce cas, c’est la version mineure la plus récente disponible pour la version majeure donnée qui sera importée. Enfin, auto peut être utilisé comme version (QtQuick/auto). Si auto est spécifié, la version avec laquelle le module actuel est importé est transmise au module à importer. Étant donné une entrée QtQuick/auto dans un module YourModule, si un fichier QML spécifie import YourModule 3.14, cela entraîne l’importation de la version 3.14 de QtQuick. Pour les modules associés qui suivent un schéma de gestion des versions commun, vous devez utiliser auto.

Les entrées de IMPORTS peuvent également faire référence à des cibles CMake en préfixant le nom de la cible avec le mot-clé TARGET. Dans ce cas, l’URI du module QML est déterminé automatiquement à partir de la cible. Cela nécessite d’adopter la politique CMake QTP0005.

Par exemple, un module QML peut importer un autre module en faisant référence à la cible CMake qui le fournit :

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    IMPORTS
        TARGET OtherQmlModule
)

OPTIONAL_IMPORTS fournit une liste des autres modules QML que ce module peut importer lors de l’exécution. Ceux-ci ne sont pas importés automatiquement par le moteur QML lors de l’importation du module actuel, mais servent plutôt d’indications à des outils tels que qmllint. Les versions peuvent être spécifiées de la même manière que pour IMPORTS. Chaque module répertorié ici sera ajouté en tant qu’entrée optional import dans le fichier qmldir généré.

Les entrées dans OPTIONAL_IMPORTS peuvent également faire référence à des cibles CMake en préfixant le nom de la cible avec le mot-clé TARGET. Dans ce cas, l’URI du module QML est déterminé automatiquement à partir de la cible. Cela nécessite d’activer la politique CMake QTP0005.

Par exemple :

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    OPTIONAL_IMPORTS
        TARGET OptionalQmlModule
)

DEFAULT_IMPORTS spécifie lesquelles des importations facultatives constituent les entrées par défaut qui doivent être chargées par les outils. Une entrée doit être spécifiée pour chaque groupe d’ OPTIONAL_IMPORTS s dans le module. Comme les importations facultatives ne sont résolues qu’au moment de l’exécution, les outils tels que qmllint ne peuvent généralement pas savoir lesquelles doivent être résolues. Pour remédier à cela, vous pouvez désigner l’une des importations facultatives comme importation par défaut ; l’outil la sélectionnera alors. Si vous disposez d’une importation facultative utilisée lors de l’exécution sans configuration supplémentaire, celle-ci constitue un candidat idéal pour l’importation par défaut.

Les entrées de ` DEFAULT_IMPORTS ` peuvent également faire référence à des cibles CMake en préfixant le nom de la cible avec le mot-clé ` TARGET `. Dans ce cas, l’URI du module QML est déterminé automatiquement à partir de la cible. Cela nécessite d’adopter la politique CMake QTP0005.

Par exemple :

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    OPTIONAL_IMPORTS
        TARGET BackendA
        TARGET BackendB
    DEFAULT_IMPORTS
        TARGET BackendA
)

DEPENDENCIES fournit une liste des autres modules QML dont ce module dépend, mais qu’il n’importe pas nécessairement. Elle est généralement utilisée pour les dépendances qui n’existent qu’au niveau C++, comme un module enregistrant une classe dans QML qui utilise ou hérite de types définis en C++ dans un autre module.

Par exemple, si l'on souhaite créer une sous-classe de ` QQuickItem ` comme suit :

class MyItem: public QQuickItem { ... };

il faut alors s'assurer que le module contenant ` QQuickItem`, appelé ` QtQuick`, soit déclaré comme dépendance via l'option ` DEPENDENCIES ` :

qt_add_qml_module(myTarget
    ...
    DEPENDENCIES QtQuick
)

Si cela n’est pas fait, cela peut entraîner des erreurs de linting, des erreurs lors de la compilation des types avec qmltc ou lors de la compilation des liaisons et des fonctions vers C++ avec qmlcachegen.

Voici un autre exemple :

class MyComponent : public QObject {
    Q_OBJECT
    QML_ELEMENT

    // ...

signals:
    void sigZoomAtMousePosition(const QPointF& aMousePos, double aZoomScaleFactor);
};

où « DEPENDENCIES QtQml » est nécessaire pour que les outils QML puissent trouver et utiliser « QPointF » :

qt_add_qml_module(myTarget
    ...
    DEPENDENCIES QtQml
)

Les entrées du fichier ` DEPENDENCIES ` peuvent également faire référence à des cibles CMake en préfixant le nom de la cible avec le mot-clé ` TARGET `. Dans ce cas, l’URI du module QML et le chemin d’importation sont déterminés automatiquement à partir de la cible. Cela nécessite d’activer la politique CMake QTP0005.

Par exemple, un module QML peut déclarer une dépendance vis-à-vis d'un autre module en faisant référence à la cible CMake qui le fournit :

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    DEPENDENCIES
        TARGET OtherQmlModule
)

Lorsque la cible de support est un exécutable et que des dépendances de type « TARGET » sont utilisées (nécessite QTP0005), « qt_add_qml_module() » génère automatiquement un fichier « qt.conf » à côté de l’exécutable dans l’arborescence de compilation. Ce fichier configure le chemin d’importation QML afin que le moteur QML puisse localiser les dépendances du module lors de l’exécution sans nécessiter de saisies manuelles dans « IMPORT_PATH ». L'option ` NO_GENERATE_QTCONF ` désactive ce comportement, ce qui peut s'avérer nécessaire si le fichier généré entre en conflit avec un fichier ` qt.conf ` déjà présent dans le répertoire de compilation. Cette option a été introduite dans Qt 6.12.

La version du module des dépendances doit être spécifiée avec le nom du module, sous la même forme que celle utilisée pour IMPORTS et OPTIONAL_IMPORTS. Chaque module répertorié ici sera ajouté en tant qu'entrée depends dans le fichier qmldir généré.

IMPORT_PATH peut être utilisé pour ajouter aux chemins de recherche les emplacements où se trouvent les autres modules QML dont celui-ci dépend. Les autres modules doivent disposer de leur fichier ` qmldir ` sous leur propre chemin cible, situé sous l’un des chemins de recherche. Qt part du principe que tous les fichiers situés sous le fichier ` IMPORT_PATH ` proviennent d’une source fiable.

Si la cible sous-jacente est une bibliothèque statique et que celle-ci doit être installée, il convient de fournir à ` OUTPUT_TARGETS ` une variable dans laquelle stocker une liste de cibles supplémentaires qui devront également être installées. Ces cibles supplémentaires sont générées en interne par ` qt_add_qml_module() ` et sont référencées par les exigences de liaison de la cible sous-jacente afin de garantir que les ressources sont correctement configurées et chargées.

Cibles et cibles de plug-in

Les options suivantes contrôlent la manière dont la cible de plugin est créée et configurée. Pour la plupart des modules, les valeurs par défaut sont appropriées et aucune de ces options n’est nécessaire. Scénarios courants :

• Par défaut — une cible de plugin distincte est créée automatiquement avec un fichier source généré. Le plugin est facultatif (il n’est pas chargé lorsque la bibliothèque sous-jacente est liée directement).
• Plugin personnalisé — utilisez NO_GENERATE_PLUGIN_SOURCE pour fournir votre propre implémentation de classe de plugin. Vous devez également définir CLASS_NAME afin qu’il corresponde à votre classe de plugin personnalisée. Cela nécessite généralement aussi NO_PLUGIN_OPTIONAL, car le plugin contient alors du code non trivial.
• Pas de plugin — utilisez NO_PLUGIN lorsque le module est toujours lié directement et n’est jamais chargé dynamiquement.
• Cible exécutable — aucun plugin n’est créé automatiquement.

PLUGIN_TARGET Spécifie la cible de plugin associée au module QML. L’ PLUGIN_TARGET peut être identique à l’ target de support ; dans ce cas, il n’y aura pas de cible de support distincte. Si PLUGIN_TARGET n’est pas fourni, la valeur par défaut est target, suivie de plugin. Par exemple, une cible de base nommée mymodule aurait pour nom de plugin par défaut mymoduleplugin. Le nom de la cible du plugin sera utilisé pour remplir la ligne plugin dans le fichier qmldir généré. Par conséquent, vous ne devez pas tenter de modifier le nom de sortie du plugin en définissant des propriétés de cible telles que OUTPUT_NAME ou l’une de ses propriétés associées.

L’ target e sous-jacente et la cible du plugin (si elles sont différentes) seront créées par la commande, à moins qu’elles n’existent déjà. Les projets doivent généralement laisser la commande les créer afin qu’elles soient générées avec le type de cible approprié. Si l’ target e sous-jacente est une bibliothèque statique, le plugin sera également créé en tant que bibliothèque statique. Si l’ target est une bibliothèque partagée, le plugin sera créé en tant que bibliothèque de modules. Si une target existante est fournie et qu’il s’agit d’une cible exécutable, aucun plugin ne sera créé. Si vous avez l’intention de toujours lier directement à la cible sous-jacente et que vous n’avez pas besoin d’un plugin, vous pouvez le désactiver en ajoutant l’option NO_PLUGIN. Spécifier à la fois NO_PLUGIN et PLUGIN_TARGET constitue une erreur.

Dans certaines situations, le projet peut souhaiter retarder la création de la cible de plugin jusqu’après l’appel. L’option « NO_CREATE_PLUGIN_TARGET » peut alors être spécifiée. Le projet doit alors appeler `qt_add_qml_plugin()` sur la cible de plugin une fois celle-ci créée. Lorsque l’option « NO_CREATE_PLUGIN_TARGET » est spécifiée, l’option « PLUGIN_TARGET » doit également être fournie pour nommer explicitement la cible de plugin.

Par défaut, l’option qt_add_qml_module() génère automatiquement un fichier .cpp qui implémente la classe de plugin nommée par l’argument CLASS_NAME. Le fichier .cpp généré sera automatiquement ajouté à la cible du plugin en tant que fichier source à compiler. Si le projet souhaite fournir sa propre implémentation de la classe de plugin, l’option NO_GENERATE_PLUGIN_SOURCE doit être spécifiée. En l’absence d’ CLASS_NAME, la valeur par défaut est URI, les points étant remplacés par des traits de soulignement, puis suivie de Plugin. À moins que le module QML ne dispose d’aucun plugin, le nom de la classe sera enregistré sous la forme d’une ligne classname dans le fichier qmldir généré. Vous devez ajouter tous les fichiers C++ contenant du code de plugin personnalisé à la cible du plugin. Étant donné que le plugin contient alors probablement des fonctionnalités qui vont au-delà du simple chargement de la bibliothèque sous-jacente, vous souhaiterez sans doute ajouter également NO_PLUGIN_OPTIONAL. Sinon, le moteur QML risque de ne pas charger le plugin s’il détecte que la bibliothèque sous-jacente est déjà liée.

Si le mot-clé ` NO_PLUGIN ` est spécifié, aucun plugin ne sera compilé. Ce mot-clé est donc incompatible avec toutes les options permettant de personnaliser la cible du plugin, notamment NO_GENERATE_PLUGIN_SOURCE, NO_PLUGIN_OPTIONAL, PLUGIN_TARGET, NO_CREATE_PLUGIN_TARGET et CLASS_NAME. Si vous ne fournissez pas de plugin pour votre module, celui-ci ne sera pleinement utilisable que si sa bibliothèque de support a été liée à l’exécutable. Il est généralement difficile de garantir qu’un éditeur de liens préserve la liaison vers une bibliothèque qu’il considère comme inutilisée.

Si le mot-clé « NO_PLUGIN_OPTIONAL » est spécifié, le plugin est alors enregistré dans le fichier généré « qmldir » comme non optionnel. Si toutes les fonctionnalités d’un module QML sont implémentées dans sa cible de base et que la cible du plugin est distincte, le plugin peut alors être optionnel, ce qui constitue la configuration par défaut et recommandée. Le fichier source du plugin généré automatiquement répond à cette exigence. Lorsqu’un projet fournit sa propre implémentation de ` .cpp ` pour le plugin, cela signifie généralement que le mot-clé ` NO_PLUGIN_OPTIONAL ` est également nécessaire, car le plugin contiendra presque certainement des fonctionnalités dont le module QML a besoin.

Enregistrement automatique des types

qt_add_qml_module génère automatiquement plusieurs fichiers. Les options suivantes contrôlent ce qui est généré. Dans la plupart des cas, les valeurs par défaut sont correctes et aucune de ces options n’est nécessaire.

L'enregistrement des types est effectué automatiquement pour les sources C++ de la cible sous-jacente qui sont traitées par AUTOMOC. Cela génère un fichier typeinfo dans le répertoire de sortie, dont le nom correspond au nom de l'target, suivi de « .qmltypes ». Ce nom de fichier peut être modifié à l'aide de l'option TYPEINFO si nécessaire, mais cela ne devrait normalement pas être nécessaire. Le nom du fichier est également enregistré sous la forme d’une entrée typeinfo dans le fichier qmldir généré. L’enregistrement automatique des types peut être désactivé à l’aide de l’option NO_GENERATE_QMLTYPES; dans ce cas, aucun fichier typeinfo ne sera généré, mais le projet devra tout de même générer un fichier typeinfo et le placer dans le même répertoire que le fichier qmldir généré.

OUTPUT_DIRECTORY spécifie l’emplacement où sont générés la bibliothèque du plugin, le fichier ` qmldir ` et les fichiers `typeinfo`. Lorsque ce mot-clé n’est pas fourni, la valeur par défaut est le chemin de la cible (formé à partir de ` URI`) suivi de la valeur de la variable `QT_QML_OUTPUT_DIRECTORY`. Si cette variable n’est pas définie, la valeur par défaut dépend du type de cible sous-jacente. Pour les exécutables, la valeur correspondra au chemin de la cible suivi de ${CMAKE_CURRENT_BINARY_DIR}, tandis que pour les autres cibles, elle sera simplement ${CMAKE_CURRENT_BINARY_DIR}. Lorsque la structure de l’arborescence des sources correspond à celle des chemins de cibles des modules QML (ce qui est fortement recommandé), QT_QML_OUTPUT_DIRECTORY n’est souvent pas nécessaire. Afin de respecter la structure des chemins d'accès des cibles, vous devez nommer vos répertoires exactement comme les segments de l'URI de votre module. Par exemple, si l'URI de votre module est MyUpperCaseThing.mylowercasething, vous devez le placer dans un répertoire nommé MyUpperCaseThing/mylowercasething/.

Il est rarement nécessaire de spécifier le mot-clé OUTPUT_DIRECTORY, mais si vous l’utilisez, il est probable que l’appelant doive également l’ajouter à IMPORT_PATH afin de garantir le bon fonctionnement du linting, de la compilation en cache des sources QML, de l’importation automatique des plugins dans les builds statiques et du déploiement des modules QML importés pour les builds non statiques.

Qt Quick Compatibilité avec le Designer

DESIGNER_SUPPORTED doit être assurée si le module QML prend en charge Qt Quick Designer. Lorsqu’elle est présente, le fichier qmldir généré contiendra une ligne designersupported. Consultez la section « Fichiers qmldir de définition de module » pour savoir comment cela affecte la manière dont Qt Quick Designer gère le plugin.

Synchronisation des versions des modules

Le mot-clé « FOLLOW_FOREIGN_VERSIONING » concerne les types de base de vos propres types QML définis en C++ qui se trouvent dans différents modules QML. En général, le schéma de gestion des versions de votre module ne correspond pas à celui du module fournissant les types de base. Par défaut, toutes les révisions des types de base sont donc mises à disposition lors de toute importation de votre module. Si l’option « FOLLOW_FOREIGN_VERSIONING » est spécifiée, les informations de version associées aux types de base et à leurs propriétés sont respectées. Ainsi, une instruction ` import MyModule 2.8 ` ne rendra accessibles que les propriétés versionnées jusqu’à la version 2.8 de tout type de base situé en dehors de MyModule. Cela s’avère particulièrement utile si vous souhaitez synchroniser la version de votre module avec celle des autres modules sur lesquels reposent vos types. Dans ce cas, vous souhaiterez peut-être que vos types personnalisés n’exposent pas les propriétés issues d’une version du type de base d’un module supérieure à celle en cours d’importation.

Espaces de noms C++ du code généré

Si un espace de noms est spécifié avec le mot-clé « NAMESPACE », le plugin et le code d’enregistrement seront générés dans un espace de noms C++ portant ce nom.

qmlimportscanner et NO_IMPORT_SCAN

Pour les compilations Qt statiques, la fonction ` qmlimportscanner ` est exécutée lors de la phase de configuration afin d’analyser les fichiers ` .qml ` d’un module QML et d’identifier les importations QML qu’il utilise (voir `qt_import_qml_plugins()`). Pour les builds Qt non statiques, si la cible est un exécutable, une analyse similaire est effectuée au moment de la compilation afin de fournir les informations nécessaires aux scripts de déploiement (voir qt_deploy_qml_imports()). Ces deux analyses peuvent être désactivées en spécifiant l’option « NO_IMPORT_SCAN ». Cela signifie que le projet se charge de s’assurer que tous les plugins requis sont instanciés et liés pour les compilations statiques. Pour les compilations non statiques, le projet doit déterminer manuellement et déployer tous les modules QML utilisés par une cible exécutable.

DISCARD_QML_CONTENTS

Par défaut, le contenu des fichiers source QML et JS est inclus dans le système de ressources de la cible. Utilisez l’option ` DISCARD_QML_CONTENTS ` pour supprimer ce contenu et réduire la taille du binaire.

Arguments de qmltc

ENABLE_TYPE_COMPILER peuvent être utilisés pour compiler des fichiers « .qml » en code source C++ à l’aide de qmltc. Les fichiers dont la propriété « source » est définie sur « QT_QML_SKIP_TYPE_COMPILER » ne sont pas compilés en C++.

TYPE_COMPILER_NAMESPACE Cet argument permet de redéfinir l'espace de noms dans lequel qmltc génère le code. Par défaut, l'espace de noms du code généré suit la hiérarchie des modules telle qu'elle est représentée dans l'URI ; par exemple, MyModule pour un module dont l'URI est MyModule, ou com::example::Module pour l'URI com.example.MyModule. En spécifiant l’option TYPE_COMPILER_NAMESPACE, le code généré peut être placé à la place dans un espace de noms personnalisé, où les différents sous-espaces de noms doivent être séparés par « :: », par exemple « MyNamespace::MySubnamespace » pour l’espace de noms MySubnamespace situé à l’intérieur de MyNamespace. Hormis le « :: », les règles de nommage des espaces de noms C++ s’appliquent.

QMLTC_EXPORT_DIRECTIVE L'option « QMLTC_EXPORT_FILE_NAME » doit être utilisée lorsque les classes générées par qmltc doivent être exportées depuis la bibliothèque QML. Par défaut, les classes générées par qmltc ne sont pas exportées depuis leur bibliothèque. L’en-tête définissant la macro d’exportation pour la bibliothèque actuelle peut être spécifié comme argument facultatif de ` QMLTC_EXPORT_FILE_NAME `, tandis que le nom de la macro d’exportation doit être spécifié comme argument de ` QMLTC_EXPORT_DIRECTIVE`. Si aucune inclusion supplémentaire n’est requise ou souhaitée, par exemple lorsque l’en-tête de la macro d’exportation est déjà indirectement inclus par une classe de base, l’option ` QMLTC_EXPORT_FILE_NAME ` peut alors être omise.