qt_deploy_runtime_dependencies

Stellt Qt-Plugins, Qt- und Nicht-Qt-Bibliotheken bereit, die von einer ausführbaren Datei benötigt werden.

Der Befehl ist in der Komponente Core des Pakets Qt6 definiert, das auf diese Weise geladen werden kann:

find_package(Qt6 REQUIRED COMPONENTS Core)

Im Gegensatz zu den meisten anderen CMake-Befehlen, die von Qt bereitgestellt werden, kann qt_deploy_runtime_dependencies() nur von einem Deployment-Skript aufgerufen werden. Es kann nicht direkt vom Projekt während der configure-Phase aufgerufen werden.

Dieser Befehl wurde in Qt 6.3 eingeführt.

Synopse

qt_deploy_runtime_dependencies(
    EXECUTABLE executable
    [ADDITIONAL_EXECUTABLES files...]
    [ADDITIONAL_LIBRARIES files...]
    [ADDITIONAL_MODULES files...]
    [GENERATE_QT_CONF]
    [BIN_DIR bin_dir]
    [LIBEXEC_DIR libexec_dir]
    [LIB_DIR lib_dir]
    [PLUGINS_DIR plugins_dir]
    [QML_DIR qml_dir]
    [VERBOSE]
    [NO_OVERWRITE]
    [NO_APP_STORE_COMPLIANCE]
    [NO_TRANSLATIONS]
    [NO_COMPILER_RUNTIME]
    [DEPLOY_TOOL_OPTIONS]
    [PRE_INCLUDE_REGEXES regexes...]
    [PRE_EXCLUDE_REGEXES regexes...]
    [POST_INCLUDE_REGEXES regexes...]
    [POST_EXCLUDE_REGEXES regexes...]
    [POST_INCLUDE_FILES files...]
    [POST_EXCLUDE_FILES files...]
)

Beschreibung

Bei der Installation einer Anwendung kann es wünschenswert sein, auch die Bibliotheken und Plugins zu installieren, von denen sie abhängt. Wenn es sich bei der Anwendung um ein macOS-App-Bundle oder eine ausführbare Windows-Datei handelt, kann qt_deploy_runtime_dependencies() von einem Skript zur Installationszeit aufgerufen werden, um diese Abhängigkeiten zu installieren. Es installiert systemfremde Qt-Bibliotheken sowie einen entsprechenden Satz von Qt-Plugins.

Unter Linux stellt der Befehl zusätzliche Bibliotheken bereit, die über die Qt-Bibliotheken hinausgehen, die im Projekt enthalten sind. Wenn der Befehl jedoch unter macOS oder Windows ausgeführt wird, verwendet er entweder macdeployqt oder windeployqt, wodurch nur Qt-spezifische Bibliotheken bereitgestellt werden.

Dieser Befehl berücksichtigt nur Laufzeitabhängigkeiten, für die Verknüpfungsbeziehungen in den zugrunde liegenden Binärdateien bestehen. Er stellt keine QML-Module bereit, siehe dazu qt_deploy_qml_imports().

Argumente

Die Option EXECUTABLE muss angegeben werden.

Das Argument executable sollte der Pfad zu der ausführbaren Datei im Build-Verzeichnis sein. Zum Beispiel ${CMAKE_CURRENT_BINARY_DIR}/MyApp.exe, oder dynamischer $<TARGET_FILE:MyApp>. Die Angabe von rohen Zielnamen, die nicht in einen Generator-Ausdruck wie <TARGET_FILE:> eingeschlossen sind, wird nicht unterstützt.

Für macOS-App-Bundles sollte das Argument executable ein Pfad zum Bundle-Verzeichnis sein, relativ zum Basisinstallationsort. Zum Beispiel MyApp.app, oder dynamischer $<TARGET_FILE_NAME:MyApp>.app. Die Angabe von rohen Zielnamen, die nicht in eine Generator-Epxression wie <TARGET_FILE_NAME:> eingeschlossen sind, wird nicht unterstützt.

Es kann auch wünschenswert sein, Abhängigkeiten für andere Binärdateien zu installieren, die mit executable zusammenhängen. Zum Beispiel könnten vom Projekt bereitgestellte Plugins weitere Abhängigkeiten haben, aber da diese Plugins nicht direkt mit der ausführbaren Datei gelinkt werden, wird qt_deploy_runtime_dependencies() sie nicht automatisch erkennen. Die Optionen ADDITIONAL_EXECUTABLES, ADDITIONAL_LIBRARIES und ADDITIONAL_MODULES können verwendet werden, um zusätzliche Binärdateien anzugeben, deren Abhängigkeiten ebenfalls bereitgestellt werden sollen (die Installation der genannten Binärdateien selbst liegt immer noch in der Verantwortung des Projekts). Die Benennung dieser Schlüsselwörter folgt den Konventionen von CMake, so dass Qt-Plugins mit ADDITIONAL_MODULES angegeben werden würden. Jeder Wert sollte ein Pfad relativ zum Basisinstallationsort sein. Die Werte können Generatorausdrücke verwenden, genau wie bei der Option EXECUTABLE. Die Angabe von rohen Zielnamen, die nicht in einen Generatorausdruck wie <TARGET_FILE_NAME:> verpackt sind, wird nicht unterstützt.

Bei der Installation einer Windows-Anwendung ist es üblich, eine qt.conf-Datei zu benötigen, wenn man der Standard-Installationsverzeichnisstruktur von CMake folgt. Wenn die Option GENERATE_QT_CONF angegeben wird, wird eine entsprechende qt.conf Datei in das gleiche Verzeichnis wie die executable geschrieben. Die Pfade in dieser qt.conf Datei basieren auf den CMAKE_INSTALL_xxxDIR Variablen, deren Standardwerte vom CMake GNUInstallDirs Modul bereitgestellt werden.

Sie können einige dieser Vorgaben mit den Parametern in der folgenden Tabelle überschreiben, die alle relativ zum Basisinstallationsverzeichnis sein sollten.

Eine qt.conf Datei wird immer geschrieben, wenn executable ein macOS App-Bundle ist, unabhängig davon, ob GENERATE_QT_CONF angegeben ist oder nicht. Die ..._DIR Optionen werden in diesem Fall ebenfalls ignoriert, da das Verzeichnis-Layout eines App-Bundles von Apples Anforderungen diktiert wird.

Eine ausführlichere Ausgabe über die Bereitstellungsschritte kann durch Angabe der Option VERBOSE aktiviert werden. Alternativ kann die Variable QT_ENABLE_VERBOSE_DEPLOYMENT im Projekt vor dem ersten Aufruf von find_package(Qt6) gesetzt werden, um die Ausgabe des Deployments standardmäßig ausführlich zu gestalten.

Der qt_deploy_runtime_dependencies() Befehl überschreibt standardmäßig bestehende Dateien (einige Warnungen können trotzdem ausgegeben werden). Verwenden Sie die Option NO_OVERWRITE, um das Überschreiben vorhandener Dateien zu verhindern. Beachten Sie, dass diese Option derzeit nur für macOS- und Windows-Bereitstellungen gilt.

Wenn executable ein macOS-App-Bundle ist, werden standardmäßig nur Qt-Plugins und Qt-Bibliotheken bereitgestellt, die den Anforderungen von Apples App Store entsprechen. Die Option NO_APP_STORE_COMPLIANCE kann angegeben werden, um diese Einschränkung zu deaktivieren.

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 bereitzustellen.

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 eine Auswirkung, wenn das zugrunde liegende Deployment-Tool entweder macdeployqt oder windeployqt ist.

Unter Linux basiert das Deployment von Laufzeitabhängigkeiten auf dem Befehl file(GET_RUNTIME_DEPENDENCIES) von CMake. Die Optionen PRE_INCLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, POST_EXCLUDE_REGEXES, POST_INCLUDE_FILES und POST_EXCLUDE_FILES sind nur in diesem Zusammenhang von Bedeutung und werden unverändert an file(GET_RUNTIME_DEPENDENCIES) weitergegeben. Einzelheiten finden Sie in der Dokumentation dieses Befehls.

Unter Linux werden Laufzeitabhängigkeiten, die sich in Systembibliotheksverzeichnissen befinden, standardmäßig nicht bereitgestellt. Wenn POST_EXCLUDE_REGEXES angegeben ist, wird dieser automatische Ausschluss nicht durchgeführt.

Der Standardwert von POST_EXCLUDE_REGEXES wird aus dem Wert von QT_DEPLOY_IGNORED_LIB_DIRS gebildet.

Beispiel

Das folgende Beispiel zeigt, wie man eine Anwendung MyApp bereitstellt.

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

find_package(Qt6 REQUIRED COMPONENTS Core)
qt_standard_project_setup()

qt_add_executable(MyApp main.cpp)

set_target_properties(MyApp PROPERTIES
    WIN32_EXECUTABLE TRUE
    MACOSX_BUNDLE TRUE
)

# App bundles on macOS have an .app suffix
if(APPLE)
    set(executable_path "$<TARGET_FILE_NAME:MyApp>.app")
else()
    set(executable_path "\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:MyApp>")
endif()

# Helper app, not necessarily built as part of this project.
qt_add_executable(HelperApp helper.cpp)
set(helper_app_path "\${QT_DEPLOY_BIN_DIR}/$<TARGET_FILE_NAME:HelperApp>")

# Generate a deployment script to be executed at install time
qt_generate_deploy_script(
    TARGET MyApp
    OUTPUT_SCRIPT deploy_script
    CONTENT "
qt_deploy_runtime_dependencies(
    EXECUTABLE \"${executable_path}\"
    ADDITIONAL_EXECUTABLES \"${helper_app_path}\"
    GENERATE_QT_CONF
    VERBOSE
)")

# Omitting RUNTIME DESTINATION will install a non-bundle target to CMAKE_INSTALL_BINDIR,
# which coincides with the default value of QT_DEPLOY_BIN_DIR used above, './bin'.
# Installing macOS bundles always requires an explicit BUNDLE DESTINATION option.
install(TARGETS MyApp HelperApp    # Install to CMAKE_INSTALL_PREFIX/bin/MyApp.exe
                                   #                           and ./binHelperApp.exe
        BUNDLE  DESTINATION .      # Install to CMAKE_INSTALL_PREFIX/MyApp.app/Contents/MacOS/MyApp
)
install(SCRIPT ${deploy_script})    # Add its runtime dependencies

Das folgende Beispiel zeigt, wie man den Parameter DEPLOY_TOOL_OPTIONS verwendet, um verschiedene Optionen an macdeployqt und windeployqt zu übergeben.

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()

# Generate a deployment script to be executed at install time
qt_generate_deploy_script(
    TARGET MyApp
    OUTPUT_SCRIPT deploy_script
    CONTENT "
qt_deploy_runtime_dependencies(
    EXECUTABLE \"${executable_path}\"
    DEPLOY_TOOL_OPTIONS "${deploy_tool_options_arg}"
    GENERATE_QT_CONF
    VERBOSE
)")