Intégration de l'ensemble avec CMake

La commande CMake `qt_add_qml_module ` est la méthode recommandée pour définir des modules QML. Elle automatise l'enregistrement des types, l'intégration des ressources, la création de plugins et l'intégration des outils. Cette page explique les concepts sous-jacents à ` qt_add_qml_module ` et présente les cas d'utilisation courants.

Pour une référence complète de toutes les options, consultez qt_add_qml_module.

Concepts clés

Avant d’examiner les exemples, il est utile de comprendre ce que qt_add_qml_module crée réellement :

• Une cible de support — une bibliothèque (ou un exécutable) contenant le code C++ du module, les fichiers QML compilés et les ressources. Il s’agit du premier argument de ` qt_add_qml_module ` et c’est la cible à laquelle vous effectuez la liaison. Il peut s’agir soit d’une cible existante (créée précédemment avec ` qt_add_executable ` ou ` qt_add_library`), soit d’une cible que ` qt_add_qml_module ` créera pour vous.
• Une cible « plugin »: une petite bibliothèque qui permet au moteur QML de charger le module de manière dynamique lors de l’exécution. Elle est créée automatiquement et est distincte de la cible « backing ». Lorsqu’un exécutable est lié directement à la cible « backing », le plugin n’est pas chargé lors de l’exécution. Le plugin peut être entièrement omis à l’aide de NO_PLUGIN.
• Un fichier qmldir — un fichier de métadonnées du module qui indique au moteur QML quels types le module fournit et où les trouver. Il est généré automatiquement.
• Un fichier typeinfo (.qmltypes) — des informations de type lisibles par machine utilisées par les outils QML (qmlcachegen, qmllint, qmlls, Qt Creator). Également généré automatiquement.

Structure des répertoires

La structure du répertoire source doit refléter l’URI du module. L’URI est converti en chemin d’accès en remplaçant les points par des barres obliques. Par exemple, un module dont l’URI est MyCompany.Controls doit se trouver dans :

src/MyCompany/Controls/CMakeLists.txt
src/MyCompany/Controls/Button.qml
src/MyCompany/Controls/mywidget.cpp
src/MyCompany/Controls/mywidget.h

Cette convention permet au moteur QML et aux outils de localiser les modules sans configuration supplémentaire. Si votre structure de répertoires ne correspond pas à l’URI, vous devrez définir OUTPUT_DIRECTORY afin que le résultat de la compilation soit placé dans un chemin correspondant à l’URI, et IMPORT_PATH afin que le moteur QML et les outils puissent localiser le module.

Modèles courants

Application exclusivement en QML

Le cas le plus simple : un exécutable contenant uniquement des fichiers QML et aucun type C++.

cmake_minimum_required(VERSION 3.16)
project(myapp LANGUAGES CXX)

find_package(Qt6 REQUIRED COMPONENTS Quick)
qt_standard_project_setup(REQUIRES 6.8)

qt_add_executable(myapp)
qt_add_qml_module(myapp
    URI MyApp
    QML_FILES
        Main.qml
        Button.qml
    RESOURCES
        images/logo.png
)

target_link_libraries(myapp PRIVATE Qt6::Quick)

La cible sous-jacente étant un exécutable, aucun plugin n’est créé. Les fichiers QML sont compilés et intégrés en tant que ressources. Le mot-clé ` RESOURCES ` ajoute les fichiers non-QML (images, polices, etc.) à la même hiérarchie de ressources.

Application avec des types C++

Une application qui expose des types C++ à QML :

qt_add_executable(myapp)
qt_add_qml_module(myapp
    URI MyApp
    QML_FILES
        Main.qml
    SOURCES
        backend.cpp backend.h
)

Les types C++ dans ` backend.h ` doivent être annotés avec ` QML_ELEMENT ` (ou des macros similaires telles que ` QML_NAMED_ELEMENT`) et doivent utiliser la macro ` Q_OBJECT ` ou ` Q_GADGET `. L’enregistrement des types s’effectue automatiquement via ` AUTOMOC`. Consultez la section « Enregistrement des types C++ avec le système de types QML » pour un aperçu complet des macros d’enregistrement disponibles.

Module de bibliothèque réutilisable

Un module QML packagé sous forme de bibliothèque que d’autres projets ou modules peuvent importer :

# In src/MyCompany/Controls/CMakeLists.txt
qt_add_qml_module(mycontrols
    URI MyCompany.Controls
    QML_FILES
        Button.qml
        Slider.qml
    SOURCES
        theme.cpp theme.h
)

Cela crée deux cibles : mycontrols (la bibliothèque de base) et mycontrolsplugin (le plugin). Les autres modules l’importent à l’aide de ` import MyCompany.Controls ` en QML. Les applications qui se lient directement à ` mycontrols ` n’ont pas besoin de charger le plugin au moment de l’exécution.

Application utilisant un module de bibliothèque

Utilisation du module mycontrols issu de l’exemple de module de bibliothèque réutilisable ci-dessus :

# In the application's CMakeLists.txt
qt_add_executable(myapp)
qt_add_qml_module(myapp
    URI MyApp
    QML_FILES Main.qml
    DEPENDENCIES TARGET mycontrols
)

target_link_libraries(myapp PRIVATE mycontrols)

La ligne DEPENDENCIES garantit que les outils QML (qmlcachegen, qmllint, qmlls) peuvent trouver les types fournis par MyCompany.Controls.

// In Main.qml
import MyCompany.Controls

Button { text: "Click me" }

Module avec des singletons

Les fichiers QML fournissant des types singleton nécessitent qu’une propriété de fichier source soit définie avant l’appel à ` qt_add_qml_module ` :

set_source_files_properties(Theme.qml PROPERTIES QT_QML_SINGLETON_TYPE TRUE)

qt_add_qml_module(mymodule
    URI MyModule
    QML_FILES
        Theme.qml
        Main.qml
)

Le fichier QML doit également contenir pragma Singleton. La propriété CMake et le pragma QML sont tous deux obligatoires.

Module avec plugin personnalisé

Lorsque vous devez effectuer une initialisation personnalisée (par exemple, l’enregistrement d’un fournisseur d’images), vous pouvez fournir votre propre sous-classe de ` QQmlEngineExtensionPlugin `.

# In CMakeLists.txt
qt_add_qml_module(mymodule
    URI MyModule
    NO_GENERATE_PLUGIN_SOURCE
    NO_PLUGIN_OPTIONAL
    CLASS_NAME MyModulePlugin
    QML_FILES
        Main.qml
    SOURCES
        myimageprovider.cpp myimageprovider.h
)

# Add the custom plugin source to the plugin target
target_sources(mymoduleplugin PRIVATE plugin.cpp)

// In plugin.cpp
#include <QtQml/QQmlEngineExtensionPlugin>
#include "myimageprovider.h"

class MyModulePlugin : public QQmlEngineExtensionPlugin
{
    Q_OBJECT
    Q_PLUGIN_METADATA(IID QQmlEngineExtensionInterface_iid)
public:
    void initializeEngine(QQmlEngine *engine, const char *uri) override
    {
        engine->addImageProvider("myprovider", new MyImageProvider);
    }
};

#include "plugin.moc"

NO_GENERATE_PLUGIN_SOURCE indique au système de compilation de ne pas générer le code source par défaut du plugin. CLASS_NAME doit correspondre au nom de la classe dans votre implémentation. NO_PLUGIN_OPTIONAL garantit que le plugin est toujours chargé, car il contient une logique d’initialisation qui serait sinon ignorée.

Ajout de fichiers QML supplémentaires

Pour les fichiers QML ajoutés après l’appel initial à ` qt_add_qml_module `, utilisez ` qt_target_qml_sources` :

qt_target_qml_sources(my_qml_module
    QML_FILES
        DynamicallyAddedType.qml
)

Cela est utile pour inclure des fichiers de manière conditionnelle en fonction de la plateforme ou de la configuration.

Référence détaillée de CMake

Pour plus de détails sur toutes les commandes, propriétés, variables et politiques CMake, consultez la section Intégration de CMake pour QML.