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 paquetage Qt6, qui peut être chargé comme suit :

find_package(Qt6 REQUIRED COMPONENTS Qml)

Synopsis

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_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 qt6_add_qml_module() à la place. Elle prend en charge le même ensemble d'arguments que cette commande.

Voir Construire une application QML et Construire un module QML réutilisable pour des exemples qui définissent des modules QML.

Description de la commande

Cette commande définit un module QML qui peut être constitué de sources C++, de fichiers .qml ou des deux. Elle s'assure que les détails essentiels du module sont fournis et qu'ils sont cohérents. Elle met également en place et coordonne 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.

Structure de la cible

Un module QML peut être structuré de différentes manières. Les scénarios suivants sont des arrangements typiques :

Cibles distinctes pour le backing et le plugin

Il s'agit de la structure recommandée pour la plupart des modules QML. Toutes les fonctionnalités du module sont implémentées dans la cible d'accompagnement, qui est le premier argument de la commande. Les sources C++, les fichiers .qml et les ressources doivent tous être ajoutés à la cible d'accompagnement. La cible secondaire est une bibliothèque qui doit être installée au même endroit que toute autre bibliothèque définie par le projet.

La structure du répertoire source sous lequel la cible d'accompagnement est créée doit correspondre au chemin cible du module QML (le chemin cible est l'URI du module avec les points remplacés par des barres obliques). Si la structure du répertoire source ne correspond pas au chemin cible, qt_add_qml_module() émettra un avertissement.

L'exemple suivant montre une structure de répertoire source appropriée pour un module QML dont l'URI est MyThings.Panels. L'appel à qt_add_qml_module() se trouve dans le fichier CMakeLists.txt illustré.

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

Une cible de plugin distincte est associée au module QML. Elle est utilisée au moment de l'exécution pour charger le module dynamiquement lorsque l'application n'est pas déjà liée à la cible d'appui. La cible d'extension est également une bibliothèque et est normalement installée dans le même répertoire que le fichier qmldir du module.

La cible du plugin devrait idéalement ne contenir rien de plus qu'une implémentation triviale de la classe du plugin. Cela permet au plugin d'être désigné comme optionnel dans le fichier qmldir. D'autres cibles peuvent alors être liées directement à la cible de soutien et le plugin ne sera pas nécessaire à l'exécution, ce qui peut améliorer les performances lors du chargement. Par défaut, un fichier source C++ définissant une classe de plugin minimale sera automatiquement généré et ajouté à la cible du 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 les plugins QML statiques si NO_PLUGIN n'est pas spécifié. Les cibles qui importent ces modules QML STATIC doivent également établir un lien explicite avec les plugins QML correspondants.

Cible du plugin sans cible d'appui

Un module QML peut être défini avec la cible du plugin servant de cible d'appui. Dans ce cas, le module doit être chargé dynamiquement au moment de l'exécution et ne peut pas être lié directement à d'autres cibles. Pour créer cet arrangement, le mot-clé PLUGIN_TARGET doit être utilisé, avec target répété comme nom de la cible du plugin. Par exemple :

qt_add_qml_module(someTarget
    PLUGIN_TARGET someTarget
    ...
)

Bien que cet arrangement puisse sembler légèrement plus simple à déployer, une cible de support séparée devrait être préférée lorsque cela est possible en raison des meilleures performances potentielles en termes de temps de chargement.

Exécutable en tant que module QML

Une cible exécutable peut servir de cible d'appui pour un module QML. Dans ce cas, il n'y aura pas de bibliothèque d'extension, puisque le module QML sera toujours chargé directement dans le cadre de l'application. La commande qt_add_qml_module() détectera l'utilisation d'un exécutable en tant que cible d'appui et désactivera automatiquement la création d'un plugin séparé. N'utilisez aucune des options dont le nom contient PLUGIN lorsque vous utilisez cet arrangement.

Lorsqu'un exécutable est utilisé comme cible de référence, la structure du répertoire source n'est pas censée correspondre au chemin cible du module QML. Voir Mise en cache des sources QML compilées pour d'autres différences de chemin cible pour 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 donnés à cette commande, ainsi que par les fichiers sources et .qml ajoutés à la cible de sauvegarde. L'argument OUTPUT_DIRECTORY détermine où les fichiers qmldir et typeinfo seront écrits. Si le module QML possède un plugin, celui-ci sera également créé dans le même répertoire que le fichier qmldir.

Si la politique de QTP0004 est définie sur NEW, un autre fichier qmldir est généré pour chaque répertoire supplémentaire contenant des fichiers .qml. Ces fichiers qmldir supplémentaires redirigent simplement vers le répertoire de base du module via une directive prefer. Cela permet à tous les composants QML d'un module d'accéder les uns aux autres, quel que soit le répertoire dans lequel ils sont stockés.

Si vous utilisez un Qt XML construit statiquement, les fichiers .qml de la cible d'appui seront analysés lors de l'exécution de CMake configure afin de déterminer les importations utilisées par le module et d'établir des relations de liaison (le mot-clé NO_IMPORT_SCAN peut être donné pour désactiver cela). Lorsqu'un fichier .qml est ajouté ou supprimé du module, CMake est normalement relancé automatiquement et les fichiers concernés sont à nouveau analysés, étant donné qu'un fichier CMakeLists.txt a été modifié. Au cours du développement, un fichier .qml existant peut ajouter ou supprimer un import ou un type. En soi, cela n'entraînerait pas la ré-exécution automatique de CMake, vous devez donc explicitement ré-exécuter 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 de sauvegarde sont analysées au moment de la compilation afin de générer un fichier d'information sur les types et un fichier C++ pour enregistrer les types associés. Le fichier C++ généré est automatiquement ajouté à la cible de référence en tant que source. Pour ce faire, AUTOMOC doit être activé sur la cible. Le projet doit s'en assurer, généralement en définissant la variable CMAKE_AUTOMOC à TRUE avant d'appeler qt_add_qml_module(), ou en passant une cible existante avec la propriété AUTOMOC target déjà définie à TRUE. Ce n'est pas une erreur d'avoir AUTOMOC désactivé sur la cible, mais le projet est alors responsable d'en gérer les conséquences. Il peut s'agir de générer manuellement le fichier typeinfo au lieu de le laisser s'auto-générer avec des détails manquants, et d'ajouter du code C++ pour enregistrer les types.

Dans la mesure du possible, les projets devraient préférer utiliser les fichiers typeinfo et qmldir générés automatiquement. Ils sont plus faciles à maintenir et ne souffrent pas de la même susceptibilité aux erreurs que les fichiers écrits à la main. Néanmoins, pour les situations 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 de typeinfo et d'enregistrement de type 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 peut remplacer le nom par défaut avec l'option TYPEINFO (mais cela ne devrait pas être nécessaire en général).

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 d'appui. Cela permet d'améliorer les performances de chargement du module. Les fichiers originaux non compilés sont également stockés dans les ressources de la cible d'appui, car le moteur QML peut encore en avoir besoin dans certaines situations.

Le chemin des ressources de chaque fichier est déterminé par son chemin relatif au répertoire source actuel (CMAKE_CURRENT_SOURCE_DIR). Ce chemin de ressource est ajouté à un préfixe formé par la concaténation de RESOURCE_PREFIX et du chemin de la cible (voir NO_RESOURCE_TARGET_PATH pour une exception à cette règle).

Si la politique QTP0001 est définie sur NEW, le RESOURCE_PREFIX est défini par défaut sur /qt/qml/, qui est le chemin d'importation par défaut du moteur QML. Cela garantit que les modules sont placés dans le chemin d'importation QML et qu'ils peuvent être trouvés sans autre configuration.

En règle générale, le projet doit s'efforcer de 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 du chemin des ressources souhaité, son emplacement dans les ressources doit être explicitement spécifié. Pour ce faire, il convient de 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. Après avoir pris en compte les propriétés du fichier source, les deux fichiers .qml se trouveront dans les 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 souhaitez ignorer la sélection automatique du programme qmlcachegen à utiliser, vous pouvez définir la propriété QT_QMLCACHEGEN_EXECUTABLE target sur la cible du module. Par exemple :

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_EXECUTABLE qmlcachegen
)

Ceci sélectionne explicitement qmlcachegen comme le 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 l'option --direct-calls. Vous pouvez l'utiliser pour activer le mode direct du compilateur de scripts QML si les extensions du compilateur Qt Quick sont installées. Si les extensions ne sont pas installées, l'argument est ignoré. Il existe un raccourci appelé 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 voir les résultats de diagnostic de qmlcachegen :

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_ARGUMENTS "--verbose"
)

Avec ce drapeau activé, qmlcachegen émettra des avertissements pour chaque fonction qu'il ne peut pas compiler en C++. Certains de ces avertissements indiqueront des problèmes dans votre code QML et d'autres vous diront que certaines caractéristiques du langage QML ne sont pas implémentées dans le générateur de code C++. Dans les deux cas, qmlcachegen générera quand même du code à octets pour ces fonctions. Si vous ne voulez voir que les problèmes dans votre code QML, vous devriez plutôt utiliser qmllint et les cibles générées pour lui.

Linting des sources QML

Une cible de linting séparée 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 d'analyse sera target suivi de _qmllint. Une cible all_qmllint qui dépend de toutes les cibles *_qmllint individuelles est également fournie par commodité.

Une cible de compilation globale dump_qml_context_properties est automatiquement créée pour exécuter qmlcontextpropertydump lorsqu'il n'existe pas de fichier de vidage des propriétés du contexte qml . qmlcontextpropertydump crée un fichier de vidage des propriétés du contexte qml qui est lu par qmllint pour signaler l'utilisation des propriétés du contexte en QML.

Une cible de construction 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 le fichier de vidage des propriétés de contexte qml lors d'une future construction de la cible de construction 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 d'appellation pour les fichiers .js

Les noms de fichiers JavaScript destinés à être adressés en tant que composants doivent commencer par une lettre majuscule.

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

Singletons

Si un module QML possède des fichiers .qml qui fournissent des types singleton, la propriété source de ces fichiers QT_QML_SINGLETON_TYPE doit être réglée sur TRUE, afin de garantir que la commande singleton est écrite dans le fichier qmldir. Cette opération doit être effectuée en plus du fichier QML contenant la déclaration pragma Singleton. La propriété source doit être définie avant de créer le module auquel le singleton appartient.

Voir qt_target_qml_sources() pour un exemple de définition de la propriété QT_QML_SINGLETON_TYPE.

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

Si un module QML a des fichiers .qml, vous pouvez les compiler en C++ en utilisant qmltc. Contrairement à la compilation du bytecode, vous devez explicitement activer 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 les fichiers .h et .cpp en minuscules pour un fichier .qml donné. Par exemple, Foo.qml est compilé en foo.h et foo.cpp.

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

Lors du traitement des QML_FILES, les propriétés suivantes des fichiers sources sont respectées :

• QT_QMLTC_FILE_BASENAMEQT_QMLTC_FILE : utilisez cette propriété du fichier source pour spécifier un nom de fichier .h et .cpp autre que celui par défaut, ce qui peut être utile pour, par exemple, résoudre des conflits de noms de fichiers (imaginez que vous avez main.qml qui est compilé, mais que main.h existe déjà, de sorte que #include "main.h" pourrait ne pas faire ce que vous attendez qu'il fasse). QT_QMLTC_FILE_BASENAME est censé être un nom de fichier (sans extension), donc tout répertoire précédent est ignoré. Contrairement au comportement par défaut, le QT_QMLTC_FILE_BASENAME n'est pas en minuscules.
• QT_QML_SKIP_TYPE_COMPILERQT_QMLTC_FILE_BASENAME : utiliser cette propriété de fichier source pour spécifier qu'un fichier QML doit être ignoré par qmltc.

Arguments

Arguments requis

L'argument target spécifie le nom de la cible d'appui pour le module QML. Par défaut, il est créé en tant que bibliothèque partagée si Qt a été construit en tant que bibliothèque partagée, ou en tant que bibliothèque statique dans le cas contraire. Ce choix peut être explicitement surchargé avec les options STATIC ou SHARED.

Chaque module QML doit définir un URI. Il doit être spécifié en notation URI pointée, comme 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 - (moins). Comme l'adresse URI sera traduite en noms de répertoire, vous devez la 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. Le URI sera utilisé dans la ligne module du fichier qmldir généré. Le 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 un VERSION sous la forme Major.Minor, où Major et Minor doivent ê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 fournie à titre facultatif après le mot-clé PAST_MAJOR_VERSIONS (voir ci-dessous). Voir Modules identifiés pour une discussion plus approfondie sur la numérotation des versions, Enregistrer les versions majeures antérieures pour enregistrer les versions majeures antérieures, et Garder les versions des modules synchronisées pour garder les versions des modules synchronisées.

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

Ajouter des sources et des ressources au module

SOURCES spécifie une liste de sources non-QML à ajouter à la cible d'appui. Elle est fournie par commodité et est équivalente à l'ajout des sources à la cible d'accompagnement avec la commande CMake intégrée target_sources().

QML_FILES liste les fichiers .qml, .js et .mjs pour le module. Ceux-ci seront automatiquement compilés en bytecode et incorporés dans la cible d'accompagnement à moins que l'option NO_CACHEGEN ne soit donnée. Le fichier non compilé est toujours stocké dans les ressources intégrées de la cible d'appui, même si l'option NO_CACHEGEN est spécifiée. À moins que l'option NO_LINT ne soit fournie, les fichiers non compilés seront également traités par qmllint via une cible de compilation personnalisée distincte. Les fichiers seront également utilisés pour remplir les informations de type dans le fichier qmldir généré par défaut. NO_GENERATE_QMLDIR peut être indiqué pour désactiver la génération automatique du fichier qmldir. Cela devrait normalement être évité, mais dans les cas où le projet doit fournir son propre fichier qmldir, cette option peut être utilisée. Depuis Qt 6.8, lorsque QTP0004 est activé, qt_add_qml_module créera 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 passant le drapeau NO_GENERATE_EXTRA_QMLDIRS. Le drapeau NO_GENERATE_QMLDIR implique NO_GENERATE_EXTRA_QMLDIRS.

RESOURCES liste tous les autres fichiers nécessaires au module, tels que les images référencées dans le code QML. Ces fichiers seront ajoutés en tant que ressources compilées (voir RESOURCE_PREFIX pour une explication du point de base sous lequel ils seront situés). Si nécessaire, leur emplacement relatif peut être contrôlé en définissant la propriété QT_RESOURCE_ALIAS source, comme pour les fichiers .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 que le projet définit.

Cependant, il est préférable de définir la politique QTP0001 de CMake. Elle définit un préfixe de ressource par défaut qui garantit que votre module QML se retrouve sous 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 pour que le moteur QML trouve 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 compilées, ils sont placés sous un chemin formé par la concaténation du chemin RESOURCE_PREFIX et du chemin cible. Dans le cas particulier où la cible d'appui est un exécutable, il peut être souhaitable de placer les fichiers .qml du module et d'autres ressources directement sous le chemin RESOURCE_PREFIX. Cela peut être réalisé en spécifiant l'option NO_RESOURCE_TARGET_PATH, qui ne peut être utilisée que si la cible d'appui est un exécutable.

Enregistrement des versions majeures antérieures

PAST_MAJOR_VERSIONS contient une liste des versions majeures supplémentaires fournies par le module. Pour chacune de ces versions et pour chaque fichier QML sans paramètre QT_QML_SOURCE_VERSIONS, une entrée supplémentaire dans le fichier qmldir sera générée pour spécifier la version supplémentaire. En outre, le code d'enregistrement du module généré enregistrera les versions majeures antérieures à l'aide de qmlRegisterModule() du côté C++. Le code d'enregistrement du module est automatiquement généré 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 lorsque votre module est importé. Vous devriez incrémenter la version majeure de votre module aussi rarement que possible. Une fois que vous pouvez compter sur le fait que tous les fichiers QML qui importent ce module omettent la version dans leurs importations, vous pouvez en toute sécurité 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 par version, envisagez de ne prendre en charge qu'un nombre limité de versions majeures antérieures.

Déclarer les dépendances d'un module

IMPORTS fournit une liste des autres modules QML que ce module importe. Chaque module listé 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 listés sous IMPORTS. En option, une version peut être spécifiée en l'ajoutant après une barre oblique, comme QtQuick/2.0. L'omission de la version entraînera l'importation de la version la plus récente disponible. Vous pouvez ne spécifier que la version majeure, comme dans QtQuick/2. Dans ce cas, la plus grande version mineure disponible avec la version majeure donnée sera importée. Enfin, auto peut être indiqué comme version (QtQuick/auto). Si auto est donné, la version avec laquelle le module actuel est importé est propagée au module à importer. Étant donné une entrée QtQuick/auto dans un module YourModule, si un fichier QML spécifie import YourModule 3.14, il en résulte l'importation de la version 3.14 de QtQuick. Pour les modules apparentés qui suivent un schéma de versionnement commun, il convient d'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'accepter la politique QTP0005 de CMake.

Par exemple, un module QML peut importer un autre module en se référant à 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 d'autres modules QML que ce module peut importer au moment de l'exécution. Ces modules ne sont pas automatiquement importés par le moteur QML lors de l'importation du module courant, 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 listé ici sera ajouté en tant qu'entrée optional import dans le fichier qmldir généré.

Les entrées de 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'accepter 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, parmi les importations optionnelles, les entrées par défaut qui doivent être chargées par l'outil. Une entrée doit être spécifiée pour chaque groupe de OPTIONAL_IMPORTS dans le module. Comme les importations optionnelles ne sont résolues qu'au moment de l'exécution, les outils comme qmllint ne peuvent généralement pas savoir quelles importations optionnelles doivent être résolues. Pour remédier à cela, vous pouvez spécifier l'un des imports optionnels comme import par défaut ; l'outil le choisira alors. Si vous avez un import optionnel qui est utilisé au moment de l'exécution sans autre configuration, c'est un candidat idéal pour l'import 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'accepter 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 d'autres modules QML dont ce module dépend, mais qu'il n'importe pas nécessairement. Il serait typiquement utilisé 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 sous-classer QQuickItem comme suit :

class MyItem: public QQuickItem { ... };

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

qt_add_qml_module(myTarget
    ...
    DEPENDENCIES QtQuick
)

Si vous ne le faites pas, vous risquez d'avoir des erreurs de linting, des erreurs lors de la compilation des types avec qmltc ou lors du binding et de la compilation des fonctions en C++ avec qmlcachegen.

Un autre exemple pourrait être le suivant :

class MyComponent : public QObject {
    Q_OBJECT
    QML_ELEMENT

    // ...

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

où DEPENDENCIES QtQml est nécessaire pour que l'outil QML trouve et utilise QPointF:

qt_add_qml_module(myTarget
    ...
    DEPENDENCIES QtQml
)

Les entrées dans 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'accepter la politique CMake QTP0005.

Par exemple, un module QML peut déclarer une dépendance sur un autre module en se référant à la cible CMake qui le fournit :

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    DEPENDENCIES
        TARGET OtherQmlModule
)

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

IMPORT_PATH peut être utilisé pour ajouter des chemins de recherche où d'autres modules QML dont celui-ci dépend peuvent être trouvés. Les autres modules doivent avoir leur fichier qmldir dans leur propre chemin cible sous l'un des chemins de recherche.

Si la cible de soutien est une bibliothèque statique et que cette bibliothèque statique sera installée, OUTPUT_TARGETS doit être utilisé pour fournir 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 d'appui afin de garantir que les ressources sont configurées et chargées correctement.

Cibles et cibles de plugins

PLUGIN_TARGET spécifie la cible de plugin associée au module QML. L'adresse PLUGIN_TARGET peut être la même que l'adresse target, auquel cas il n'y aura pas de cible d'accompagnement distincte. Si PLUGIN_TARGET n'est pas indiqué, il s'agit par défaut de target avec plugin en annexe. Par exemple, une cible d'appui appelée mymodule aura un nom de plugin par défaut de mymoduleplugin. Le nom de la cible de plugin sera utilisé pour remplir une ligne plugin dans le fichier qmldir généré. Par conséquent, vous ne devez pas essayer de modifier le nom de sortie du plugin en définissant des propriétés de cible telles que OUTPUT_NAME ou toute autre propriété connexe.

Le backing target et la cible du plugin (si elle est différente) seront créés par la commande, à moins qu'ils n'existent déjà. Les projets devraient généralement les laisser être créés par la commande afin qu'ils soient créés en tant que type de cible approprié. Si le support target est une bibliothèque statique, le plugin sera également créé en tant que bibliothèque statique. Si le support target est une bibliothèque partagée, le plugin sera créé en tant que bibliothèque de module. Si un target existant est transmis et qu'il s'agit d'une cible exécutable, il n'y aura pas de plugin. Si vous avez l'intention de toujours établir un lien direct avec la cible de référence 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 est une erreur.

Dans certaines situations, le projet peut vouloir retarder la création de la cible du plugin jusqu'à la fin de l'appel. L'option NO_CREATE_PLUGIN_TARGET peut être utilisée dans ce cas. Le projet est alors censé appeler qt_add_qml_plugin() sur la cible du plugin une fois qu'elle a été créée. Lorsque NO_CREATE_PLUGIN_TARGET est fourni, PLUGIN_TARGET doit également être fourni pour nommer explicitement la cible du plugin.

Par défaut, qt_add_qml_module() générera 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 fournie. Si l'option CLASS_NAME n'est pas fournie, le fichier URI sera utilisé par défaut, les points étant remplacés par des traits de soulignement, puis Plugin sera ajouté. À moins que le module QML n'ait pas de 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. Puisque le plugin contient probablement des fonctionnalités qui vont au-delà du simple chargement de la bibliothèque d'appui, vous voudrez probablement ajouter NO_PLUGIN_OPTIONAL, aussi. Sinon, le moteur QML peut ignorer le chargement du plugin s'il détecte que la bibliothèque d'accompagnement est déjà liée.

Si le mot-clé NO_PLUGIN est donné, aucun plugin ne sera construit. Ce mot-clé est donc incompatible avec toutes les options qui personnalisent la cible du plugin, en particulier 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 d'accompagnement a été liée à l'exécutable. Il est généralement difficile de garantir qu'un éditeur de liens préserve le lien avec une bibliothèque qu'il considère comme inutilisée.

Si le mot-clé NO_PLUGIN_OPTIONAL est donné, le plugin est enregistré dans le fichier qmldir généré comme non optionnel. Si toutes les fonctionnalités d'un module QML sont implémentées dans sa cible d'appui et que la cible du plugin est séparée, alors le plugin peut être optionnel, ce qui est l'arrangement par défaut et recommandé. Le fichier source du plugin généré automatiquement répond à cette exigence. Lorsqu'un projet fournit sa propre implémentation .cpp pour le plugin, cela signifie normalement 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

L'enregistrement des types est automatiquement effectué pour les sources C++ de la cible d'appui qui sont traitées par AUTOMOC. Cela génère un fichier typeinfo dans le répertoire de sortie, le nom du fichier étant le nom target avec .qmltypes en annexe. Ce nom de fichier peut être modifié en utilisant l'option TYPEINFO si vous le souhaitez, mais cela ne devrait normalement pas être nécessaire. Le nom du fichier est également enregistré comme 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, auquel cas aucun fichier d'information sur les types ne sera généré, mais le projet devra quand même générer un fichier d'information sur les types et le placer dans le même répertoire que le fichier qmldir généré.

OUTPUT_DIRECTORY spécifie l'endroit où la bibliothèque de plugins, qmldir et les fichiers d'informations de type sont générés. Si ce mot-clé n'est pas donné, la valeur par défaut sera le chemin cible (formé à partir de URI) ajouté à 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 de sauvegarde. Pour les exécutables, la valeur sera le chemin de la cible ajouté à ${CMAKE_CURRENT_BINARY_DIR}, alors que pour les autres cibles, ce sera juste ${CMAKE_CURRENT_BINARY_DIR}. Lorsque la structure de l'arborescence des sources correspond à la structure des chemins d'accès aux cibles des modules QML (ce qui est fortement recommandé), QT_QML_OUTPUT_DIRECTORY n'est souvent pas nécessaire. Pour que la structure des chemins cibles corresponde, vous devez appeler 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 appelé MyUpperCaseThing/mylowercasething/.

Le besoin de spécifier le mot-clé OUTPUT_DIRECTORY devrait être rare, mais s'il est utilisé, il est probable que l'appelant devra également ajouter au IMPORT_PATH pour s'assurer que le linting, la compilation en cache des sources QML, l'importation automatique des plugins dans les constructions statiques et le déploiement des modules QML importés pour les constructions non statiques fonctionnent tous correctement.

Qt Quick Compatibilité avec le designer

DESIGNER_SUPPORTED doit être indiqué si le module QML prend en charge Qt Quick Designer. S'il est présent, le fichier qmldir généré contiendra une ligne designersupported. Voir Définition du module qmldir Files pour savoir comment cela affecte la façon dont Qt Quick Designer gère le plugin.

Synchronisation des versions des modules

Le mot-clé FOLLOW_FOREIGN_VERSIONING se rapporte aux types de base de vos propres types QML définis en C++ qui vivent dans différents modules QML. Généralement, le schéma de version de votre module ne correspond pas à celui du module fournissant les types de base. Par conséquent, toutes les révisions des types de base sont disponibles par défaut dans toute importation de votre module. Si FOLLOW_FOREIGN_VERSIONING est donné, les informations de version attachées aux types de base et à leurs propriétés sont respectées. Ainsi, un import MyModule 2.8 ne rendra disponible que les propriétés versionnées jusqu'à la version 2.8 de tous les types de base en dehors de MyModule. Cela est surtout utile si vous voulez que la version de votre module soit synchronisée avec celle des autres modules sur lesquels vous basez vos types. Dans ce cas, vous pourriez vouloir que vos types personnalisés n'exposent pas les propriétés d'un type de base d'un module dont la version est supérieure à celle qui est importée.

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

Si un espace de noms est donné avec le mot-clé NAMESPACE, le code du plugin et de l'enregistrement sera généré dans un espace de noms C++ de ce nom.

qmlimportscanner et NO_IMPORT_SCAN

Pour les constructions statiques de Qt, qmlimportscanner est exécuté au moment de la configuration pour analyser les fichiers .qml d'un module QML et identifier les importations QML qu'il utilise (voir qt_import_qml_plugins()). Pour les constructions non statiques de Qt, si la cible est un exécutable, une analyse similaire est effectuée au moment de la construction pour fournir les informations nécessaires aux scripts de déploiement (voir qt_deploy_qml_imports()). Les deux analyses peuvent être désactivées en fournissant l'option NO_IMPORT_SCAN. Cela signifie que le projet prend la responsabilité de s'assurer que tous les plugins nécessaires sont instanciés et liés pour les constructions statiques. Pour les constructions non statiques, le projet doit élaborer et déployer manuellement tous les modules QML utilisés par une cible exécutable.

DISCARD_QML_CONTENTS

Par défaut, les contenus des fichiers sources QML et JS sont inclus dans le système de ressources de la cible. Utilisez DISCARD_QML_CONTENTS pour supprimer ces contenus et réduire la taille du binaire.

Arguments pour qmltc

ENABLE_TYPE_COMPILER peuvent être utilisés pour compiler les fichiers .qml en code source C++ avec qmltc. Les fichiers ayant la propriété source QT_QML_SKIP_TYPE_COMPILER ne sont pas compilés en C++.

TYPE_COMPILER_NAMESPACE L'argument "espace de noms" permet de modifier 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 décrite dans l'URI, par exemple, MyModule pour un module avec l'URI 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é dans un espace de noms personnalisé, où les différents sous-espaces de noms doivent être séparés par un ": :", par exemple "MyNamespace::MySubnamespace" pour l'espace de noms MySubnamespace qui se trouve à l'intérieur de MyNamespace. Hormis le ": :", les règles de dénomination des espaces de noms C++ s'appliquent.

QMLTC_QMLTC_EXPORT_DIRECTIVE doit être utilisé avec QMLTC_EXPORT_FILE_NAME lorsque les classes générées par qmltc doivent être exportées de la bibliothèque qml. Par défaut, les classes générées par qmltc ne sont pas exportées de leur bibliothèque. L'en-tête définissant la macro d'exportation pour la bibliothèque actuelle peut être spécifié en tant qu'argument facultatif à QMLTC_EXPORT_FILE_NAME tandis que le nom de la macro d'exportation doit être spécifié en tant qu'argument à QMLTC_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 incluse par une classe de base, l'option QMLTC_EXPORT_FILE_NAME peut être laissée de côté.