qt_add_qml_plugin

Synopse

qt_add_qml_plugin(
    target
    [BACKING_TARGET backing_target]
    [STATIC | SHARED]
    [OUTPUT_DIRECTORY]
    [URI]
    [CLASS_NAME]
    [NO_GENERATE_PLUGIN_SOURCE]
    [NAMESPACE namespace]
)

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

Beschreibung

Dieser Befehl erstellt das mit einem QML-Modul verbundene Plugin-Ziel. Er wird normalerweise intern von qt_add_qml_module() aufgerufen, um das Plugin zu erstellen oder zu aktualisieren, das mit seinem Backing-Target verbunden ist. Sie sollten diese Funktion nicht direkt aufrufen, es sei denn, Sie haben besondere Umstände, die es erforderlich machen, das Ziel auf besondere Weise zu erstellen.

Die Dokumentation für qt_add_qml_module() beschreibt verschiedene Strukturmuster, wie die CMake-Targets, die mit einem QML-Modul verbunden sind, angeordnet werden können. Beachten Sie, dass Sie auch dann, wenn das QML-Modul kein separates Backing-Target hat und die gesamte Funktionalität direkt im Plugin implementiert ist (nicht die empfohlene Anordnung), qt_add_qml_module() und nicht qt_add_qml_plugin() aufrufen sollten.

Argumente

target gibt den Namen des Ziels an, das für das QML-Plugin verwendet werden soll. Wenn es nicht bereits existiert, wird es erstellt.

BACKING_TARGET gibt den Namen des Backing-Targets an, mit dem das Plugin verknüpft ist. Das Backing-Target kann dasselbe sein wie das Plugin target, in diesem Fall gibt es nur ein gemeinsames Target, aber das wird normalerweise nicht empfohlen (siehe qt_add_qml_module() für weitere Informationen). BACKING_TARGET sollte immer angegeben werden, es sei denn, es gibt besondere Umstände, die es erfordern, dass das Plugin-Target vor dem Backing-Target erstellt wird. Wenn BACKING_TARGET nicht angegeben wird, muss die Option URI angegeben werden.

Standardmäßig wird das Plugin mit einem Typ erstellt, der mit dem unterstützenden Ziel kompatibel ist. Handelt es sich bei dem unterstützenden Ziel um eine statische Bibliothek, wird das Plugin ebenfalls als statische Bibliothek erstellt. Handelt es sich bei dem unterstützenden Ziel um eine gemeinsam genutzte Bibliothek, wird das Plugin als Modulbibliothek erstellt. Wenn kein unterstützendes Ziel angegeben wird oder das Plugin kein separates unterstützendes Ziel hat, kann der Plugin-Typ entweder mit den Schlüsselwörtern STATIC oder SHARED angegeben werden. Wenn der Plugin-Typ nicht durch eine der vorangegangenen Bedingungen bestimmt wird, wird ein statisches Plugin erstellt, wenn Qt als statische Bibliothek gebaut wurde, oder andernfalls ein Modulbibliotheks-Plugin.

OUTPUT_DIRECTORY gibt das Verzeichnis an, in dem die Plugin-Bibliothek erstellt werden soll. Es sollte immer derselbe Ort sein wie die qmldir-Datei des QML-Moduls. Wenn OUTPUT_DIRECTORY nicht angegeben wird, wird es aus den auf BACKING_TARGET gespeicherten Informationen ermittelt, sofern verfügbar. Beachten Sie, dass dies ein anderes Verzeichnis sein kann als das der eigenen Bibliothek des Backing-Targets. Wenn ein Ausgabeverzeichnis nicht vom Backing Target bezogen werden kann, wird standardmäßig CMAKE_CURRENT_BINARY_DIR verwendet.

URI deklariert den Modulbezeichner des QML-Moduls, mit dem dieses Plugin verbunden ist. Der Modulbezeichner ist der (gepunktete URI-Notation) Bezeichner für das QML-Modul. Wenn URI nicht angegeben wird, muss BACKING_TARGET angegeben werden und die URI des unterstützenden Ziels muss dort aufgezeichnet sein (typischerweise durch einen früheren Aufruf von qt_add_qml_module()).

Jedes Plugin sollte eine C++ Klasse haben, die das Modul bei der QML Engine registriert. Standardmäßig generiert qt_add_qml_plugin() automatisch die Quellen für diese C++ Klasse und fügt sie der Liste der Quellen von target hinzu. Die generierte Plugin-Klasse erfüllt die Anforderungen, dass das Plugin optional ist (siehe Moduldefinition qmldir-Dateien). Der Klassenname wird wie folgt bestimmt:

• Wenn CLASS_NAME angegeben wurde, wird er verwendet. Er muss mit dem Namen übereinstimmen, der in der Datei qmldir des QML-Moduls verwendet wird.
• Wenn CLASS_NAME nicht angegeben wurde, aber BACKING_TARGET, wird der C++-Klassenname aus den für dieses Backing-Target aufgezeichneten Details übernommen. Diese Details werden normalerweise durch einen früheren Aufruf von qt_add_qml_module() aufgezeichnet und stimmen mit dem Namen überein, der in der erzeugten qmldir Datei verwendet wird. Dies ist der empfohlene Weg, um den Klassennamen in den meisten Szenarien bereitzustellen.
• Wenn der Klassenname immer noch nicht ermittelt werden kann, wird er auf die URI des Moduls gesetzt, wobei Punkte durch Unterstriche ersetzt und Plugin angehängt werden.

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

Bei einigen Plugins kann es erforderlich sein, die Plugin-Klasse manuell zu schreiben. Zum Beispiel kann es sein, dass das Plugin zusätzliche Initialisierungen durchführen oder Dinge registrieren muss, die nicht von der Standard-Plugin-Klasse implementiert werden. In solchen Fällen kann die Option NO_GENERATE_PLUGIN_SOURCE angegeben werden. Sie sind dann dafür verantwortlich, Ihre eigene C++-Plugin-Klasse zu schreiben und sie der target hinzuzufügen. Beachten Sie, dass es sehr unwahrscheinlich ist, dass das Plugin optional sein kann, wenn Sie Ihre eigene Plugin-Klasse schreiben müssen. Das wiederum bedeutet, dass das Schlüsselwort NO_PLUGIN_OPTIONAL im Aufruf von qt_add_qml_module() bei der Definition des QML-Moduls enthalten sein muss, da sonst die generierte Datei qmldir nicht korrekt ist. Vergewissern Sie sich, dass Ihre Plugin-Klasse denselben Klassennamen verwendet, der sich aus der oben beschriebenen Logik ergibt.