qt_add_qml_module

Dieser Befehl wurde in Qt 6.2 eingeführt.

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]
    [ENABLE_TYPE_COMPILER]
    [TYPE_COMPILER_NAMESPACE namespace]
    [QMLTC_EXPORT_DIRECTIVE export_macro]
    [QMLTC_EXPORT_FILE_NAME header_defining_export_macro]

)

Wenn versionslose Befehle deaktiviert sind, verwenden Sie stattdessen qt6_add_qml_module(). Er unterstützt die gleichen Argumente wie dieser Befehl.

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

Siehe QT_QML_GENERATE_QMLLS_INI um Ihr Projekt so zu konfigurieren, dass Informationen über QML-Module in der QML Language Server.

Beschreibung

Dieser Befehl definiert ein QML-Modul, das aus C++-Quellen, .qml -Dateien oder beidem bestehen kann. Er stellt sicher, dass die wesentlichen Moduldetails bereitgestellt werden und dass sie konsistent sind. Außerdem werden Dinge wie die zwischengespeicherte Kompilierung von .qml -Quellen, die Einbettung von Ressourcen, Linting-Prüfungen und die automatische Erzeugung einiger wichtiger Moduldateien eingerichtet und koordiniert.

Zielstruktur

Ein QML-Modul kann auf verschiedene Weise strukturiert werden. Die folgenden Szenarien sind die typischen Anordnungen:

Getrennte Backing- und Plugin-Targets

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++-Quellen, .qml -Dateien und Ressourcen sollten alle zum Backing-Target hinzugefügt werden. Das Backing-Target ist eine Bibliothek, die am gleichen Ort wie alle anderen vom Projekt definierten Bibliotheken installiert werden sollte.

Die Quellverzeichnisstruktur, unter der das Sicherungsziel erstellt wird, sollte mit dem Zielpfad des QML-Moduls übereinstimmen (der Zielpfad ist der URI des Moduls, wobei Punkte durch Schrägstriche ersetzt werden). Wenn die Struktur des Quellverzeichnisses nicht mit dem Zielpfad übereinstimmt, wird qt_add_qml_module() eine Warnung ausgeben.

Das folgende Beispiel zeigt eine geeignete Quellverzeichnisstruktur für ein QML-Modul mit einem URI von 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 nicht bereits mit dem Backing-Target verknüpft ist. Das Plugin-Target ist ebenfalls eine Bibliothek und wird normalerweise in dasselbe Verzeichnis wie die qmldir-Datei des Moduls installiert.

Das Plugin-Target sollte idealerweise nicht mehr als eine triviale Implementierung der Plugin-Klasse enthalten. Dadurch kann das Plugin in der Datei qmldir als optional gekennzeichnet werden. Andere Targets können dann direkt auf das Backing-Target verlinken 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-Target hinzugefügt. Für Fälle, in denen das QML-Modul eine eigene Plugin-Klassen-Implementierung benötigt, sind die Optionen NO_GENERATE_PLUGIN_SOURCE und normalerweise NO_PLUGIN_OPTIONAL erforderlich.

Die STATIC QML-Module erzeugen auch die statischen QML-Plugins, wenn NO_PLUGIN nicht angegeben ist. Ziele, die solche STATIC QML-Module importieren, müssen auch explizit auf entsprechende QML-Plugins verlinken.

Plugin-Target ohne Backing-Target

Ein QML-Modul kann so definiert werden, dass das Plugin-Target als sein eigenes Backing-Target dient. In diesem Fall muss das Modul zur Laufzeit dynamisch geladen werden und kann nicht direkt von anderen Targets gelinkt werden. Um diese Anordnung zu erstellen, muss das Schlüsselwort PLUGIN_TARGET verwendet werden, wobei target als Name des Plugin-Targets wiederholt wird. Zum Beispiel:

qt_add_qml_module(someTarget
    PLUGIN_TARGET someTarget
    ...
)

Auch wenn diese Anordnung geringfügig einfacher zu implementieren scheint, sollte ein separates Backing-Target nach Möglichkeit bevorzugt werden, da es eine bessere Leistung beim Laden bietet.

Ausführbar als QML-Modul

Ein ausführbares Ziel kann als Backing Target 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 unterstützendes Ziel verwendet wird und deaktiviert automatisch die Erstellung eines separaten Plugins. Verwenden Sie keine der Optionen mit PLUGIN in ihrem Namen, wenn Sie diese Anordnung verwenden.

Wenn eine ausführbare Datei als unterstützendes Ziel verwendet wird, wird nicht erwartet, dass die Quellverzeichnisstruktur mit dem Zielpfad des QML-Moduls übereinstimmt. Siehe Zwischenspeichern von kompilierten QML-Quellen für zusätzliche Zielpfadunterschiede für einkompilierte Ressourcen.

Automatisches Generieren von qmldir und Typeinfo-Dateien

Standardmäßig werden eine qmldir-Datei und eine typeinfo-Datei für das zu definierende QML-Modul automatisch generiert. Der Inhalt dieser Dateien wird durch die verschiedenen Argumente bestimmt, die diesem Befehl übergeben werden, sowie durch die Quellen und .qml Dateien, die dem Backing-Target hinzugefügt wurden. Das Argument OUTPUT_DIRECTORY bestimmt, wohin die Dateien qmldir und typeinfo geschrieben werden. Wenn das QML-Modul über ein Plugin verfügt, wird dieses Plugin ebenfalls im selben Verzeichnis wie die Datei qmldir erstellt.

Wenn die QTP0004-Richtlinie auf NEW gesetzt ist, wird für jedes weitere Verzeichnis, das .qml Dateien enthält, eine weitere qmldir Datei erzeugt. Diese zusätzlichen qmldir Dateien leiten lediglich über eine prefer Direktive auf das Basisverzeichnis des Moduls um. Auf diese Weise können alle QML-Komponenten eines Moduls aufeinander zugreifen, unabhängig davon, in welchem Verzeichnis sie gespeichert sind.

Wenn ein statisch erstelltes Qt verwendet wird, werden die .qml Dateien des Backing Targets während des CMake configure Laufs gescannt, um die vom Modul verwendeten Importe zu ermitteln und Verknüpfungsbeziehungen einzurichten (das NO_IMPORT_SCAN Schlüsselwort kann angegeben werden, um dies zu deaktivieren). Wenn eine .qml Datei zum Modul hinzugefügt oder aus ihm entfernt wird, wird CMake normalerweise automatisch erneut ausgeführt und die relevanten Dateien werden erneut gescannt, da eine CMakeLists.txt Datei geändert wurde. Im Laufe der Entwicklung kann eine bestehende .qml Datei einen Import oder einen Typ hinzufügen oder entfernen. Dies allein würde nicht dazu führen, dass CMake automatisch neu gestartet wird. Daher sollten Sie CMake explizit neu starten, um zu erzwingen, dass die Datei qmldir neu generiert wird und alle Verknüpfungsbeziehungen aktualisiert werden.

Die C++-Quellen des Backing-Ziels werden zur Erstellungszeit gescannt, um eine Typeinfo-Datei und eine C++-Datei zur Registrierung der zugehörigen Typen zu erzeugen. Die generierte C++-Datei wird dem Backing-Target automatisch als Quelle hinzugefügt. Dies erfordert, dass AUTOMOC auf dem Ziel aktiviert ist. Das Projekt ist dafür verantwortlich, dies sicherzustellen, indem es normalerweise die Variable CMAKE_AUTOMOC auf TRUE setzt, bevor es qt_add_qml_module() aufruft, oder indem es ein vorhandenes Ziel übergibt, 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 Handhabung der Konsequenzen verantwortlich. Dies kann bedeuten, dass die Typeinfo-Datei manuell generiert werden muss, anstatt sie mit fehlenden Details automatisch generieren zu lassen, und dass C++-Code zur Registrierung der Typen hinzugefügt werden muss.

Projekte sollten, wenn möglich, die automatisch generierten Typeinfo- und qmldir -Dateien verwenden. Sie sind leichter zu pflegen und leiden nicht unter der gleichen Fehleranfälligkeit wie handgeschriebene Dateien. Für Situationen, in denen das Projekt diese Dateien selbst bereitstellen muss, kann die automatische Generierung jedoch 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 und C++-Typregistrierung. Wenn die automatisch erzeugte Typeinfo-Datei akzeptabel ist, das Projekt aber einen anderen Namen für diese Datei verwenden möchte, kann es den Standardnamen mit der Option TYPEINFO überschreiben (dies sollte aber normalerweise nicht erforderlich sein).

Zwischenspeichern von kompilierten QML-Quellen

Alle .qml, .js und .mjs Dateien, die dem Modul über das Argument QML_FILES hinzugefügt werden, werden zu Bytecode kompiliert und direkt im Backing-Ziel zwischengespeichert. Dies verbessert die Leistung des Moduls beim Laden. Die ursprünglichen, nicht kompilierten Dateien werden ebenfalls in den Ressourcen des Backing-Targets gespeichert, da diese in bestimmten Situationen von der QML-Engine noch benötigt werden können.

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

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

Normalerweise sollte das Projekt darauf abzielen, die Dateien .qml an demselben relativen Ort zu platzieren, an dem sie sich auch in den Ressourcen befinden würden. Wenn sich die Datei .qml in einem anderen relativen Verzeichnis als dem gewünschten Ressourcenpfad befindet, muss ihr Speicherort in den Ressourcen explizit angegeben werden. Dies geschieht durch Setzen der Eigenschaft QT_RESOURCE_ALIAS source file, die gesetzt werden muss, bevor die Datei .qml hinzugefügt wird. Zum 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. Nach Berücksichtigung der Quelldateieigenschaften werden die beiden Dateien .qml unter den folgenden Ressourcenpfaden zu finden sein:

• /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 qmlcachegen-Programms außer Kraft setzen wollen, können Sie die Eigenschaft QT_QMLCACHEGEN_EXECUTABLE target auf das Modulziel setzen. Zum Beispiel:

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_EXECUTABLE qmlcachegen
)

Damit wird qmlcachegen explizit als das zu verwendende Programm ausgewählt, auch wenn bessere Alternativen verfügbar sind.

Außerdem können Sie zusätzliche Argumente an qmlcachegen übergeben, indem Sie die Option QT_QMLCACHEGEN_ARGUMENTS setzen. Insbesondere schaltet die Option --only-bytecode die Kompilierung von QML-Skriptcode nach C++ aus. Zum Beispiel:

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

Ein weiteres wichtiges Argument ist --direct-calls. Sie können es verwenden, um den direkten Modus des QML-Skript-Compilers zu aktivieren, wenn die Qt Quick Compiler Erweiterungen installiert sind. Wenn die Erweiterungen nicht installiert sind, wird das Argument ignoriert. Es gibt eine Abkürzung namens QT_QMLCACHEGEN_DIRECT_CALLS für dieses Argument.

set_target_properties(someTarget PROPERTIES
    QT_QMLCACHEGEN_DIRECT_CALLS ON
)

Schließlich kann das Argument --verbose verwendet werden, um Diagnoseausgaben von qmlcachegen zu sehen:

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 nach C++ kompilieren kann. Einige dieser Warnungen weisen auf Probleme in Ihrem QML-Code hin, und andere sagen Ihnen, dass bestimmte Funktionen der QML-Sprache nicht im C++-Codegenerator implementiert sind. In beiden Fällen wird qmlcachegen trotzdem Bytecode für solche Funktionen erzeugen. Wenn Sie nur die Probleme in Ihrem QML-Code sehen wollen, sollten Sie stattdessen qmllint und die dafür generierten Targets verwenden.

Linting von QML-Quellen

Ein separates Linting-Target wird automatisch erstellt, wenn irgendwelche .qml Dateien dem Modul über das QML_FILES Schlüsselwort oder durch einen späteren Aufruf von qt_target_qml_sources() hinzugefügt werden. Der Name des Linting-Targets ist target, gefolgt von _qmllint. Ein all_qmllint -Ziel, das von allen einzelnen *_qmllint -Zielen abhängt, wird ebenfalls als Hilfestellung angeboten.

Namenskonventionen für .js Dateien

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

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

Singletons

Wenn ein QML-Modul über .qml Dateien verfügt, die Singleton-Typen bereitstellen, muss die Quelleigenschaft QT_QML_SINGLETON_TYPE dieser Dateien auf TRUE gesetzt werden, um sicherzustellen, dass der Befehl singleton in die qmldir-Datei geschrieben wird. Dies muss zusätzlich zu der QML-Datei erfolgen, die die Anweisung pragma Singleton enthält. Die Quelleigenschaft muss vor der Erstellung des Moduls, zu dem das Singleton gehört, gesetzt werden.

Siehe qt_target_qml_sources() für ein Beispiel, wie man die QT_QML_SINGLETON_TYPE Eigenschaft setzt.

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

Wenn ein QML-Modul .qml Dateien hat, können Sie diese mit qmltc nach C++ kompilieren. Im Gegensatz zur Bytecode-Kompilierung müssen Sie qmltc explizit über das Argument ENABLE_TYPE_COMPILER aktivieren. In diesem Fall würden .qml Dateien, die unter QML_FILES angegeben sind, kompiliert werden. Dateien, die mit .js und .mjs enden, werden ignoriert, da qmltc keinen JavaScript-Code kompiliert. Zusätzlich werden Dateien, die mit der QT_QML_SKIP_TYPE_COMPILER-Quelldatei-Eigenschaft gekennzeichnet sind, ebenfalls übersprungen.

Standardmäßig erstellt qmltc Dateien in Kleinbuchstaben .h und .cpp für eine gegebene Datei .qml. Zum Beispiel wird Foo.qml in foo.h und foo.cpp kompiliert.

Die erstellten C++ Dateien werden in ein spezielles .qmltc/<target>/ Unterverzeichnis des BINARY_DIR des target abgelegt. Diese Dateien werden dann automatisch zu den Zielquellen hinzugefügt und als Qt C++ Code zusammen mit anderen Quelldateien kompiliert.

Bei der Verarbeitung von QML_FILES werden die folgenden Eigenschaften der Quelldateien beachtet:

• QT_QMLTC_FILE_BASENAMEQT_QMLTC_FILE: Verwenden Sie diese Quelldateieigenschaft, um einen nicht standardmäßigen .h- und .cpp-Dateinamen anzugeben, was nützlich sein kann, um z.B. widersprüchliche Dateinamen aufzulösen (stellen Sie sich vor, Sie haben main.qml, die kompiliert wird, aber main.h existiert bereits, so dass #include "main.h" möglicherweise nicht das tut, was Sie erwarten). QT_QMLTC_FILE_BASENAME wird als Dateiname (ohne Erweiterung) erwartet, daher wird jedes vorangehende Verzeichnis ignoriert. Anders als im Falle des Standardverhaltens wird QT_QMLTC_FILE_BASENAME nicht kleingeschrieben.
• QT_QML_SKIP_TYPE_COMPILERQT_QMLTC_FILE_BASENAME: Verwenden Sie diese Quelldatei-Eigenschaft, um anzugeben, dass eine QML-Datei von qmltc ignoriert werden soll.

Argumente

Erforderliche Argumente

target gibt den Namen des Backing-Targets für das QML-Modul an. Standardmäßig wird es als Shared Library erstellt, wenn Qt als Shared Library gebaut wurde, ansonsten als statische Bibliothek. Diese Wahl kann explizit mit den Optionen STATIC oder SHARED überschrieben werden.

Jedes QML-Modul muss ein URI definieren. Es sollte in gepunkteter URI-Notation angegeben werden, wie QtQuick.Layouts. Jedes Segment muss ein wohlgeformter ECMAScript Identifier Name sein. Das bedeutet zum Beispiel, dass die Segmente nicht mit einer Zahl beginnen und keine - (Minus-)Zeichen enthalten dürfen. Da die URI in Verzeichnisnamen übersetzt wird, sollten Sie sie auf alphanumerische Zeichen des lateinischen Alphabets, Unterstriche und Punkte beschränken. Andere QML-Module können diesen Namen in Import-Anweisungen verwenden, um das Modul zu importieren. Die URI wird in der module Zeile der generierten qmldir Datei verwendet. URI wird auch verwendet, um den Zielpfad zu bilden, indem die Punkte durch Schrägstriche ersetzt werden.

Weitere ausführliche Informationen zum Modul-URI finden Sie unter Identifizierte Module.

Versionen

Ein QML-Modul kann auch ein VERSION in der Form Major.Minor definieren, wobei sowohl Major als auch Minor ganze Zahlen sein müssen. Eine zusätzliche .Patch Komponente kann angehängt werden, wird aber ignoriert. Eine Liste früherer Hauptversionen, für die das Modul Typen bereitstellt, kann ebenfalls optional nach dem Schlüsselwort PAST_MAJOR_VERSIONS angegeben werden (siehe unten). Weitere ausführliche Informationen zur Versionsnummerierung finden Sie unter Identifizierte Module, zur Registrierung früherer Hauptversionen und zur Synchronisierung von Modulversionen.

Wenn Sie keine Versionen benötigen, sollten Sie das Argument VERSION weglassen. Es wird standardmäßig auf die höchstmögliche Version gesetzt. Die interne Versionierung von QML-Modulen hat einige grundlegende Schwächen. 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-Quellen an, die dem Backing-Target hinzugefügt werden sollen. Dies ist eine praktische Funktion und entspricht dem Hinzufügen der Quellen zum Backing-Target mit dem eingebauten CMake-Befehl target_sources().

QML_FILES listet die Dateien .qml, .js und .mjs für das Modul auf. Diese werden automatisch in Bytecode kompiliert und in das Backing-Target eingebettet, sofern nicht die Option NO_CACHEGEN angegeben wird. Die nicht kompilierte Datei wird immer in den eingebetteten Ressourcen des Backing-Targets gespeichert, auch wenn NO_CACHEGEN angegeben ist. Sofern die Option NO_LINT nicht angegeben wird, werden die nicht kompilierten Dateien auch von qmllint über ein separates benutzerdefiniertes Build-Target verarbeitet. Die Dateien werden auch verwendet, um die Typinformationen in der generierten qmldir-Datei aufzufüllen. NO_GENERATE_QMLDIR kann angegeben werden, um die automatische Erzeugung der Datei qmldir zu deaktivieren. Dies sollte normalerweise vermieden werden, aber für Fälle, in denen das Projekt seine eigene qmldir Datei bereitstellen muss, kann diese Option verwendet werden. Seit Qt 6.8, wenn QTP0004 aktiviert ist, erstellt qt_add_qml_module zusätzliche qmldir Dateien für jedes Unterverzeichnis im QML-Modul, die sicherstellen, dass jede QML-Datei ihr eigenes Modul über den impliziten Import importiert. Dieses Verhalten kann für ein QML-Modul ausgeschaltet werden, indem ihm das Flag NO_GENERATE_EXTRA_QMLDIRS übergeben wird. Das NO_GENERATE_QMLDIR impliziert NO_GENERATE_EXTRA_QMLDIRS.

RESOURCES listet alle anderen Dateien auf, die das Modul benötigt, wie z.B. Bilder, die vom QML-Code referenziert werden. Diese Dateien werden als einkompilierte Ressourcen hinzugefügt (siehe RESOURCE_PREFIX für eine Erklärung des Basispunktes, unter dem sie sich befinden). Bei Bedarf kann ihr relativer Speicherort durch Festlegen der Eigenschaft QT_RESOURCE_ALIAS source gesteuert werden, genau wie bei .qml (siehe Zwischenspeichern kompilierter QML-Quellen).

RESOURCE_PREFIX ist dazu gedacht, einen Namespace für das Projekt zu kapseln und wird oft für alle QML-Module, die das Projekt definiert, gleich sein. Er sollte so gewählt werden, dass er nicht mit dem Ressourcen-Präfix eines anderen Projekts kollidiert oder von einem anderen Projekt verwendet wird, das ihn möglicherweise nutzt. Eine gute Wahl ist es, den Domänennamen der Organisation, zu der das Projekt gehört, mit einzubeziehen. Eine übliche Konvention ist es, /imports an den Domänennamen anzuhängen, um das Ressourcenpräfix zu bilden. Zum Beispiel:

qt_add_qml_module(someTarget
    RESOURCE_PREFIX /my.company.com/imports
    ...
)

Wenn verschiedene Dateien zu den einkompilierten Ressourcen hinzugefügt werden, werden sie unter einem Pfad platziert, der durch die Verkettung von RESOURCE_PREFIX und dem Zielpfad gebildet wird. Für den speziellen Fall, dass das unterstützende Ziel eine ausführbare Datei ist, kann es wünschenswert sein, die Dateien des Moduls .qml und andere Ressourcen stattdessen direkt unter RESOURCE_PREFIX zu platzieren. Dies kann durch die Angabe der Option NO_RESOURCE_TARGET_PATH erreicht werden, die nur verwendet werden darf, wenn das unterstützende Ziel eine ausführbare Datei ist.

Registrierung früherer Hauptversionen

PAST_MAJOR_VERSIONS enthält eine Liste der zusätzlichen Hauptversionen, die das Modul bereitstellt. Für jede dieser Versionen und jede QML-Datei ohne eine QT_QML_SOURCE_VERSIONS -Einstellung wird ein zusätzlicher Eintrag in der qmldir-Datei erzeugt, um die zusätzliche Version anzugeben. Außerdem registriert der generierte Modulregistrierungscode die vergangenen Hauptversionen mit qmlRegisterModule() auf der C++-Seite. 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 einen gewissen Overhead, wenn Ihr Modul importiert wird. Sie sollten die Hauptversion Ihres Moduls so selten wie möglich inkrementieren. Sobald Sie sich darauf verlassen können, dass alle QML-Dateien, die dieses Modul importieren, die Version in ihren Importen weglassen, können Sie PAST_MAJOR_VERSIONS getrost weglassen. Alle QML-Dateien werden dann die neueste Version Ihres Moduls importieren. Wenn Sie versionierte Importe unterstützen müssen, sollten Sie nur eine begrenzte Anzahl von früheren Hauptversionen unterstützen.

Deklaration von Modul-Abhängigkeiten

IMPORTS liefert eine Liste anderer QML-Module, die dieses Modul importiert. Jedes hier aufgeführte Modul wird als import -Eintrag 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, so wird die größte verfügbare Version importiert. Sie können auch nur die Hauptversion angeben, wie in QtQuick/2. In diesem Fall wird die größte verfügbare Nebenversion mit der angegebenen Hauptversion importiert. Schließlich kann auto als Version (QtQuick/auto) angegeben werden. Wenn auto angegeben wird, wird die Version, mit der das aktuelle Modul importiert wird, an das zu importierende Modul weitergegeben. Bei einem Eintrag QtQuick/auto in einem 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.

OPTIONAL_IMPORTS bietet eine Liste anderer QML-Module, die dieses Modul zur Laufzeit importieren kann. Diese werden nicht automatisch von der QML-Engine importiert, wenn das aktuelle Modul importiert wird, sondern dienen eher als Hinweise für Werkzeuge wie qmllint. Die Versionen können auf die gleiche Weise wie bei IMPORTS angegeben werden. Jedes hier aufgeführte Modul wird als optional import Eintrag in die generierte qmldir Datei eingefügt.

DEFAULT_IMPORTS gibt an, welche der optionalen Importe die Standardeinträge sind, die vom Tooling 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 Werkzeuge wie qmllint im Allgemeinen nicht wissen, welche der optionalen Importe aufgelöst werden sollen. Um dieses Problem zu lösen, können Sie einen der optionalen Importe als Standardimport festlegen; das Tooling wählt ihn 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.

DEPENDENCIES liefert eine Liste anderer QML-Module, von denen dieses Modul abhängt, die es aber nicht unbedingt importiert. Dies wird typischerweise für Abhängigkeiten verwendet, die nur auf der C++-Ebene bestehen, z. B. wenn ein Modul eine Klasse in QML registriert, die eine Unterklasse einer Klasse ist, die in einem anderen Modul definiert ist.

Wenn man zum Beispiel die Klasse QQuickItem wie folgt unterteilen möchte:

class MyItem: public QQuickItem { ... };

dann muss man sicherstellen, dass das Modul, das QQuickItem enthält, namens QtQuick, über die Option DEPENDENCIES als Abhängigkeit deklariert wird. Andernfalls kann es zu Fehlern bei der Typkompilierung mit qmltc oder bei der Bindung und Funktionskompilierung nach C++ mit qmlcachegen kommen.

Die Modulversion der Abhängigkeiten muss zusammen mit dem Modulnamen angegeben werden, und zwar in der gleichen Form wie bei IMPORTS und OPTIONAL_IMPORTS. Jedes hier aufgeführte Modul wird als Eintrag depends in die erzeugte qmldir-Datei eingefügt.

IMPORT_PATH kann verwendet werden, um den Suchpfaden hinzuzufügen, wo andere QML-Module, von denen dieses Modul abhängt, gefunden werden können. Die anderen Module müssen ihre qmldir Datei unter ihrem eigenen Zielpfad unterhalb eines der Suchpfade haben.

Wenn das unterstützende Ziel eine statische Bibliothek ist und diese statische Bibliothek installiert wird, sollte OUTPUT_TARGETS angegeben werden, um eine Variable bereitzustellen, in der eine Liste von zusätzlichen Zielen gespeichert wird, die ebenfalls installiert werden müssen. Diese zusätzlichen Targets werden intern von qt_add_qml_module() generiert und von den Linking-Anforderungen des Backing-Targets referenziert, um sicherzustellen, dass die Ressourcen korrekt eingerichtet und geladen werden.

Targets und Plugin-Targets

PLUGIN_TARGET spezifiziert das mit dem QML-Modul verbundene Plugin-Target. PLUGIN_TARGET kann dasselbe sein wie das Backing-Ziel target. In diesem Fall gibt es kein separates Backing-Ziel. Wenn PLUGIN_TARGET nicht angegeben wird, ist es standardmäßig target mit angehängtem plugin. Ein Backing-Target mit dem Namen mymodule hätte zum Beispiel den Standard-Plugin-Namen mymoduleplugin. Der Name des Plugin-Targets wird verwendet, um die Zeile plugin in der generierten qmldir-Datei zu füllen. Daher dürfen Sie nicht versuchen, den Ausgabennamen des Plugins zu ändern, indem Sie Zieleigenschaften wie OUTPUT_NAME oder eine der damit verbundenen Eigenschaften festlegen.

Das Backing target und das Plugin-Ziel (falls unterschiedlich) werden durch den Befehl erstellt, sofern sie nicht bereits existieren. Projekte sollten im Allgemeinen zulassen, dass sie durch den Befehl erstellt werden, so dass sie als der entsprechende Zieltyp erstellt werden. Wenn die zugrundeliegende target eine statische Bibliothek ist, wird das Plugin auch als statische Bibliothek erstellt. Handelt es sich bei der zugrundeliegenden target um eine Shared Library, wird das Plugin als Modulbibliothek erstellt. Wenn ein vorhandenes target übergeben wird und es sich um ein ausführbares Ziel handelt, wird kein Plugin erstellt. Wenn Sie beabsichtigen, immer direkt mit dem unterstützenden Ziel zu verlinken und kein Plugin benötigen, kann dieses durch Hinzufügen der Option NO_PLUGIN deaktiviert werden. Die Angabe von sowohl NO_PLUGIN als auch PLUGIN_TARGET ist ein Fehler.

In bestimmten Situationen kann es sein, 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-Target aufruft, sobald es erstellt wurde. Wenn NO_CREATE_PLUGIN_TARGET angegeben wird, muss auch PLUGIN_TARGET angegeben werden, um das Plugin-Target 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 seine eigene Implementierung der Plugin-Klasse bereitstellen möchte, sollte die Option NO_GENERATE_PLUGIN_SOURCE angegeben werden. Wird keine CLASS_NAME angegeben, wird standardmäßig URI verwendet, wobei die Punkte durch Unterstriche ersetzt und Plugin angehängt werden. Sofern das QML-Modul kein Plugin hat, wird der Klassenname als classname Zeile in der generierten qmldir-Datei aufgezeichnet. 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 einfache Laden der unterstützenden Bibliothek hinausgehen, werden Sie wahrscheinlich auch NO_PLUGIN_OPTIONAL hinzufügen wollen. Andernfalls überspringt die QML-Engine möglicherweise das Laden des Plugins, wenn sie feststellt, dass die zugrundeliegende Bibliothek bereits gelinkt ist.

Wenn das Schlüsselwort NO_PLUGIN angegeben wird, dann wird kein Plugin erstellt. Dieses Schlüsselwort ist daher inkompatibel mit allen Optionen, die das Plugin-Target anpassen, insbesondere 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 es nur dann voll nutzbar, wenn die zugehörige Bibliothek in die ausführbare Datei gelinkt wurde. Es ist im Allgemeinen schwer zu garantieren, dass ein Linker die Verknüpfung zu einer Bibliothek beibehält, die er als unbenutzt betrachtet.

Wenn das Schlüsselwort NO_PLUGIN_OPTIONAL angegeben wird, dann wird das Plugin in der generierten qmldir Datei als nicht-optional aufgezeichnet. Wenn die gesamte Funktionalität eines QML-Moduls in seinem Backing-Target implementiert ist und das Plugin-Target separat ist, dann kann das Plugin optional sein, was die Standardeinstellung und empfohlene Anordnung ist. Die automatisch generierte Plugin-Quelldatei erfüllt diese Anforderung. Wenn ein Projekt seine eigene .cpp Implementierung für das Plugin bereitstellt, bedeutet dies normalerweise, dass das NO_PLUGIN_OPTIONAL Schlüsselwort ebenfalls benötigt wird, da das Plugin mit ziemlicher Sicherheit Funktionen enthält, die das QML-Modul benötigt.

Automatische Typregistrierung

Die Typregistrierung wird automatisch für die C++-Quellen des Backing-Targets durchgeführt, die von AUTOMOC verarbeitet werden. Dabei wird eine Typeinfo-Datei im Ausgabeverzeichnis erzeugt, wobei der Dateiname der Name target mit angehängtem .qmltypes ist. Dieser Dateiname kann bei Bedarf mit der Option TYPEINFO geändert werden, was aber normalerweise nicht notwendig sein sollte. Der Dateiname wird auch als Eintrag typeinfo in der erzeugten qmldir-Datei gespeichert. Die automatische Typregistrierung kann mit der Option NO_GENERATE_QMLTYPES deaktiviert werden. In diesem Fall wird keine Typinfodatei erzeugt, aber es wird trotzdem erwartet, dass das Projekt eine Typinfodatei erzeugt und sie im selben Verzeichnis wie die erzeugte qmldir Datei ablegt.

OUTPUT_DIRECTORY gibt an, wo die Plugin-Bibliothek, qmldir und Typeinfo-Dateien erzeugt werden. Wenn dieses Schlüsselwort nicht angegeben wird, ist der Standardwert der Zielpfad (gebildet aus URI), der an den Wert der Variable QT_QML_OUTPUT_DIRECTORY angehängt wird. Wenn diese Variable nicht definiert ist, hängt der Standardwert vom Typ des unterstützenden Ziels ab. Bei ausführbaren Dateien ist der Wert der an ${CMAKE_CURRENT_BINARY_DIR} angehängte Zielpfad, während er bei anderen Zielen einfach ${CMAKE_CURRENT_BINARY_DIR} lautet. Wenn die Struktur des Quellbaums mit der Struktur der QML-Modul-Zielpfade übereinstimmt (was sehr empfehlenswert ist), wird QT_QML_OUTPUT_DIRECTORY oft nicht benötigt. Um der Struktur der Zielpfade zu entsprechen, müssen Sie Ihre Verzeichnisse genau so nennen wie die Segmente Ihres Modul-URIs. Wenn Ihr Modul-URI beispielsweise MyUpperCaseThing.mylowercasething lautet, müssen Sie ihn in ein Verzeichnis namens MyUpperCaseThing/mylowercasething/ stellen.

Die Notwendigkeit, das Schlüsselwort OUTPUT_DIRECTORY anzugeben, sollte selten sein, aber wenn es verwendet wird, ist es wahrscheinlich, dass der Aufrufer auch den IMPORT_PATH ergänzen muss, um sicherzustellen, dass Linting, die Zwischenspeicherkompilierung von QML-Quellen, der automatische Import von Plugins in statischen Builds und die Bereitstellung von importierten QML-Modulen für nicht-statische Builds korrekt funktionieren.

Qt Quick Designer-Kompatibilität

DESIGNER_SUPPORTED sollte angegeben werden, wenn das QML-Modul Qt Quick Designer unterstützt. Wenn dies der Fall ist, enthält die generierte Datei qmldir eine Zeile designersupported. Siehe Moduldefinition qmldir-Dateien, um zu erfahren, wie sich dies auf die Art und Weise auswirkt, wie Qt Quick Designer das Plugin behandelt.

Modulversionen synchron halten

Das Schlüsselwort FOLLOW_FOREIGN_VERSIONING bezieht sich auf Basistypen Ihrer eigenen C++-definierten QML-Typen, die sich in verschiedenen QML-Modulen befinden. Normalerweise stimmt das Versionsschema Ihres Moduls nicht mit dem des Moduls überein, das die Basistypen bereitstellt. Daher werden standardmäßig alle Revisionen der Basistypen in jedem Import Ihres Moduls verfügbar gemacht. Wenn FOLLOW_FOREIGN_VERSIONING angegeben wird, werden die Versionsinformationen, die den Basistypen und ihren Eigenschaften beigefügt sind, respektiert. Ein import MyModule 2.8 macht dann nur die versionierten Eigenschaften bis zur Version 2.8 aller Basistypen außerhalb von MyModule verfügbar. Dies ist vor allem dann nützlich, wenn Sie die Version Ihres Moduls mit anderen Modulen, auf denen Sie Typen basieren, synchron halten wollen. In diesem Fall möchten Sie vielleicht, dass Ihre benutzerdefinierten Typen keine Eigenschaften aus einem Basistyp eines Moduls mit einer höheren Version als der des importierten Typs zur Verfügung stellen.

C++-Namensräume des generierten Codes

Wenn ein Namespace mit dem Schlüsselwort NAMESPACE angegeben wird, wird der Plugin- und Registrierungscode in einem C++-Namespace dieses Namens generiert.

qmlimportscanner und NO_IMPORT_SCAN

Für statische Qt-Builds wird qmlimportscanner zur Konfigurationszeit ausgeführt, um die .qml Dateien eines QML-Moduls zu scannen und die QML-Importe zu identifizieren, die es verwendet (siehe qt_import_qml_plugins()). Für nicht-statische Qt-Builds, wenn das Ziel eine ausführbare Datei ist, wird ein ähnlicher Scan zur Build-Zeit durchgeführt, um die von Deployment-Skripten benötigten Informationen zu liefern (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, dass alle benötigten Plugins instanziiert und für statische Builds gelinkt sind. Bei nicht-statischen Builds muss das Projekt alle QML-Module, die von einem ausführbaren Ziel verwendet werden, manuell ausarbeiten und bereitstellen.

Argumente für qmltc

ENABLE_TYPE_COMPILER können verwendet werden, um .qml Dateien mit qmltc in C++ Quellcode zu kompilieren. Dateien mit der Quelleigenschaft QT_QML_SKIP_TYPE_COMPILER werden nicht nach C++ kompiliert.

TYPE_COMPILER_NAMESPACE Argument erlaubt es, den Namespace zu überschreiben, in dem qmltc Code generiert. Standardmäßig folgt der Namensraum des generierten Codes der Modulhierarchie, wie sie im URI dargestellt ist, z.B. MyModule für ein Modul mit URI MyModule oder com::example::Module für URI com.example.MyModule. Durch Angabe der Option TYPE_COMPILER_NAMESPACE kann der generierte Code stattdessen in einen benutzerdefinierten Namensraum gestellt werden, wobei verschiedene Unternamensräume durch ein "::" zu trennen sind, z. B. "MyNamespace::MySubnamespace" für den Namensraum MySubnamespace, der innerhalb des MyNamespace liegt. Abgesehen von dem "::" gelten die C++-Namensraumbenennungsregeln.

QMLTC_QMLTC_EXPORT_DIRECTIVE sollte mit QMLTC_EXPORT_FILE_NAME verwendet werden, wenn die von qmltc erzeugten Klassen aus der qml-Bibliothek exportiert werden sollen. Standardmäßig werden die von qmltc erzeugten Klassen nicht aus ihrer Bibliothek exportiert. Der Header, der das Exportmakro für die aktuelle Bibliothek definiert, kann als optionales Argument für QMLTC_EXPORT_FILE_NAME angegeben werden, während der Name des Exportmakros als Argument für QMLTC_QMLTC_EXPORT_DIRECTIVE angegeben werden sollte. Wenn kein zusätzliches Include erforderlich oder erwünscht ist, z.B. wenn der Header des Exportmakros bereits indirekt von einer Basisklasse inkludiert wird, dann kann die Option QMLTC_EXPORT_FILE_NAME weggelassen werden.