qt_generate_deploy_qml_app_script

Erzeugt ein Deployment-Skript für eine QML-Anwendung.

Der Befehl ist in der Qml Komponente des Qt6 Pakets definiert, das so geladen werden kann:

find_package(Qt6 REQUIRED COMPONENTS Qml)

Dieser Befehl wurde in Qt 6.3 eingeführt.

Synopse

qt_generate_deploy_qml_app_script(
    TARGET <target>
    OUTPUT_SCRIPT <var>
    [NO_UNSUPPORTED_PLATFORM_ERROR]
    [NO_TRANSLATIONS]
    [NO_COMPILER_RUNTIME]
    [DEPLOY_TOOL_OPTIONS ...]
    [DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM]
    [MACOS_BUNDLE_POST_BUILD]
    [PRE_INCLUDE_REGEXES regexes...]
    [PRE_EXCLUDE_REGEXES regexes...]
    [POST_INCLUDE_REGEXES regexes...]
    [POST_EXCLUDE_REGEXES regexes...]
    [POST_INCLUDE_FILES files...]
    [POST_EXCLUDE_FILES files...]
)

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

Beschreibung

Die Installation eines ausführbaren Targets, das auch ein QML-Modul ist, erfordert die Bereitstellung einer Reihe von Dingen zusätzlich zu dem Target selbst. Qt-Bibliotheken und andere Bibliotheken aus dem Projekt, Qt-Plugins und die Runtime-Teile aller QML-Module, die die Anwendung verwendet, müssen möglicherweise ebenfalls installiert werden. Das installierte Layout wird sich bei macOS-App-Bundles auch von dem anderer Plattformen unterscheiden. qt_generate_deploy_qml_app_script() ist ein Komfort-Befehl, der diesen Prozess vereinfachen soll, ähnlich dem, was qt_generate_deploy_app_script() für Nicht-QML-Anwendungen tut.

Der Befehl erwartet, dass die Anwendung der von Qt empfohlenen Struktur des Installationsverzeichnisses ziemlich genau folgt. Diese Struktur basiert auf dem Standard-Installationslayout von CMake, wie es von GNUInstallDirs bestimmt wird (außer für macOS-App-Bundles, die stattdessen den Anforderungen von Apple folgen). QML-Module werden an dem für die jeweilige Plattform geeigneten Ort installiert. Bei macOS-Bundles wird die Datei qmldir jedes QML-Moduls im entsprechenden Unterverzeichnis unter Resources/qml und das Plugin des Moduls (falls vorhanden) unter PlugIns installiert. Es wird davon ausgegangen, dass das App-Bundle direkt am Basisinstallationsort installiert wird (siehe das Beispiel weiter unten). Für alle anderen Plattformen werden sowohl qmldir als auch das Plugin des Moduls im entsprechenden Unterverzeichnis unterhalb von qml installiert, das wiederum relativ zum Basisinstallationsort ist.

qt_generate_deploy_qml_app_script() erzeugt ein Skript, dessen Name in der durch die Option OUTPUT_SCRIPT benannten Variable gespeichert wird. Dieses Skript wird nur zur CMake-Generierungszeit geschrieben. Es ist für die Verwendung mit dem install(SCRIPT) -Befehl vorgesehen, der nach der Installation des Ziels der Anwendung mit install(TARGETS) erfolgen sollte.

Das Deployment-Skript wird qt_deploy_qml_imports() mit einem geeigneten Satz von Optionen für das Standard-Installationslayout aufrufen. Für macOS-App-Bundles und Windows-Ziele ruft es dann auch qt_deploy_runtime_dependencies() auf, wiederum mit geeigneten Optionen für das Standard-Installationslayout.

Der Aufruf von qt_generate_deploy_qml_app_script() für eine Plattform, die nicht von qt_deploy_runtime_dependencies unterstützt wird, führt zu einem fatalen Fehler, es sei denn, die Option NO_UNSUPPORTED_PLATFORM_ERROR wird angegeben. Wenn die Option angegeben ist und das Projekt für eine nicht unterstützte Plattform erstellt wird, werden weder QML-Module noch reguläre Laufzeitabhängigkeiten installiert. Um sicherzustellen, dass die QML-Module dennoch installiert werden, geben Sie sowohl die Option NO_UNSUPPORTED_PLATFORM_ERROR als auch DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM an. Mit der letztgenannten Option wird sichergestellt, dass die QML-Module, die als Teil des Projekts erstellt wurden, trotzdem installiert werden.

Die Option MACOS_BUNDLE_POST_BUILD ermöglicht einen zusätzlichen Schritt, wenn target ein macOS-App-Bundle ist. Es wird eine Post-Build-Regel erstellt, die das Deployment-Skript verwendet, um genügend der importierten QML-Module bereitzustellen, damit die Anwendung direkt aus dem Build-Verzeichnis ausgeführt werden kann (im Wesentlichen nur die qmldir Dateien und Symlinks zu Plugins). Dies ist normalerweise wünschenswert, um die Entwicklung der Anwendung zu unterstützen. MACOS_BUNDLE_POST_BUILD wird für alle anderen Plattformen ignoriert.

Auf anderen Plattformen als macOS werden die Qt-Übersetzungen automatisch bereitgestellt. Um dieses Verhalten zu unterbinden, geben Sie NO_TRANSLATIONS an. Verwenden Sie qt_deploy_translations(), um Übersetzungen auf eine angepasste Weise zu verteilen.

Für Windows-Desktop-Anwendungen werden standardmäßig auch die erforderlichen Laufzeitdateien für den Compiler installiert. Um dies zu verhindern, geben Sie NO_COMPILER_RUNTIME an.

Seit Qt 6.7 können Sie DEPLOY_TOOL_OPTIONS verwenden, um zusätzliche Optionen an das zugrunde liegende Deployment-Tool zu übergeben. Dies hat nur dann eine Auswirkung, wenn das zugrunde liegende Deployment-Tool entweder macdeployqt oder windeployqt ist.

Die Optionen PRE_INCLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, POST_EXCLUDE_REGEXES, POST_INCLUDE_FILES und POST_EXCLUDE_FILES können angegeben werden, um die Bereitstellung von Laufzeitabhängigkeiten zu steuern. Diese Optionen gelten nicht für alle Plattformen und werden unverändert an qt_deploy_runtime_dependencies() weitergegeben.

Für das Deployment einer Nicht-QML-Anwendung sollte stattdessen qt_generate_deploy_app_script() verwendet werden. Es ist ein Fehler, sowohl qt_generate_deploy_qml_app_script() als auch qt_generate_deploy_app_script() für dasselbe Ziel aufzurufen.

Beispiel

Das folgende Beispiel zeigt, wie man eine QtQuick Anwendung einsetzt.

cmake_minimum_required(VERSION 3.16...3.22)
project(MyThings)

find_package(Qt6 6.3 REQUIRED COMPONENTS Core Qml)
qt_standard_project_setup()

qt_add_executable(MyApp main.cpp)
qt_add_qml_module(MyApp
    URI Application
    VERSION 1.0
    QML_FILES main.qml MyThing.qml
)

install(TARGETS MyApp
    BUNDLE  DESTINATION .
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)

qt_generate_deploy_qml_app_script(
    TARGET MyApp
    OUTPUT_SCRIPT deploy_script
    MACOS_BUNDLE_POST_BUILD
    NO_UNSUPPORTED_PLATFORM_ERROR
    DEPLOY_USER_QML_MODULES_ON_UNSUPPORTED_PLATFORM
)
install(SCRIPT ${deploy_script})

Das folgende Beispiel zeigt, wie man zusätzliche Optionen an das zugrundeliegende Deployment-Tool übergibt.

set(deploy_tool_options_arg "")
if(APPLE)
    set(deploy_tool_options_arg --hardened-runtime)
elseif(WIN32)
    set(deploy_tool_options_arg --no-compiler-runtime)
endif()

qt_generate_deploy_qml_app_script(
    ...
    DEPLOY_TOOL_OPTIONS ${deploy_tool_options_arg}
)
install(SCRIPT ${deploy_script})