qt_target_qml_quellen

Dieser Befehl wurde in Qt 6.2 eingeführt.

Synopsis

qt_target_qml_sources(
    target
    [QML_FILES ...]
    [RESOURCES ...]
    [PREFIX resource_path]
    [OUTPUT_TARGETS out_targets_var]
    [NO_LINT]
    [NO_CACHEGEN]
    [NO_QMLDIR_TYPES]
)

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

Beschreibung

qt_target_qml_sources() bietet die Möglichkeit, weitere Dateien zu einem QML-Modul hinzuzufügen, nachdem qt_add_qml_module() aufgerufen wurde. Normalerweise übergeben Sie den Satz von .qml Dateien und Ressourcen direkt an qt_add_qml_module(), aber in einigen Fällen kann es wünschenswert oder sogar notwendig sein, Dateien nach dem Aufruf von qt_add_qml_module() hinzuzufügen. Zum Beispiel können Sie Dateien basierend auf einem Ausdruck der Anweisung if oder aus Unterverzeichnissen, die nur hinzugefügt werden, wenn bestimmte Kriterien erfüllt sind, bedingt hinzufügen wollen. Möglicherweise möchten Sie einen Satz von Dateien mit anderen Eigenschaften als die anderen hinzufügen, z. B. mit einem anderen Ressourcen-Präfix oder mit deaktiviertem Linting und Bytecode-Kompilierung. Der Befehl qt_target_qml_sources() ermöglicht diese Szenarien.

Argumente

target muss das Backing-Target eines QML-Moduls sein, oder wenn das QML-Modul kein separates Backing-Target hat, muss es das Plugin-Target des Moduls sein.

QML_FILES ist eine Liste von .qml, .js und .mjs Dateien, die dem QML-Modul hinzugefügt werden sollen. Diese Option hat genau die gleiche Wirkung wie die Option QML_FILES des Befehls qt_add_qml_module(), einschließlich der automatischen Kompilierung in Bytecode und der Lint-Verarbeitung.

Die Optionen NO_CACHEGEN und NO_LINT haben ebenfalls die gleiche Wirkung wie bei qt_add_qml_module(). Sie deaktivieren die Bytecode-Kompilierung und die Lint-Verarbeitung für die mit QML_FILES aufgelisteten Dateien. Dieses Verhalten kann auch nur für einzelne Dateien mit Hilfe der Quelldateieigenschaften festgelegt werden.

NO_QMLDIR_TYPES verhindert, dass die QML_FILES als Typen zur generierten qmldir-Datei hinzugefügt werden.

RESOURCES hat genau die gleiche Wirkung wie die Option RESOURCES des Befehls qt_add_qml_module(). Sie stellt eine Liste von Dateien zur Verfügung, die der target als gewöhnliche Ressourcen hinzugefügt werden. Diese Dateien sind typischerweise Dinge wie Bilder, Shader usw., auf die sich der QML-Code in irgendeiner Weise bezieht.

Dateien, die dem Modul über QML_FILES oder RESOURCES hinzugefügt werden, werden unter dem gleichen Ressourcenpräfix und Zielpfad platziert, wie wenn sie mit dem Befehl qt_add_qml_module() hinzugefügt würden. Dies kann überschrieben werden, indem ein anderer Speicherort mit der Option PREFIX angegeben wird. Der Wert, der dem Schlüsselwort PREFIX folgt, wird direkt verwendet, ohne einen Zielpfad anzuhängen. Der endgültige Ressourcenpfad jeder Datei ist das Präfix plus der Pfad der Datei unterhalb von CMAKE_CURRENT_SOURCE_DIR. Die Eigenschaft QT_RESOURCE_ALIAS source file kann auch verwendet werden, um diesen relativen Pfad zu überschreiben.

qt_add_qml_module(backing
    URI Example
    VERSION 1.0
    RESOURCE_PREFIX /my.company.com/imports
)

qt_target_qml_sources(backing
    QML_FILES special/First.qml
    RESOURCES icons/logo.png
)

qt_target_qml_sources(backing
    PREFIX /other.company.com/debugging
    QML_FILES Inspector.qml
)

Im obigen Beispiel haben die Ressourcen des backing Ziels den folgenden Inhalt:

• /my.company.com/imports/Example/special/First.qml
• /my.company.com/imports/Example/icons/logo.png
• /other.company.com/debugging/Inspector.qml

OUTPUT_TARGETS ist analog zu der gleichen Option für qt_add_qml_module(). Verwenden Sie sie, um den Namen einer Variablen anzugeben, in der alle zusätzlichen Ziele gespeichert werden, die für statische Builds erstellt werden. Wenn target installiert wird, müssen diese zusätzlichen Targets ebenfalls installiert werden, um die Linking-Anforderungen zu erfüllen.

Eigenschaften der Quelldatei

Eine Reihe von Quelldateieigenschaften kann verwendet werden, um zu beeinflussen, wie jede einzelne .qml Datei an verschiedenen Punkten der QML-Modulverarbeitung behandelt wird. Diese überschreiben alle übergeordneten Optionen, die in Aufrufen von qt_target_qml_sources() oder qt_add_qml_module() angegeben werden. Alle diese Eigenschaften müssen gesetzt werden, bevor die Dateien mit einem dieser beiden Befehle hinzugefügt werden.

QT_QML_SKIP_QMLLINT kann für eine Quelldatei auf TRUE gesetzt werden, um zu verhindern, dass sie in die automatische qmllint-Verarbeitung einbezogen wird. Standardmäßig werden alle .qml Dateien in den Lint-Lauf des Ziels einbezogen, aber diese Option kann verwendet werden, um bestimmte Dateien auszuschließen.

QT_QML_SKIP_CACHEGEN verhindert ebenfalls, dass eine Quelldatei zu Bytecode kompiliert wird, wenn diese Eigenschaft auf TRUE gesetzt ist. Beachten Sie, dass die Datei trotzdem als Ressource in nicht kompilierter Form zu target hinzugefügt wird (siehe Zwischenspeichern von kompilierten QML-Quellen).

Setzen Sie die Eigenschaft QT_QML_SKIP_QMLDIR_ENTRY source file auf TRUE, um zu verhindern, dass diese QML- oder JavaScript-Datei als Typ zur Datei qmldir des QML-Moduls hinzugefügt wird (siehe Automatisches Erzeugen von qmldir und Typeinfo-Dateien). Dies wird normalerweise für eine Datei verwendet, die keinen öffentlichen Typ aufweist, wie z. B. eine private JavaScript-Datei. Für JavaScript-Dateien mit Namen in Großbuchstaben, die weder ECMAScript-Module sind noch als zustandslose Bibliotheken über .pragma library deklariert sind, sollten Sie diese Option in Betracht ziehen. Wenn Sie sie in die Datei qmldir aufnehmen, werden sie im Geltungsbereich jedes QML-Dokuments, das das Modul, zu dem sie gehören, explizit oder implizit importiert, neu ausgewertet.

Standardmäßig wird bei der Generierung der Datei qmldir für jede .qml Datei, die einen Typ bereitstellt, ein einzelner Typeneintrag erzeugt. Er erhält eine Versionsnummer X.0, wobei X die Hauptversion des QML-Moduls ist. Wenn das QML-Modul über PAST_MAJOR_VERSIONS verfügt, wird dasselbe Muster auch auf diese angewendet, wobei X.0 für jede frühere Hauptversion X angehängt wird. Für Situationen, in denen eine Datei stattdessen Typeneinträge für einen anderen Satz von Versionen bereitstellen muss (z. B. wenn sie zum ersten Mal in einer Minor-Patch-Version nach der Version .0 hinzugefügt wurde), geben Sie diese Versionen in der Eigenschaft QT_QML_SOURCE_VERSIONS der Quelldatei an. Für jede Version wird ein Typeintrag erstellt.

Wenn der Typ, den eine .qml -Datei bereitstellt, ein Singleton ist, setzen Sie die QT_QML_SINGLETON_TYPE -Eigenschaft auf TRUE. Ebenso kann die QT_QML_INTERNAL_TYPE -Quelleigenschaft der Datei auf TRUE gesetzt werden, um anzuzeigen, dass der Typ, den sie bereitstellt, ein interner Typ ist. Der Name des Typs selbst kann auch mit der Eigenschaft QT_QML_SOURCE_TYPENAME überschrieben werden. Alle drei Eigenschaften spiegeln sich in den Typeneinträgen der Datei in der erzeugten Datei qmldir wider. Die Quelleigenschaften müssen vor der Erstellung des Moduls, zu dem das Singleton gehört, festgelegt werden.

Alle Dateien, die mit QML_FILES oder RESOURCES aufgeführt sind, werden zu den Ressourcen von target hinzugefügt. Ihre Position in den Ressourcen besteht aus einem Basispunkt und einem relativen Pfad. Der Basispunkt ist standardmäßig die Verkettung des Ressourcenpräfixes des QML-Moduls und seines Zielpfades, aber diese können mit dem Argument PREFIX überschrieben werden. Der relative Pfad ist standardmäßig der Pfad der Datei relativ zur Zieleigenschaft von target's SOURCE_DIR. Dieser relative Pfad kann durch Setzen der Eigenschaft QT_RESOURCE_ALIAS für die Quelldatei überschrieben werden. Dies wird üblicherweise verwendet, um Dateien aus verschiedenen Verzeichnissen zu sammeln und sie in den Ressourcen an einem gemeinsamen Ort erscheinen zu lassen. Seit Qt 6.8 ist die Aktivierung von QTP0004 jedoch oft die bessere Option, wenn das Ziel ist, dass alle Dateien des QML-Moduls im impliziten Import gefunden werden können. In Fällen, in denen eine solche manuelle Einrichtung dennoch notwendig ist, ist es ratsam, NO_GENERATE_EXTRA_QMLDIRS an qt_add_qml_module zu übergeben, da die zusätzlichen qmldirs das Aliasing von Ressourcendateien nicht berücksichtigen.

set_source_files_properties(nested/way/down/File.qml PROPERTIES
    QT_RESOURCE_ALIAS File.qml
)
set_source_files_properties(TemplateFile.qml PROPERTIES
    QT_RESOURCE_ALIAS templates/File.qml
    QT_QML_SKIP_QMLDIR_ENTRY TRUE
    QT_QML_SKIP_QMLLINT TRUE
    QT_QML_SKIP_CACHEGEN TRUE
)
set_source_files_properties(FunnySingleton.qml PROPERTIES
    QT_QML_SINGLETON_TYPE TRUE
)
qt_add_qml_module(qt_target_qml_sources_example
    URI Example
    VERSION 2.3
    RESOURCE_PREFIX /my.company.com/imports
    NO_GENERATE_EXTRA_QMLDIRS
    QML_FILES
        nested/way/down/File.qml
        TemplateFile.qml
        FunnySingleton.qml
)

set_source_files_properties(some_old_thing.qml PROPERTIES
    QT_QML_SOURCE_VERSIONS "1.1;2.0"
    QT_QML_SOURCE_TYPENAME OldThing
)
set_source_files_properties(../../../images/button-types.png PROPERTIES
    QT_RESOURCE_ALIAS button-types.png
)
qt_target_qml_sources(qt_target_qml_sources_example
    QML_FILES some_old_thing.qml
    RESOURCES
        ../../../images/button-types.png
        doc/README.txt
)

Im obigen Beispiel haben die Ressourcen des Ziels qt_target_qml_sources_example den folgenden Inhalt:

• /my.company.com/imports/Example/File.qml
• /my.company.com/imports/Example/FunnySingleton.qml
• /my.company.com/imports/Example/templates/File.qml
• /my.company.com/imports/Example/some_old_thing.qml
• /my.company.com/imports/Example/button-types.png
• /my.company.com/imports/Example/doc/README.txt

Die erzeugte Datei qmldir enthält die folgenden Typeneinträge:

File 2.0 File.qml
singleton FunnySingleton 2.0 FunnySingleton.qml
OldThing 1.1 some_old_thing.qml
OldThing 2.0 some_old_thing.qml

pragma Singleton
import QtQml

QtObject {}