qt_deploy_runtime_dependencies

Stellt Qt-Plugins sowie 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, die wie folgt geladen werden kann:

find_package(Qt6 REQUIRED COMPONENTS Core)

Im Gegensatz zu den meisten anderen von Qt bereitgestellten CMake-Befehlen kann „ qt_deploy_runtime_dependencies() “ nur aus einem Bereitstellungsskript heraus aufgerufen werden. Er kann nicht direkt vom Projekt während der Konfigurationsphase aufgerufen werden.

Dieser Befehl wurde in Qt 6.3 eingeführt.

Syntax

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_PLUGINS]                                  # since Qt 6.10
    [EXCLUDE_PLUGIN_TYPES type...]                # since Qt 6.10
    [INCLUDE_PLUGIN_TYPES type...]                # since Qt 6.10
    [EXCLUDE_PLUGINS name...]                     # since Qt 6.10
    [INCLUDE_PLUGINS name...]                     # since Qt 6.10
    [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. Handelt es sich bei der Anwendung um ein macOS-App-Bundle oder eine Windows-Ausführungsdatei, kann „ qt_deploy_runtime_dependencies() “ aus einem Skript zur Installationszeit aufgerufen werden, um diese Abhängigkeiten bereitzustellen. Dabei werden nicht zum System gehörende Qt-Bibliotheken sowie ein geeigneter Satz von Qt-Plugins installiert.

Unter Linux stellt der Befehl zusätzliche Bibliotheken bereit, die über die mit Qt verbundenen hinausgehen und im Projekt enthalten sind. Bei Ausführung unter macOS oder Windows verwendet der Befehl jedoch entweder ` macdeployqt ` oder ` windeployqt`, wodurch ausschließlich 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 den Pfad zur ausführbaren Datei im Build-Verzeichnis angeben. Zum Beispiel „ ${CMAKE_CURRENT_BINARY_DIR}/MyApp.exe “ oder, dynamischer, „ $<TARGET_FILE:MyApp> “. Die Angabe von reinen Zielnamen, die nicht in einem Generatorausdruck wie „ $<TARGET_FILE:> “ eingeschlossen sind, wird nicht unterstützt.

Bei 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 reinen Zielnamen, die nicht in einen Generatorausdruck eingeschlossen sind, wie z. B. $<TARGET_FILE_NAME:>, wird nicht unterstützt.

Es kann auch wünschenswert sein, Abhängigkeiten für andere Binärdateien zu installieren, die mit dem „ executable “ in Zusammenhang stehen. Beispielsweise könnten vom Projekt bereitgestellte Plugins weitere Abhängigkeiten haben, doch da diese Plugins nicht direkt mit der ausführbaren Datei verknüpft werden, erkennt „ qt_deploy_runtime_dependencies() “ sie nicht automatisch. Mit den Optionen „ ADDITIONAL_EXECUTABLES “, „ ADDITIONAL_LIBRARIES “ und „ ADDITIONAL_MODULES “ können zusätzliche Binärdateien angegeben werden, deren Abhängigkeiten ebenfalls bereitgestellt werden sollen (die Installation der genannten Binärdateien selbst liegt weiterhin in der Verantwortung des Projekts). Die Benennung dieser Schlüsselwörter folgt den CMake-Konventionen, sodass Qt-Plugins beispielsweise mit ` ADDITIONAL_MODULES` angegeben würden. Jeder Wert sollte ein relativer Pfad zum Basisinstallationsverzeichnis sein. Die Werte können Generatorausdrücke verwenden, genau wie bei der Option ` EXECUTABLE `. Die Angabe von reinen Zielnamen, die nicht in einen Generatorausdruck eingeschlossen sind, wie z. B. ` $<TARGET_FILE_NAME:> `, wird nicht unterstützt.

Bei der Installation einer Windows-Anwendung wird häufig eine qt.conf-Datei benötigt, wenn die Standard-Installationsverzeichnisstruktur von CMake befolgt wird. Wenn die Option „ GENERATE_QT_CONF “ angegeben wird, wird eine entsprechende „ qt.conf “-Datei in dasselbe Verzeichnis wie „ executable “ geschrieben. Die Pfade in dieser „ qt.conf “-Datei basieren auf den Variablen „ CMAKE_INSTALL_xxxDIR “, deren Standardwerte vom CMake-Modul „GNUInstallDirs“ bereitgestellt werden.

Sie können einige dieser Standardwerte mit den Parametern in der folgenden Tabelle überschreiben, wobei alle relativ zum Basisinstallationsverzeichnis angegeben werden müssen.

Es wird keine „ qt.conf “-Datei geschrieben, wenn „ executable “ ein macOS-App-Bundle ist; in diesem Fall werden sowohl die Option „ GENERATE_QT_CONF “ als auch die Option „ ..._DIR “ ignoriert. Die Verzeichnisstruktur eines App-Bundles wird durch die Anforderungen von Apple vorgegeben, und Qt findet Bibliotheken, Plugins und Ressourcen an diesen konventionellen Speicherorten auch ohne „ qt.conf “.

Eine ausführlichere Ausgabe zu den Bereitstellungsschritten 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 zur Bereitstellung standardmäßig ausführlich zu gestalten.

Der Befehl „ qt_deploy_runtime_dependencies() “ überschreibt standardmäßig vorhandene Dateien (es können dennoch einige Warnungen ausgegeben werden). Verwenden Sie die Option „ NO_OVERWRITE “, um das Überschreiben vorhandener Dateien zu verhindern. Beachten Sie, dass diese Option derzeit nur Deployments unter macOS und Windows betrifft.

Standardmäßig werden, wenn es sich bei „ executable “ um ein macOS-App-Bundle handelt, nur Qt-Plugins und Qt-Bibliotheken bereitgestellt, die den Anforderungen des Apple App Store entsprechen. Die Option „ NO_APP_STORE_COMPLIANCE “ kann angegeben werden, um diese Einschränkung zu deaktivieren.

Auf anderen Plattformen als macOS werden Qt-Übersetzungen automatisch bereitgestellt. Um dieses Verhalten zu unterbinden, geben Sie „ NO_TRANSLATIONS “ an. Verwenden Sie „qt_deploy_translations()“, um Übersetzungen auf individuelle Weise bereitzustellen.

Bei 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 mit ` DEPLOY_TOOL_OPTIONS ` zusätzliche Optionen an das zugrunde liegende Bereitstellungstool übergeben. Dies wirkt sich nur aus, wenn das zugrunde liegende Bereitstellungstool entweder `macdeployqt` oder `windeployqt` ist.

Unter Linux basiert die Bereitstellung 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 Kontext von Bedeutung und werden unverändert an ` file(GET_RUNTIME_DEPENDENCIES)` weitergeleitet. Einzelheiten finden Sie in der Dokumentation zu diesem Befehl.

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.

Steuerung der Bereitstellung von Qt-Plugins

Qt-Plugins werden automatisch in „QT_DEPLOY_PLUGINS_DIR“ bereitgestellt.

Sie können die Bereitstellung von Plugins mit dem Argument „ NO_PLUGINS “ deaktivieren.

Mit dem Argument „ INCLUDE_PLUGIN_TYPES “ können Sie alle Plugins eines bestimmten Typs einbeziehen. Mit dem Argument „ EXCLUDE_PLUGIN_TYPES “ können Sie alle Plugins eines bestimmten Typs ausschließen. Beide Argumente nehmen Plugin-Typen entgegen, z. B. „ imageformats “.

Sie können bestimmte Plugins mit den Argumenten ` INCLUDE_PLUGINS ` und ` EXCLUDE_PLUGINS` ein- oder ausschließen. Beide Argumente erwarten Plugin-Namen, zum Beispiel ` qjpeg`.

Beispiel

Das folgende Beispiel zeigt, wie eine Anwendung mit dem Parameter „ MyApp “ bereitgestellt wird.

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

find_package(Qt6 REQUIRED COMPONENTS Core)
qt_standard_project_setup()

# Keep the QT_DEPLOY_* references below for the generated script to expand,
# see \l {QTP0008}.
qt_policy(SET QTP0008 NEW)

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)
    # The CONTENT below is parsed when the generated script runs.
    # To preserve the code signing identity, it needs to be wrapped in escaped quotes.
    # In addition, all the options need to be wrapped into a single quoted string,
    # so that CMake doesn't replace each space with a semicolon in the generated text.
    set(deploy_tool_options_arg
        "-hardened-runtime \"-codesign=Developer ID Application: Joe Developer (1234567890)\""
    )
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
)")