qt_add_qml_module

Definiert ein QML-Modul.

Dieser Befehl wurde in Qt 6.2 eingeführt.

Der Befehl ist in der Komponente „ Qml “ des Pakets „ Qt6 “ definiert, das wie folgt geladen werden kann:

find_package(Qt6 REQUIRED COMPONENTS Qml)

Übersicht

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]

)

Wenn versionlose Befehle deaktiviert sind, verwenden Sie stattdessen „ qt6_add_qml_module() “. Dieser Befehl unterstützt dieselben Argumente wie der vorliegende Befehl.

Beispiele für die Definition von QML-Modulen finden Sie unter „Erstellen einer QML-Anwendung “ und „Erstellen eines wiederverwendbaren QML-Moduls “.

Beschreibung

Dieser Befehl definiert ein QML-Modul, das aus C++-Quelldateien, „ .qml “-Dateien oder beidem bestehen kann. Er stellt sicher, dass wesentliche Modulangaben vorhanden und konsistent sind. Außerdem richtet er Funktionen wie die zwischengespeicherte Kompilierung von „ .qml “-Quelldateien, die Einbettung von Ressourcen, Linting-Prüfungen und die automatische Generierung einiger wichtiger Moduldateien ein und koordiniert diese.

Einen konzeptionellen Überblick mit gängigen Anwendungsbeispielen finden Sie unter „Alles mit CMake zusammenführen“. Informationen zu fortgeschrittenen Themen wie benutzerdefinierten Verzeichnisstrukturen und Versionierung finden Sie unter „QML-Module schreiben“.

Zielstruktur

Ein QML-Modul kann auf verschiedene Arten strukturiert werden. Die folgenden Szenarien stellen typische Anordnungen dar:

Getrennte Backing- und Plugin-Ziele

Dies ist die empfohlene Anordnung für die meisten QML-Module. Die gesamte Funktionalität des Moduls wird im Backing-Target implementiert, das als erstes Befehlsargument angegeben wird. C++-Quelldateien, „ .qml “-Dateien und Ressourcen sollten alle dem Backing-Target hinzugefügt werden. Das Backing-Target ist eine Bibliothek, die am selben Speicherort wie alle anderen vom Projekt definierten Bibliotheken installiert werden sollte.

Die Quellverzeichnisstruktur, unter der das Backing-Ziel erstellt wird, sollte mit dem Zielpfad des QML-Moduls übereinstimmen (der Zielpfad ist die URI des Moduls, wobei Punkte durch Schrägstriche ersetzt werden). Wenn die Quellverzeichnisstruktur nicht mit dem Zielpfad übereinstimmt, gibt „ qt_add_qml_module() “ eine Warnung aus.

Das folgende Beispiel zeigt eine geeignete Quellverzeichnisstruktur für ein QML-Modul mit der URI MyThings.Panels. Der Aufruf von qt_add_qml_module() würde in der gezeigten Datei „ CMakeLists.txt “ erfolgen.

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

Dem QML-Modul ist ein separates Plugin-Ziel zugeordnet. Es wird zur Laufzeit verwendet, um das Modul dynamisch zu laden, wenn die Anwendung noch keine Verknüpfung zum zugrunde liegenden Ziel hergestellt hat. Das Plugin-Ziel ist ebenfalls eine Bibliothek und wird normalerweise im selben Verzeichnis wie die `qmldir` -Datei des Moduls installiert.

Das Plugin-Ziel sollte im Idealfall nichts weiter als eine triviale Implementierung der Plugin-Klasse enthalten. Dadurch kann das Plugin in der Datei „ qmldir “ als optional gekennzeichnet werden. Andere Ziele können dann direkt mit dem zugrunde liegenden Ziel verknüpft werden, und das Plugin wird zur Laufzeit nicht benötigt, was die Leistung beim Laden verbessern kann. Standardmäßig wird eine C++-Quelldatei, die eine minimale Plugin-Klasse definiert, automatisch generiert und dem Plugin-Ziel hinzugefügt. In Fällen, in denen das QML-Modul eine benutzerdefinierte Plugin-Klassenimplementierung benötigt, sind die Optionen `NO_GENERATE_PLUGIN_SOURCE` und in der Regel auch ` NO_PLUGIN_OPTIONAL ` erforderlich.

Die QML-Module „ STATIC “ generieren zudem die statischen QML-Plugins, sofern „ NO_PLUGIN “ nicht angegeben ist. Ziele, die solche „ STATIC “-QML-Module importieren, müssen zudem explizit auf die entsprechenden QML-Plugins verweisen.

Plugin-Ziel ohne zugrunde liegendes Ziel

Ein QML-Modul kann so definiert werden, dass das Plugin-Ziel als sein eigenes Backing-Ziel dient. In diesem Fall muss das Modul zur Laufzeit dynamisch geladen werden und kann nicht direkt von anderen Zielen verknüpft werden. Um diese Konfiguration zu erstellen, muss das Schlüsselwort „ PLUGIN_TARGET “ verwendet werden, wobei „ target “ als Name des Plugin-Ziels wiederholt wird. Beispiel:

qt_add_qml_module(someTarget
    PLUGIN_TARGET someTarget
    ...
)

Auch wenn diese Konfiguration auf den ersten Blick etwas einfacher zu implementieren scheint, sollte nach Möglichkeit ein separates Backing-Ziel bevorzugt werden, da dies potenziell eine bessere Leistung bei der Ladezeit bietet.

Als QML-Modul ausführbar

Ein ausführbares Ziel kann als Backing-Ziel für ein QML-Modul dienen. In diesem Fall gibt es keine Plugin-Bibliothek, da das QML-Modul immer direkt als Teil der Anwendung geladen wird. Der Befehl „ qt_add_qml_module() “ erkennt, wenn eine ausführbare Datei als Backing-Ziel verwendet wird, und deaktiviert automatisch die Erstellung eines separaten Plugins. Verwenden Sie bei dieser Konfiguration keine der Optionen, deren Name „ PLUGIN “ enthält.

Wenn eine ausführbare Datei als zugrunde liegendes Ziel verwendet wird, wird nicht erwartet, dass die Quellverzeichnisstruktur mit dem Zielpfad des QML-Moduls übereinstimmt. Weitere Unterschiede beim Zielpfad für kompilierte Ressourcen finden Sie unter „Zwischenspeichern kompilierter QML-Quellen “.

Automatische Generierung von „ qmldir “- und „typeinfo“-Dateien

Standardmäßig werden für das zu definierende QML-Modul eine „qmldir“-Datei und eine „typeinfo“-Datei automatisch generiert. Der Inhalt dieser Dateien wird durch die verschiedenen Argumente dieses Befehls sowie durch die dem zugrunde liegenden Ziel hinzugefügten Quell- und „ .qml “-Dateien bestimmt. Das Argument OUTPUT_DIRECTORY legt fest, wohin die Dateien „ qmldir “ und „typeinfo“ geschrieben werden. Verfügt das QML-Modul über ein Plugin, wird dieses ebenfalls im selben Verzeichnis wie die Datei „ qmldir “ erstellt.

Wenn die Richtlinie „QTP0004“ auf „ NEW “ gesetzt ist, wird für jedes weitere Verzeichnis, das „ .qml “-Dateien enthält, eine weitere „ qmldir “-Datei generiert. Diese zusätzlichen „ qmldir “-Dateien leiten lediglich über eine „ prefer “-Anweisung zum Basisverzeichnis des Moduls weiter. Dies geschieht, damit alle QML-Komponenten in einem Modul aufeinander zugreifen können, unabhängig davon, in welchem Verzeichnis sie gespeichert sind.

Bei Verwendung eines statisch kompilierten Qt werden die „ .qml “-Dateien des zugrunde liegenden Ziels während des CMake-Konfigurationslaufs gescannt, um die vom Modul verwendeten Importe zu ermitteln und Verknüpfungsbeziehungen einzurichten (das Schlüsselwort „ NO_IMPORT_SCAN “ kann angegeben werden, um dies zu deaktivieren). Wenn eine „ .qml “-Datei zum Modul hinzugefügt oder daraus entfernt wird, wird CMake normalerweise automatisch neu ausgeführt und die entsprechenden Dateien werden erneut gescannt, da eine „ CMakeLists.txt “-Datei geändert wurde. Im Laufe der Entwicklung kann es vorkommen, dass in einer bestehenden „ .qml “-Datei ein Import oder ein Typ hinzugefügt oder entfernt wird. Dies allein würde nicht dazu führen, dass CMake automatisch erneut ausgeführt wird. Daher sollten Sie CMake explizit erneut ausführen, um die Neugenerierung der „ qmldir “-Datei und die Aktualisierung aller Verknüpfungsbeziehungen zu erzwingen.

Die C++-Quelldateien des zugrunde liegenden Ziels werden zum Zeitpunkt der Erstellung gescannt, um eine „typeinfo“-Datei und eine C++-Datei zur Registrierung der zugehörigen Typen zu generieren. Die generierte C++-Datei wird dem zugrunde liegenden Ziel automatisch als Quelldatei hinzugefügt. Dazu muss die Option „ AUTOMOC “ für das Ziel aktiviert sein. Das Projekt ist dafür verantwortlich, dies sicherzustellen, in der Regel durch Setzen der Variablen „ CMAKE_AUTOMOC “ auf „ TRUE “ vor dem Aufruf von „ qt_add_qml_module() “ oder durch Übergabe eines bestehenden Ziels, bei dem die Zieleigenschaft „ AUTOMOC “ bereits auf „ TRUE “ gesetzt ist. Es ist kein Fehler, wenn „ AUTOMOC “ auf dem Ziel deaktiviert ist, aber das Projekt ist dann für die Bewältigung der Folgen verantwortlich. Dies kann unter anderem bedeuten, dass die „typeinfo“-Datei manuell generiert werden muss, anstatt sie mit fehlenden Details automatisch generieren zu lassen, und dass C++-Code hinzugefügt werden muss, um die Typen zu registrieren.

Projekte sollten nach Möglichkeit die automatisch generierten „typeinfo“- und „ qmldir “-Dateien verwenden. Diese sind einfacher zu pflegen und nicht so fehleranfällig wie manuell erstellte Dateien. Für Fälle, in denen das Projekt diese Dateien jedoch selbst bereitstellen muss, kann die automatische Generierung deaktiviert werden. Die Option „ NO_GENERATE_QMLDIR “ deaktiviert die automatische Generierung von „ qmldir “, und die Option „ NO_GENERATE_QMLTYPES “ deaktiviert die automatische Generierung von „typeinfo“ sowie die C++-Typregistrierung. Wenn die automatisch generierte „typeinfo“-Datei akzeptabel ist, das Projekt jedoch einen anderen Namen für diese Datei verwenden möchte, kann der Standardname mit der Option „ TYPEINFO “ überschrieben werden (dies sollte jedoch in der Regel nicht erforderlich sein).

Zwischenspeicherung kompilierter QML-Quellen

Alle Dateien vom Typ „ .qml “, „ .js “ und „ .mjs “, die über das Argument „ QML_FILES “ zum Modul hinzugefügt werden, werden zu Bytecode kompiliert und direkt im zugrunde liegenden Ziel zwischengespeichert. Dies verbessert die Ladegeschwindigkeit des Moduls. Die ursprünglichen, nicht kompilierten Dateien werden ebenfalls in den Ressourcen des zugrunde liegenden Ziels gespeichert, da diese unter bestimmten Umständen von der QML-Engine noch benötigt werden können.

Der Ressourcenpfad jeder Datei wird durch ihren Pfad relativ zum aktuellen Quellverzeichnis (CMAKE_CURRENT_SOURCE_DIR) bestimmt. Dieser Ressourcenpfad wird an ein Präfix angehängt, das durch Verknüpfung von RESOURCE_PREFIX und dem Zielpfad gebildet wird (siehe jedoch NO_RESOURCE_TARGET_PATH für eine Ausnahme von dieser Regel).

Wenn die Richtlinie „QTP0001“ auf „ NEW “ gesetzt ist, wird „RESOURCE_PREFIX“ standardmäßig auf „ /qt/qml/ “ gesetzt, was dem Standard-Importpfad der QML-Engine entspricht. Dadurch wird sichergestellt, dass Module in den QML-Importpfad aufgenommen werden und ohne weitere Konfiguration gefunden werden können.

In der Regel sollte das Projekt darauf abzielen, „ .qml “-Dateien an derselben relativen Position zu platzieren, an der sie sich in den Ressourcen befinden würden. Befindet sich die „ .qml “-Datei in einem anderen relativen Verzeichnis als ihrem gewünschten Ressourcenpfad, muss ihr Speicherort in den Ressourcen explizit angegeben werden. Dies geschieht durch Festlegen der Eigenschaft „ QT_RESOURCE_ALIAS “ der Quelldatei, die vor dem Hinzufügen der „ .qml “-Datei festgelegt werden muss. Beispiel:

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
)

Im obigen Beispiel lautet der Zielpfad „ MyCo/Frames “. Unter Berücksichtigung der Eigenschaften der Quelldatei befinden sich die beiden „ .qml “-Dateien an den folgenden Ressourcenpfaden:

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

In dem seltenen Fall, dass Sie die automatische Auswahl des zu verwendenden Programms „qmlcachegen“ überschreiben möchten, können Sie die Ziel-Eigenschaft „ QT_QMLCACHEGEN_EXECUTABLE “ für das Modulziel festlegen. Zum Beispiel:

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_EXECUTABLE qmlcachegen
)

Dadurch wird „qmlcachegen“ explizit als zu verwendendes Programm ausgewählt, auch wenn bessere Alternativen verfügbar sind.

Darüber hinaus können Sie qmlcachegen zusätzliche Argumente übergeben, indem Sie die Option „ QT_QMLCACHEGEN_ARGUMENTS “ setzen. Insbesondere deaktiviert die Option „ --only-bytecode “ die Kompilierung von QML-Skriptcode in C++. Beispiel:

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

Ein weiteres wichtiges Argument ist „ --direct-calls “. Damit können Sie den Direktmodus des QML-Skript-Compilers aktivieren, sofern die Compiler-Erweiterungen „ Qt Quick “ installiert sind. Sind die Erweiterungen nicht installiert, wird das Argument ignoriert. Dafür gibt es die Kurzform „ QT_QMLCACHEGEN_DIRECT_CALLS “.

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_DIRECT_CALLS ON
)

Schließlich kann das Argument „ --verbose “ verwendet werden, um die Diagnoseausgabe von `qmlcachegen` anzuzeigen:

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_ARGUMENTS "--verbose"
)

Wenn dieses Flag gesetzt ist, gibt qmlcachegen Warnungen für jede Funktion aus, die es nicht in C++ kompilieren kann. Einige dieser Warnungen weisen auf Probleme in Ihrem QML-Code hin, andere weisen darauf hin, dass bestimmte Funktionen der QML-Sprache im C++-Codegenerator nicht implementiert sind. In beiden Fällen generiert `qmlcachegen` dennoch Bytecode für solche Funktionen. Wenn Sie ausschließlich die Probleme in Ihrem QML-Code anzeigen lassen möchten, sollten Sie stattdessen `qmllint` und die dafür generierten Ziele verwenden.

Überprüfung von QML-Quelltexten

Ein separates Linting-Ziel wird automatisch erstellt, wenn „ .qml “-Dateien über das Schlüsselwort „ QML_FILES “ oder durch einen späteren Aufruf von „qt_target_qml_sources()“ zum Modul hinzugefügt werden. Der Name des Linting-Ziels lautet „ target “, gefolgt von „ _qmllint “. Ein „ all_qmllint “-Ziel, das von allen einzelnen „ *_qmllint “-Zielen abhängt, wird ebenfalls als Erleichterung bereitgestellt.

Es wird automatisch ein globales Build-Ziel „ dump_qml_context_properties “ erstellt, das „qmlcontextpropertydump“ ausführt, wenn noch keine QML-Kontext-Eigenschafts-Dump-Datei vorhanden ist. „qmlcontextpropertydump“ erstellt eine QML-Kontext-Eigenschafts-Dump-Datei, die von „qmllint“ gelesen wird, um vor der Verwendung von Kontexteigenschaften in QML zu warnen.

Ein globales Build-Ziel „ clean_qml_context_properties “ ermöglicht das Löschen einer bereits vorhandenen QML-Kontext-Eigenschafts-Dump-Datei und kann verwendet werden, um die QML-Kontext-Eigenschafts-Dump-Datei bei einem zukünftigen Build des globalen Build-Ziels „ dump_qml_context_properties “ neu zu berechnen.

Linting-Ziele sind vom Build-Ziel „ dump_qml_context_properties “ abhängig, wenn die Variable „QT_QMLLINT_CONTEXT_PROPERTY_DUMP“ aktiviert ist.

Namenskonventionen für „ .js “-Dateien

JavaScript-Dateinamen, die als Komponenten behandelt werden sollen, sollten mit einem Großbuchstaben beginnen.

Alternativ können Sie Dateinamen in Kleinbuchstaben verwenden und die Quelldateieigenschaft ` QT_QML_SOURCE_TYPENAME ` auf den gewünschten Typnamen setzen.

Singletons

Wenn ein QML-Modul „ .qml “-Dateien enthält, die Singleton-Typen bereitstellen, muss für diese Dateien die Quell-Eigenschaft „ QT_QML_SINGLETON_TYPE “ auf „ TRUE “ gesetzt werden, um sicherzustellen, dass der Befehl „ singleton “ in die Datei „qmldir“ geschrieben wird. Dies muss zusätzlich zu der QML-Datei erfolgen, die die Anweisung „ pragma Singleton “ enthält. Die Quell-Eigenschaft muss vor dem Erstellen des Moduls gesetzt werden, zu dem das Singleton gehört.

Ein Beispiel für die Einstellung der Eigenschaft „ QT_QML_SINGLETON_TYPE “ finden Sie unter qt_target_qml_sources().

Kompilieren von QML nach C++ mit dem QML-Typ-Compiler

Wenn ein QML-Modul „ .qml “-Dateien enthält, können Sie diese mit qmltc in C++ kompilieren. Im Gegensatz zur Bytecode-Kompilierung müssen Sie qmltc explizit über das Argument `ENABLE_TYPE_COMPILER` aktivieren. In diesem Fall werden die unter ` QML_FILES ` angegebenen „ .qml “-Dateien kompiliert. Dateien mit den Endungen „ .js “ und „ .mjs “ werden ignoriert, da qmltc keinen JavaScript-Code kompiliert. Zudem werden Dateien übersprungen, die mit der Quelldateieigenschaft „QT_QML_SKIP_TYPE_COMPILER“ gekennzeichnet sind.

Standardmäßig erstellt qmltc für eine bestimmte „ .qml “-Datei die entsprechenden Dateien „ .h “ und „ .cpp “ in Kleinbuchstaben. So wird beispielsweise „ Foo.qml “ letztendlich zu „ foo.h “ und „ foo.cpp “ kompiliert.

Die erstellten C++-Dateien werden in einem eigenen Unterverzeichnis „ .qmltc/<target>/ “ des Verzeichnisses „ BINARY_DIR “ der Datei „ target “ abgelegt. Diese Dateien werden dann automatisch zu den Zielquelldateien hinzugefügt und zusammen mit anderen Quelldateien als Qt-C++-Code kompiliert.

Bei der Verarbeitung von QML_FILES werden die folgenden Eigenschaften der Quelldateien berücksichtigt:

• QT_QMLTC_FILE_BASENAME: Verwenden Sie diese Eigenschaft der Quelldatei, um einen vom Standard abweichenden .h- und .cpp-Dateinamen anzugeben. Dies kann beispielsweise nützlich sein, um Konflikte bei Dateinamen zu lösen (stellen Sie sich vor, Sie haben eine main.qml, die kompiliert wird, aber main.h existiert bereits, sodass #include "main.h" möglicherweise nicht das gewünschte Ergebnis liefert). Es wird erwartet, dass „QT_QMLTC_FILE_BASENAME“ ein Dateiname (ohne Erweiterung) ist, daher wird ein vorangestelltes Verzeichnis ignoriert. Anders als beim Standardverhalten wird „QT_QMLTC_FILE_BASENAME“ nicht in Kleinbuchstaben umgewandelt.
• QT_QML_SKIP_TYPE_COMPILER: Verwenden Sie diese Quelldateieigenschaft, um festzulegen, dass eine QML-Datei von qmltc ignoriert werden soll.

Argumente

Die Argumente für ` qt_add_qml_module ` sind in die folgenden Kategorien unterteilt:

Erforderliche Argumente

Das Argument „ target “ gibt den Namen des zugrunde liegenden Ziels für das QML-Modul an. Standardmäßig wird es als gemeinsam genutzte Bibliothek erstellt, wenn Qt als gemeinsam genutzte Bibliotheken kompiliert wurde, andernfalls als statische Bibliothek. Diese Wahl kann explizit mit den Optionen „ STATIC “ oder „ SHARED “ überschrieben werden.

Jedes QML-Modul muss einen ` URI` definieren. Dieser sollte in der gepunkteten URI-Notation angegeben werden, beispielsweise ` QtQuick.Layouts`. Jedes Segment muss ein wohlgeformter ECMAScript-Bezeichnername sein. Das bedeutet beispielsweise, dass die Segmente nicht mit einer Zahl beginnen dürfen und keine Minuszeichen ( - ) enthalten dürfen. Da der „ URI “ in Verzeichnisnamen übersetzt wird, sollten Sie ihn auf alphanumerische Zeichen des lateinischen Alphabets, Unterstriche und Punkte beschränken. Andere QML-Module können diesen Namen in Importanweisungen verwenden, um das Modul zu importieren. Der „ URI “ wird in der Zeile „ module “ der generierten qmldir-Datei verwendet. Der „ URI “ wird ebenfalls zur Bildung des Zielpfads verwendet, indem Punkte durch Schrägstriche ersetzt werden.

Eine ausführlichere Erörterung der Modul-URI finden Sie unter „Identifizierte Module “.

Versionen

Ein QML-Modul kann auch eine Versionsnummer ( VERSION ) in der Form „ Major.Minor “ definieren, wobei sowohl „ Major “ als auch „ Minor “ Ganzzahlen sein müssen. Ein zusätzlicher Teil „ .Patch “ kann angehängt werden, wird jedoch ignoriert. Optional kann nach dem Schlüsselwort „ PAST_MAJOR_VERSIONS “ eine Liste früherer Hauptversionen angegeben werden, für die das Modul Typen bereitstellt (siehe unten). Weitere ausführliche Informationen zur Versionsnummerierung finden Sie unter „Identifizierte Module“, zur Registrierung früherer Hauptversionen unter „Registrierung früherer Hauptversionen“ und zur Synchronisierung von Modulversionen unter „Synchronisierung von Modulversionen“.

Wenn Sie keine Versionsangaben benötigen, sollten Sie das Argument „ VERSION “ weglassen. Standardmäßig wird die höchstmögliche Version verwendet. Die interne Versionierung von QML-Modulen weist einige grundlegende Mängel auf. Sie sollten einen externen Paketverwaltungsmechanismus verwenden, um verschiedene Versionen Ihrer QML-Module zu verwalten.

Hinzufügen von Quellen und Ressourcen zum Modul

SOURCES gibt eine Liste von Nicht-QML-Quelldateien an, die dem „backing“-Ziel hinzugefügt werden sollen. Diese Option dient der Vereinfachung und entspricht dem Hinzufügen der Quelldateien zum „backing“-Ziel mit dem integrierten CMake-Befehl „ target_sources() “.

QML_FILES listet die Dateien „ .qml “, „ .js “ und „ .mjs “ für das Modul auf. Diese werden automatisch zu Bytecode kompiliert und in das Backing-Target eingebettet, sofern nicht die Option „ NO_CACHEGEN “ angegeben ist. Die unkompilierte Datei wird immer in den eingebetteten Ressourcen des Backing-Targets gespeichert, selbst wenn „ NO_CACHEGEN “ angegeben ist. Sofern nicht die Option „ NO_LINT “ angegeben ist, werden die unkompilierten Dateien zudem von „ qmllint “ über ein separates benutzerdefiniertes Build-Target verarbeitet. Die Dateien werden standardmäßig auch verwendet, um Typinformationen in die generierte „qmldir“-Datei einzufügen. Mit der Option „ NO_GENERATE_QMLDIR “ kann die automatische Generierung der „ qmldir “-Datei deaktiviert werden. Dies sollte normalerweise vermieden werden, aber in Fällen, in denen das Projekt eine eigene „ qmldir “-Datei bereitstellen muss, kann diese Option verwendet werden. Seit Qt 6.8 erstellt „ qt_add_qml_module “ bei aktivierter Option „QTP0004“ für jedes Unterverzeichnis im QML-Modul zusätzliche „ qmldir “-Dateien, die sicherstellen, dass jede QML-Datei ihr eigenes Modul über den impliziten Import einbindet. Dieses Verhalten kann für ein QML-Modul deaktiviert werden, indem das Flag „ NO_GENERATE_EXTRA_QMLDIRS “ übergeben wird. „ NO_GENERATE_QMLDIR “ impliziert „ NO_GENERATE_EXTRA_QMLDIRS “.

RESOURCES listet alle weiteren vom Modul benötigten Dateien auf, wie z. B. Bilder, auf die im QML-Code verwiesen wird. Diese Dateien werden als kompilierte Ressourcen hinzugefügt (siehe RESOURCE_PREFIX für eine Erläuterung des Basisverzeichnisses, unter dem sie abgelegt werden). Bei Bedarf lässt sich ihr relativer Speicherort durch Setzen der Quelleneigenschaft „ QT_RESOURCE_ALIAS “ steuern, genau wie bei „ .qml “-Dateien (siehe „Zwischenspeichern kompilierter QML-Quellen“).

RESOURCE_PREFIX soll einen Namensraum für das Projekt kapseln und ist häufig für alle vom Projekt definierten QML-Module identisch.

Es ist jedoch besser, stattdessen die CMake-Richtlinie „QTP0001“ festzulegen. Diese definiert ein Standard-Ressourcenpräfix, das sicherstellt, dass Ihr QML-Modul unter einem der Standard-Importpfade der QML-Engine abgelegt wird.

Wenn Sie „ RESOURCE_PREFIX “ festlegen, sollten Sie diesen auch zu den Importpfaden hinzufügen, damit die QML-Engine das QML-Modul finden kann.

Wenn QTP0001 aktiviert ist (z. B. über ` qt_standard_project_setup(REQUIRES 6.5)`), lautet der Standardwert ` "/qt/qml/"`, andernfalls ` "/"`.

Wenn verschiedene Dateien zu den kompilierten Ressourcen hinzugefügt werden, werden sie unter einem Pfad abgelegt, der sich aus der Verkettung von „ RESOURCE_PREFIX “ und dem Zielpfad ergibt. Für den Sonderfall, in dem das zugrunde liegende Ziel eine ausführbare Datei ist, kann es wünschenswert sein, die „ .qml “-Dateien des Moduls und andere Ressourcen stattdessen direkt unter dem „ RESOURCE_PREFIX “ abzulegen. Dies lässt sich durch die Angabe der Option „ NO_RESOURCE_TARGET_PATH “ erreichen, die jedoch nur verwendet werden darf, wenn das zugrunde liegende Ziel eine ausführbare Datei ist.

Registrierung früherer Hauptversionen

PAST_MAJOR_VERSIONS enthält eine Liste zusätzlicher Hauptversionen, die das Modul bereitstellt. Für jede dieser Versionen und jede QML-Datei ohne die Einstellung „ QT_QML_SOURCE_VERSIONS “ wird ein zusätzlicher Eintrag in der Datei „qmldir“ generiert, um die zusätzliche Version anzugeben. Darüber hinaus registriert der generierte Modulregistrierungscode die früheren Hauptversionen auf der C++-Seite mithilfe von ` qmlRegisterModule()`. Der Modulregistrierungscode wird automatisch für Ihr QML-Modul generiert, es sei denn, Sie geben „ NO_GENERATE_QMLTYPES “ an (von der Verwendung dieser Option wird jedoch dringend abgeraten). Die Verwendung von „ PAST_MAJOR_VERSIONS “ verursacht beim Import Ihres Moduls einen gewissen Mehraufwand. Sie sollten die Hauptversion Ihres Moduls so selten wie möglich erhöhen. Sobald Sie sich darauf verlassen können, dass alle QML-Dateien, die dieses Modul importieren, die Versionsangabe in ihren Importanweisungen weglassen, können Sie PAST_MAJOR_VERSIONS getrost weglassen. Alle QML-Dateien importieren dann die neueste Version Ihres Moduls. Wenn Sie versionierte Importe unterstützen müssen, sollten Sie in Erwägung ziehen, nur eine begrenzte Anzahl früherer Hauptversionen zu unterstützen.

Modulabhängigkeiten deklarieren

IMPORTS enthält eine Liste anderer QML-Module, die dieses Modul importiert. Jedes hier aufgeführte Modul wird als Eintrag „ import “ in die generierte qmldir-Datei aufgenommen. Wenn eine QML-Datei dieses Modul importiert, importiert sie auch alle unter „ IMPORTS “ aufgeführten Module. Optional kann eine Version angegeben werden, indem sie nach einem Schrägstrich angehängt wird, z. B. QtQuick/2.0. Wird die Version weggelassen, wird die höchste verfügbare Version importiert. Sie können auch nur die Hauptversion angeben, wie in QtQuick/2. In diesem Fall wird die höchste verfügbare Nebenversion der angegebenen Hauptversion importiert. Schließlich kann „ auto “ als Version angegeben werden (z. B.QtQuick/auto). Wird „ auto “ angegeben, wird die Version, mit der das aktuelle Modul importiert wird, auf das zu importierende Modul übertragen. Bei einem Eintrag „ QtQuick/auto “ im Modul „ YourModule “ führt die Angabe „ import YourModule 3.14 “ in einer QML-Datei dazu, dass die Version „ 3.14 “ von „ QtQuick “ importiert wird. Für verwandte Module, die einem gemeinsamen Versionsschema folgen, sollten Sie „ auto “ verwenden.

Einträge in „ IMPORTS “ können auch auf CMake-Ziele verweisen, indem dem Zielnamen das Schlüsselwort „ TARGET “ vorangestellt wird. In diesem Fall wird die QML-Modul-URI automatisch aus dem Ziel ermittelt. Dies setzt die Aktivierung der CMake-Richtlinie QTP0005 voraus.

Beispielsweise kann ein QML-Modul ein anderes Modul importieren, indem es auf das CMake-Ziel verweist, das dieses bereitstellt:

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    IMPORTS
        TARGET OtherQmlModule
)

OPTIONAL_IMPORTS stellt eine Liste anderer QML-Module bereit, die dieses Modul zur Laufzeit importieren kann. Diese werden beim Import des aktuellen Moduls nicht automatisch von der QML-Engine importiert, sondern dienen vielmehr als Hinweise für Tools wie qmllint. Versionen können auf dieselbe Weise wie bei „ IMPORTS “ angegeben werden. Jedes hier aufgeführte Modul wird als Eintrag „ optional import “ in die generierte qmldir-Datei aufgenommen.

Einträge in OPTIONAL_IMPORTS können sich auch auf CMake-Ziele beziehen, indem dem Zielnamen das Schlüsselwort TARGET vorangestellt wird. In diesem Fall wird die QML-Modul-URI automatisch aus dem Ziel ermittelt. Dies erfordert die Aktivierung der CMake-Richtlinie QTP0005.

Beispiel:

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    OPTIONAL_IMPORTS
        TARGET OptionalQmlModule
)

DEFAULT_IMPORTS legt fest, welche der optionalen Importe die Standardeinträge sind, die von den Tools geladen werden sollen. Für jede Gruppe von „ OPTIONAL_IMPORTS “ im Modul sollte ein Eintrag angegeben werden. Da optionale Importe erst zur Laufzeit aufgelöst werden, können Tools wie qmllint im Allgemeinen nicht wissen, welche der optionalen Importe aufgelöst werden sollen. Um dies zu beheben, können Sie einen der optionalen Importe als Standardimport festlegen; das Tool wählt diesen dann aus. Wenn Sie einen optionalen Import haben, der zur Laufzeit ohne weitere Konfiguration verwendet wird, ist dies ein idealer Kandidat für den Standardimport.

Einträge in ` DEFAULT_IMPORTS ` können sich auch auf CMake-Ziele beziehen, indem dem Zielnamen das Schlüsselwort ` TARGET ` vorangestellt wird. In diesem Fall wird die URI des QML-Moduls automatisch aus dem Ziel ermittelt. Dies erfordert die Aktivierung der CMake-Richtlinie QTP0005.

Beispiel:

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

DEPENDENCIES liefert eine Liste weiterer QML-Module, von denen dieses Modul abhängt, die es jedoch nicht unbedingt importiert. Dies wird typischerweise für Abhängigkeiten verwendet, die nur auf C++-Ebene bestehen, wie beispielsweise bei einem Modul, das eine Klasse bei QML registriert, die in einem anderen Modul definierte C++-Typen verwendet oder von diesen erbt.

Wenn man beispielsweise wie folgt eine Unterklasse von ` QQuickItem ` erstellen möchte:

class MyItem: public QQuickItem { ... };

dann muss sichergestellt werden, dass das Modul, das „ QQuickItem “ enthält – nämlich „ QtQuick “ –, über die Option „ DEPENDENCIES “ als Abhängigkeit deklariert wird:

qt_add_qml_module(myTarget
    ...
    DEPENDENCIES QtQuick
)

Andernfalls kann es zu Linting-Fehlern, Fehlern bei der Typkompilierung mit `qmltc` oder bei der Bindung und der Kompilierung von Funktionen nach C++ mit `qmlcachegen` kommen.

Ein weiteres Beispiel könnte sein:

class MyComponent : public QObject {
    Q_OBJECT
    QML_ELEMENT

    // ...

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

wobei „ DEPENDENCIES QtQml “ erforderlich ist, damit die QML-Tools „ QPointF “ finden und verwenden können:

qt_add_qml_module(myTarget
    ...
    DEPENDENCIES QtQml
)

Einträge in „ DEPENDENCIES “ können auch auf CMake-Ziele verweisen, indem dem Zielnamen das Schlüsselwort „ TARGET “ vorangestellt wird. In diesem Fall werden die URI des QML-Moduls und der Importpfad automatisch anhand des Ziels ermittelt. Dies erfordert die Aktivierung der CMake-Richtlinie QTP0005.

Beispielsweise kann ein QML-Modul eine Abhängigkeit von einem anderen Modul deklarieren, indem es auf das CMake-Ziel verweist, das dieses bereitstellt:

qt_add_qml_module(my_module
    URI MyModule
    VERSION 1.0
    DEPENDENCIES
        TARGET OtherQmlModule
)

Wenn das zugrunde liegende Ziel eine ausführbare Datei ist und „ TARGET “-Abhängigkeiten verwendet werden (erfordert QTP0005), generiert „ qt_add_qml_module() “ automatisch eine „ qt.conf “-Datei neben der ausführbaren Datei im Build-Baum. Diese Datei konfiguriert den QML-Importpfad so, dass die QML-Engine die Abhängigkeiten des Moduls zur Laufzeit finden kann, ohne dass manuelle „ IMPORT_PATH “-Einträge erforderlich sind. Die Option „ NO_GENERATE_QTCONF “ unterdrückt dieses Verhalten, was erforderlich sein kann, wenn die generierte Datei mit einer bereits im Build-Verzeichnis vorhandenen Datei „ qt.conf “ in Konflikt steht. Diese Option wurde in Qt 6.12 eingeführt.

Die Modulversion der Abhängigkeiten muss zusammen mit dem Modulnamen angegeben werden, und zwar in derselben Form, wie sie für „ IMPORTS “ und „ OPTIONAL_IMPORTS “ verwendet wird. Jedes hier aufgeführte Modul wird als Eintrag „ depends “ in die generierte qmldir-Datei aufgenommen.

IMPORT_PATH kann verwendet werden, um den Suchpfaden weitere Pfade hinzuzufügen, in denen andere QML-Module zu finden sind, von denen dieses Modul abhängt. Die anderen Module müssen ihre ` qmldir `-Datei unter ihrem eigenen Zielpfad unterhalb eines der Suchpfade haben. Qt geht davon aus, dass alle Dateien unter ` IMPORT_PATH ` aus einer vertrauenswürdigen Quelle stammen.

Wenn das zugrunde liegende Ziel eine statische Bibliothek ist und diese statische Bibliothek installiert werden soll, sollte „ OUTPUT_TARGETS “ angegeben werden, um eine Variable bereitzustellen, in der eine Liste zusätzlicher Ziele gespeichert wird, die ebenfalls installiert werden müssen. Diese zusätzlichen Ziele werden intern von „ qt_add_qml_module() “ generiert und werden von den Verknüpfungsanforderungen des zugrunde liegenden Ziels referenziert, um sicherzustellen, dass Ressourcen korrekt eingerichtet und geladen werden.

Ziele und Plugin-Ziele

Die folgenden Optionen steuern, wie das Plugin-Ziel erstellt und konfiguriert wird. Für die meisten Module sind die Standardeinstellungen angemessen, sodass keine dieser Optionen erforderlich ist. Häufige Szenarien:

• Standard — Es wird automatisch ein separates Plugin-Ziel mit einer generierten Quelldatei erstellt. Das Plugin ist optional (es wird nicht geladen, wenn die zugrunde liegende Bibliothek direkt verknüpft wird).
• Benutzerdefiniertes Plugin – Verwenden Sie NO_GENERATE_PLUGIN_SOURCE, um eine eigene Implementierung der Plugin-Klasse bereitzustellen. Sie sollten außerdem CLASS_NAME so einstellen, dass er mit Ihrer benutzerdefinierten Plugin-Klasse übereinstimmt. In der Regel ist zusätzlich NO_PLUGIN_OPTIONAL erforderlich, da das Plugin dann nicht-trivialen Code enthält.
• Kein Plugin – Verwenden Sie NO_PLUGIN, wenn das Modul immer direkt verknüpft und niemals dynamisch geladen wird.
• Ausführbares Ziel – es wird kein Plugin automatisch erstellt.

PLUGIN_TARGET Gibt das mit dem QML-Modul verknüpfte Plugin-Ziel an. Das „ PLUGIN_TARGET “ kann mit dem Backing- target übereinstimmen; in diesem Fall gibt es kein separates Backing-Ziel. Wenn „ PLUGIN_TARGET “ nicht angegeben wird, lautet der Standardwert „ target “, an den „ plugin “ angehängt wird. Beispielsweise hätte ein Backing-Ziel namens „ mymodule “ den Standard-Plugin-Namen „ mymoduleplugin “. Der Name des Plugin-Ziels wird verwendet, um eine „ plugin “-Zeile in der generierten qmldir-Datei zu füllen. Daher dürfen Sie nicht versuchen, den Ausgabennamen des Plugins zu ändern, indem Sie Ziel-Eigenschaften wie „ OUTPUT_NAME “ oder eine der damit verbundenen Eigenschaften festlegen.

Die zugrunde liegende „ target “ und das Plugin-Ziel (sofern unterschiedlich) werden durch den Befehl erstellt, sofern sie nicht bereits vorhanden sind. Projekte sollten im Allgemeinen zulassen, dass diese durch den Befehl erstellt werden, damit sie als der richtige Zieltyp angelegt werden. Ist die zugrunde liegende „ target “ eine statische Bibliothek, wird das Plugin ebenfalls als statische Bibliothek erstellt. Ist das zugrunde liegende target eine gemeinsam genutzte Bibliothek, wird das Plugin als Modulbibliothek erstellt. Wird ein vorhandenes target übergeben und handelt es sich dabei um ein ausführbares Ziel, wird kein Plugin erstellt. Wenn Sie beabsichtigen, immer direkt mit dem zugrunde liegenden Ziel zu verknüpfen und kein Plugin benötigen, kann dies durch Hinzufügen der Option „ NO_PLUGIN “ deaktiviert werden. Die Angabe von sowohl „ NO_PLUGIN “ als auch „ PLUGIN_TARGET “ führt zu einem Fehler.

In bestimmten Situationen kann es vorkommen, dass das Projekt die Erstellung des Plugin-Ziels bis nach dem Aufruf verzögern möchte. In diesem Fall kann die Option „ NO_CREATE_PLUGIN_TARGET “ angegeben werden. Es wird dann erwartet, dass das Projekt „qt_add_qml_plugin()“ für das Plugin-Ziel aufruft, sobald dieses erstellt wurde. Wenn „ NO_CREATE_PLUGIN_TARGET “ angegeben wird, muss zusätzlich „ PLUGIN_TARGET “ bereitgestellt werden, um das Plugin-Ziel explizit zu benennen.

Standardmäßig generiert „ qt_add_qml_module() “ automatisch eine „ .cpp “-Datei, die die durch das Argument „ CLASS_NAME “ benannte Plugin-Klasse implementiert. Die generierte „ .cpp “-Datei wird dem Plugin-Ziel automatisch als zu kompilierende Quelldatei hinzugefügt. Wenn das Projekt eine eigene Implementierung der Plugin-Klasse bereitstellen möchte, sollte die Option „ NO_GENERATE_PLUGIN_SOURCE “ angegeben werden. Wird kein „ CLASS_NAME “ angegeben, wird standardmäßig „ URI “ verwendet, wobei Punkte durch Unterstriche ersetzt und anschließend „ Plugin “ angehängt wird. Sofern das QML-Modul kein Plugin enthält, wird der Klassenname als Zeile „ classname “ in der generierten qmldir-Datei vermerkt. Sie müssen alle C++-Dateien mit benutzerdefiniertem Plugin-Code zum Plugin-Ziel hinzufügen. Da das Plugin dann wahrscheinlich Funktionen enthält, die über das bloße Laden der zugrunde liegenden Bibliothek hinausgehen, sollten Sie wahrscheinlich auch NO_PLUGIN_OPTIONAL hinzufügen. Andernfalls überspringt die QML-Engine möglicherweise das Laden des Plugins, wenn sie feststellt, dass die zugrunde liegende Bibliothek bereits eingebunden ist.

Wird das Schlüsselwort „ NO_PLUGIN “ angegeben, wird kein Plugin erstellt. Dieses Schlüsselwort ist daher nicht kompatibel mit allen Optionen, die das Plugin-Ziel anpassen, insbesondere mit NO_GENERATE_PLUGIN_SOURCE, NO_PLUGIN_OPTIONAL, PLUGIN_TARGET, NO_CREATE_PLUGIN_TARGET und CLASS_NAME. Wenn Sie kein Plugin für Ihr Modul bereitstellen, ist dieses nur dann voll funktionsfähig, wenn die zugrunde liegende Bibliothek in die ausführbare Datei eingebunden wurde. Es ist im Allgemeinen schwierig zu gewährleisten, dass ein Linker die Verknüpfung zu einer Bibliothek beibehält, die er als ungenutzt betrachtet.

Wird das Schlüsselwort „ NO_PLUGIN_OPTIONAL “ angegeben, wird das Plugin in der generierten Datei „ qmldir “ als nicht optional vermerkt. Sind alle Funktionen eines QML-Moduls in seinem zugrunde liegenden Ziel implementiert und ist das Plugin-Ziel separat, kann das Plugin optional sein – dies ist die Standard- und empfohlene Vorgehensweise. Die automatisch generierte Plugin-Quelldatei erfüllt diese Anforderung. Wenn ein Projekt eine eigene ` .cpp `-Implementierung für das Plugin bereitstellt, bedeutet dies normalerweise, dass auch das Schlüsselwort ` NO_PLUGIN_OPTIONAL ` erforderlich ist, da das Plugin mit ziemlicher Sicherheit Funktionen enthält, die das QML-Modul benötigt.

Automatische Typregistrierung

qt_add_qml_module generiert automatisch mehrere Dateien. Die folgenden Optionen steuern, was generiert wird. In den meisten Fällen sind die Standardeinstellungen korrekt und keine dieser Optionen ist erforderlich.

Die Typregistrierung erfolgt automatisch für die C++-Quelldateien des zugrunde liegenden Ziels, die von AUTOMOC verarbeitet werden. Dabei wird im Ausgabeverzeichnis eine Typeinfo-Datei generiert, deren Dateiname dem Namen „ target “ mit dem Suffix „ .qmltypes “ entspricht. Dieser Dateiname kann bei Bedarf mit der Option „ TYPEINFO “ geändert werden, was jedoch normalerweise nicht erforderlich sein sollte. Der Dateiname wird außerdem als Eintrag „ typeinfo “ in der generierten qmldir-Datei gespeichert. Die automatische Typregistrierung kann mit der Option „ NO_GENERATE_QMLTYPES “ deaktiviert werden. In diesem Fall wird keine typeinfo-Datei generiert, es wird jedoch weiterhin erwartet, dass das Projekt eine typeinfo-Datei erstellt und diese im selben Verzeichnis wie die generierte qmldir -Datei ablegt.

OUTPUT_DIRECTORY Legt fest, wo die Plugin-Bibliothek sowie die Dateien „ qmldir “ und „typeinfo“ generiert werden. Wenn dieses Schlüsselwort nicht angegeben wird, ist der Standardwert der Zielpfad (gebildet aus „ URI “), an den der Wert der Variablen „QT_QML_OUTPUT_DIRECTORY“ angehängt wird. Ist diese Variable nicht definiert, hängt der Standardwert vom Typ des zugrunde liegenden Ziels ab. Bei ausführbaren Dateien ist der Wert der Zielpfad, an den ${CMAKE_CURRENT_BINARY_DIR} angehängt wird, während er bei anderen Zielen einfach ${CMAKE_CURRENT_BINARY_DIR} lautet. Wenn die Struktur des Quellbaums mit der Struktur der Zielpfade der QML-Module übereinstimmt (was dringend empfohlen wird), ist QT_QML_OUTPUT_DIRECTORY oft nicht erforderlich. Um die Struktur der Zielpfade einzuhalten, müssen Sie Ihre Verzeichnisse genau so benennen wie die Segmente Ihrer Modul-URI. Wenn Ihre Modul-URI beispielsweise MyUpperCaseThing.mylowercasething lautet, müssen Sie diese in ein Verzeichnis namens MyUpperCaseThing/mylowercasething/ ablegen.

Die Angabe des Schlüsselworts „ OUTPUT_DIRECTORY “ sollte nur selten erforderlich sein; wird es jedoch verwendet, muss der Aufrufer wahrscheinlich auch den „IMPORT_PATH“ erweitern, um sicherzustellen, dass das Linting, die zwischengespeicherte Kompilierung von QML-Quellen, der automatische Import von Plugins bei statischen Builds sowie die Bereitstellung importierter QML-Module bei nicht-statischen Builds korrekt funktionieren.

Qt Quick Designer-Kompatibilität

DESIGNER_SUPPORTED sollte angegeben werden, wenn das QML-Modul den „ Qt Quick “-Designer unterstützt. Ist dies der Fall, enthält die generierte Datei „ qmldir “ eine Zeile „ designersupported “. Informationen dazu, wie sich dies auf die Verarbeitung des Plugins durch den „ Qt Quick “-Designer auswirkt, finden Sie unter „Moduldefinition – qmldir-Dateien “.

Modulversionen synchron halten

Das Schlüsselwort „ FOLLOW_FOREIGN_VERSIONING “ bezieht sich auf Basistypen Ihrer eigenen, in C++ definierten QML-Typen, die in verschiedenen QML-Modulen enthalten sind. In der Regel stimmt das Versionsschema Ihres Moduls nicht mit dem des Moduls überein, das die Basistypen bereitstellt. Daher werden standardmäßig alle Revisionen der Basistypen bei jedem Import Ihres Moduls zur Verfügung gestellt. Wenn „ FOLLOW_FOREIGN_VERSIONING “ angegeben wird, werden die mit den Basistypen und deren Eigenschaften verbundenen Versionsinformationen berücksichtigt. Ein ` import MyModule 2.8 ` stellt somit nur versionierte Eigenschaften bis zur Version ` 2.8 ` aller Basistypen außerhalb von ` MyModule` zur Verfügung. Dies ist vor allem dann nützlich, wenn Sie die Version Ihres Moduls mit anderen Modulen synchron halten möchten, auf deren Typen Ihre eigenen basieren. In diesem Fall möchten Sie möglicherweise vermeiden, dass Ihre benutzerdefinierten Typen Eigenschaften aus einer Basistyp-Version eines Moduls offenlegen, die höher ist als die des importierten Moduls.

C++-Namespaces des generierten Codes

Wenn ein Namespace mit dem Schlüsselwort „ NAMESPACE “ angegeben wird, werden das Plugin und der Registrierungscode in einem C++-Namespace mit diesem Namen generiert.

qmlimportscanner und NO_IMPORT_SCAN

Bei statischen Qt-Builds wird „ qmlimportscanner “ während der Konfiguration ausgeführt, um die „ .qml “-Dateien eines QML-Moduls zu scannen und die darin verwendeten QML-Importe zu identifizieren (siehe qt_import_qml_plugins()). Bei nicht-statischen Qt-Builds wird, sofern das Ziel eine ausführbare Datei ist, zum Zeitpunkt des Builds ein ähnlicher Scan durchgeführt, um die von Deployment-Skripten benötigten Informationen bereitzustellen (siehe qt_deploy_qml_imports()). Beide Scans können durch Angabe der Option „ NO_IMPORT_SCAN “ deaktiviert werden. Dies bedeutet, dass das Projekt die Verantwortung dafür übernimmt, sicherzustellen, dass alle erforderlichen Plugins für statische Builds instanziiert und verknüpft werden. Bei nicht-statischen Builds muss das Projekt alle von einem ausführbaren Ziel verwendeten QML-Module manuell ermitteln und bereitstellen.

DISCARD_QML_CONTENTS

Standardmäßig werden die Inhalte der QML- und JS-Quelldateien in das Ressourcensystem des Ziels aufgenommen. Verwenden Sie „ DISCARD_QML_CONTENTS “, um diese Inhalte zu entfernen und die Größe der Binärdatei zu reduzieren.

Argumente für `qmltc`

ENABLE_TYPE_COMPILER können verwendet werden, um „ .qml “-Dateien mit qmltc in C++-Quellcode zu kompilieren. Dateien mit der Eigenschaft „source“ QT_QML_SKIP_TYPE_COMPILER werden nicht in C++ kompiliert.

TYPE_COMPILER_NAMESPACE Mit diesem Argument lässt sich der Namensraum überschreiben, in dem qmltc Code generiert. Standardmäßig folgt der Namensraum des generierten Codes der Modulhierarchie, wie sie in der URI dargestellt ist, z. B. MyModule für ein Modul mit der URI MyModule oder com::example::Module für die URI com.example.MyModule. Durch Angabe der Option „ TYPE_COMPILER_NAMESPACE “ kann der generierte Code stattdessen in einen benutzerdefinierten Namensraum eingefügt werden, wobei verschiedene Unternamensräume durch „::“ getrennt werden müssen, z. B. „MyNamespace::MySubnamespace“ für den Namensraum „MySubnamespace“, der sich innerhalb von „MyNamespace“ befindet. Abgesehen vom „::“ gelten die Namenskonventionen für C++-Namespaces.

QMLTC_EXPORT_DIRECTIVE sollte zusammen mit „ QMLTC_EXPORT_FILE_NAME “ verwendet werden, wenn die von qmltc generierten Klassen aus der QML-Bibliothek exportiert werden sollen. Standardmäßig werden von qmltc generierte Klassen nicht aus ihrer Bibliothek exportiert. Der Header, der das Export-Makro für die aktuelle Bibliothek definiert, kann als optionales Argument für ` QMLTC_EXPORT_FILE_NAME ` angegeben werden, während der Name des Export-Makros als Argument für ` QMLTC_EXPORT_DIRECTIVE` angegeben werden sollte. Wenn kein zusätzliches Include erforderlich oder gewünscht ist, z. B. wenn der Header des Export-Makros bereits indirekt von einer Basisklasse eingebunden wird, kann die Option ` QMLTC_EXPORT_FILE_NAME ` weggelassen werden.