Qt für Windows - Bereitstellung

Diese Dokumentation beschreibt den Bereitstellungsprozess für Windows. Wir beziehen uns im gesamten Dokument auf die Plug & Paint-Beispielanwendung, um den Bereitstellungsprozess zu demonstrieren.

Das Windows-Bereitstellungswerkzeug

Das Windows Deployment Tool windeployqt wurde entwickelt, um den Prozess der Erstellung eines Deployment-Ordners zu automatisieren, der die Qt-bezogenen Abhängigkeiten (Bibliotheken, QML-Importe, Plugins und Übersetzungen) enthält, die für die Ausführung der Anwendung in diesem Ordner erforderlich sind. Es erstellt einen Installationsbaum für Windows-Desktop-Anwendungen, der sich leicht in ein Installationspaket einbinden lässt.

Das Tool ist unter QTDIR/bin/windeployqt zu finden. Es muss innerhalb der Build-Umgebung ausgeführt werden, um korrekt zu funktionieren. Bei Verwendung von Qt Online Installer sollte das Skript QTDIR/bin/qtenv2.bat zum Einrichten verwendet werden.

windeployqt nimmt eine .exe Datei oder ein Verzeichnis, das eine .exe Datei enthält, als Argument und durchsucht die ausführbare Datei nach Abhängigkeiten. Wenn ein Verzeichnis mit dem Argument --qmldir übergeben wird, verwendet windeployqt das Tool qmlimportscanner, um die QML-Dateien in diesem Verzeichnis auf QML-Importabhängigkeiten zu überprüfen. Identifizierte Abhängigkeiten werden dann in das Verzeichnis der ausführbaren Datei kopiert.

Falls Qt mit ausgeschaltetem configure-Schalter -relocatable gebaut wurde, ersetzt windeployqt die hartcodierten lokalen Pfade in Qt6Core.dll durch relative Pfade.

Bei Windows-Desktop-Anwendungen werden die erforderlichen Laufzeitdateien für den Compiler ebenfalls standardmäßig in den Ordner deployable kopiert (sofern nicht die Option --no-compiler-runtime angegeben ist). Im Falle von Release-Builds mit Microsoft Visual C++ handelt es sich dabei um die Visual C++ Redistributable Packages, die für die rekursive Installation durch das Installationsprogramm der Anwendung auf dem Zielrechner vorgesehen sind. Ansonsten werden die Shared Libraries der Compiler-Laufzeit verwendet.

Die Anwendung kann zusätzliche Bibliotheken von Drittanbietern erfordern (z. B. Datenbankbibliotheken), die von windeployqt nicht berücksichtigt werden.

Zusätzliche Argumente sind in der Hilfeausgabe des Tools beschrieben:

Usage: windeployqt.exe [options] [files]
Qt Deploy Tool 6.10.0

The simplest way to use windeployqt is to add the bin directory of your Qt
installation (e.g. <QT_DIR\bin>) to the PATH variable and then run:
windeployqt <path-to-app-binary>

If your application uses Qt Quick, run:
windeployqt --qmldir <path-to-app-qml-files> <path-to-app-binary>

Options:
 -?, -h, --help                            Displays help on commandline
                                           options.
 --help-all                                Displays help, including generic Qt
                                           options.
 -v, --version                             Displays version information.
 --dir <directory>                         Use directory instead of binary
                                           directory.
 --qmake <path>                            Use specified qmake instead of
                                           qmake from PATH. Deprecated, use
                                           qtpaths instead.
 --qtpaths <path>                          Use specified qtpaths.exe instead
                                           of qtpaths.exe from PATH.
 --libdir <path>                           Copy libraries to path.
 --plugindir <path>                        Copy plugins to path.
 --translationdir <path>                   Copy translations to path.
 --qml-deploy-dir <path>                   Copy qml files to path.
 --debug                                   Assume debug binaries.
 --release                                 Assume release binaries.
 --pdb                                     Deploy .pdb files (MSVC).
 --force                                   Force updating files.
 --dry-run                                 Simulation mode. Behave normally,
                                           but do not copy/update any files.
 --no-patchqt                              Do not patch the Qt6Core library.
 --ignore-library-errors                   Ignore errors when libraries cannot
                                           be found.
 --no-plugins                              Skip plugin deployment.
 --include-soft-plugins                    Include in the deployment all
                                           relevant plugins by taking into
                                           account all soft dependencies.
 --skip-plugin-types <plugin types>        A comma-separated list of plugin
                                           types that are not deployed
                                           (qmltooling,generic).
 --add-plugin-types <plugin types>         A comma-separated list of plugin
                                           types that will be added to
                                           deployment
                                           (imageformats,iconengines)
 --include-plugins <plugins>               A comma-separated list of
                                           individual plugins that will be
                                           added to deployment (scene2d,qjpeg)
 --exclude-plugins <plugins>               A comma-separated list of
                                           individual plugins that will not be
                                           deployed (qsvg,qpdf)
 --no-libraries                            Skip library deployment.
 --qmldir <directory>                      Scan for QML-imports starting from
                                           directory.
 --qmlimport <directory>                   Add the given path to the QML
                                           module search locations.
 --no-quick-import                         Skip deployment of Qt Quick
                                           imports.
 --translations <languages>                A comma-separated list of languages
                                           to deploy (de,fi).
 --no-translations                         Skip deployment of translations.
 --no-system-d3d-compiler                  Skip deployment of the system D3D
                                           compiler.
 --no-system-dxc-compiler                  Skip deployment of the system DXC
                                           (dxcompiler.dll, dxil.dll).
 --compiler-runtime                        Deploy compiler runtime (Desktop
                                           only).
 --no-compiler-runtime                     Do not deploy compiler runtime
                                           (Desktop only).
 --json                                    Print to stdout in JSON format.
 --no-opengl-sw                            Do not deploy the software
                                           rasterizer library.
 --no-ffmpeg                               Do not deploy the FFmpeg libraries.
 --force-openssl                           Deploy openssl plugin but ignore
                                           openssl library dependency
 --openssl-root <directory>                Directory containing openSSL
                                           libraries.
 --list <option>                           Print only the names of the files
                                           copied.
                                           Available options:
                                            source:   absolute path of the
                                           source files
                                            target:   absolute path of the
                                           target files
                                            relative: paths of the target
                                           files, relative
                                                      to the target directory
                                            mapping:  outputs the source and
                                           the relative
                                                      target, suitable for use
                                           within an
                                                      Appx mapping file
 --verbose <level>                         Verbose level (0-2).

Qt libraries can be added by passing their name (-xml) or removed by passing
the name prepended by --no- (--no-xml).

Arguments:
[files]                                   Binaries or directory containing
                                          the binary.

Statische Verknüpfung

Um statische Anwendungen zu erstellen, bauen Sie Qt statisch, indem Sie Qt mit -static konfigurieren:

cd C:\path\to\Qt
configure -static <any other options you need>

Wenn Sie Qt später neu konfigurieren und von derselben Stelle aus neu erstellen müssen, stellen Sie sicher, dass alle Spuren der vorherigen Konfiguration entfernt werden, indem Sie das Build-Verzeichnis aufrufen und nmake distclean oder mingw32-make distclean ausführen, bevor Sie configure erneut ausführen.

Verknüpfen der Anwendung mit der statischen Version von Qt

Als Beispiel wird in diesem Abschnitt das Plug & Paint Beispiel statisch erstellt.

Sobald Qt die Erstellung abgeschlossen hat, bauen Sie die Plug & Paint-Anwendung. Zuerst müssen wir in das Verzeichnis wechseln, das die Anwendung enthält:

cd examples\tools\plugandpaint

Führen Sie qmake aus, um ein neues Makefile für die Anwendung zu erstellen, und führen Sie einen sauberen Build durch, um die statisch gelinkte ausführbare Datei zu erstellen:

nmake clean
qmake -config release
nmake

Wahrscheinlich wollen Sie gegen die Release-Bibliotheken linken, und Sie können dies beim Aufruf von qmake angeben. Wenn nun alles fehlerfrei kompiliert und gelinkt wurde, sollten wir eine plugandpaint.exe Datei haben, die bereit für die Bereitstellung ist. Um zu überprüfen, ob die Anwendung über die erforderlichen Bibliotheken verfügt, kopieren Sie die ausführbare Datei auf einen Rechner, auf dem weder Qt noch andere Qt-Anwendungen installiert sind, und führen Sie sie auf diesem Rechner aus.

Denken Sie daran, dass, wenn Ihre Anwendung von compilerspezifischen Bibliotheken abhängt, diese trotzdem zusammen mit Ihrer Anwendung weiterverteilt werden müssen. Sie können mit dem Tool depends überprüfen, mit welchen Bibliotheken Ihre Anwendung verlinkt ist. Weitere Informationen finden Sie im Abschnitt Anwendungsabhängigkeiten.

Da wir Plugins nicht mit dem Ansatz der statischen Verknüpfung bereitstellen können, ist die von uns vorbereitete Anwendung unvollständig. Sie wird zwar ausgeführt, aber die Funktionalität ist aufgrund der fehlenden Plugins deaktiviert. Um Plugin-basierte Anwendungen bereitzustellen, sollten wir den Shared-Library-Ansatz verwenden.

Gemeinsam genutzte Bibliotheken

Bei der Bereitstellung der Anwendung plugandpaint mit dem Shared-Libraries-Ansatz gibt es zwei Herausforderungen: Die Qt-Laufzeitumgebung muss zusammen mit der ausführbaren Datei der Anwendung korrekt verteilt werden, und die Plugins müssen an der richtigen Stelle auf dem Zielsystem installiert werden, damit die Anwendung sie finden kann.

Qt als gemeinsam genutzte Bibliothek erstellen

In diesem Beispiel wird davon ausgegangen, dass Qt als Shared Library installiert ist, was bei der Installation von Qt standardmäßig der Fall ist, und zwar im Verzeichnis C:\path\to\Qt.

Verknüpfen der Anwendung mit Qt als Shared Library

Nachdem wir sichergestellt haben, dass Qt als Shared Library installiert ist, können wir die Anwendung plugandpaint erstellen. Zuerst müssen wir in das Verzeichnis wechseln, das die Anwendung enthält:

cd examples\tools\plugandpaint

Führen Sie nun qmake aus, um ein neues Makefile für die Anwendung zu erstellen, und führen Sie einen sauberen Build durch, um die dynamisch gelinkte ausführbare Datei zu erstellen:

nmake clean
qmake -config release
nmake

Damit wird die Kernanwendung gebaut, die folgenden Schritte bauen die Plugins:

cd ..\plugandpaint/plugins
nmake clean
qmake -config release
nmake

Wenn alles ohne Fehler kompiliert und gelinkt wurde, erhalten wir eine ausführbare Datei plugandpaint.exe und die Plugin-Dateien pnp_basictools.dll und pnp_extrafilters.dll.

Erstellen des Anwendungspakets

Um die Anwendung bereitzustellen, müssen wir sicherstellen, dass wir die relevanten Qt-DLLs (die den in der Anwendung verwendeten Qt-Modulen entsprechen) und das Windows-Plattform-Plugin, qwindows.dll, sowie die ausführbare Datei in denselben Verzeichnisbaum im Unterverzeichnis release kopieren.

Im Gegensatz zu den Benutzer-Plugins müssen Qt-Plugins in Unterverzeichnissen abgelegt werden, die dem Plugin-Typ entsprechen. Der richtige Ort für das Plattform-Plugin ist ein Unterverzeichnis namens platforms. Der Abschnitt Qt Plugins enthält weitere Informationen über Plugins und wie Qt nach ihnen sucht.

Wenn dynamisches OpenGL verwendet wird, möchten Sie vielleicht zusätzlich die Bibliothek für softwarebasiertes OpenGL einbinden, wenn die Anwendung damit kompatibel ist.

Wenn Qt so konfiguriert wurde, dass es gegen ICU oder OpenSSL linkt, müssen die entsprechenden DLLs ebenfalls dem Ordner release hinzugefügt werden. Die Binärpakete für Qt unter Windows erfordern dies jedoch. Für weitere Details, siehe auch Bibliotheken von Drittanbietern.

Denken Sie daran, dass, wenn Ihre Anwendung von compilerspezifischen Bibliotheken abhängt, diese zusammen mit Ihrer Anwendung weiterverteilt werden müssen. Sie können mit dem Tool depends überprüfen, welche Bibliotheken Ihre Anwendung verknüpft. Weitere Informationen finden Sie im Abschnitt Anwendungsabhängigkeiten.

Wir werden uns in Kürze mit den Plugins befassen, aber zunächst wollen wir prüfen, ob die Anwendung in einer bereitgestellten Umgebung funktioniert: Kopieren Sie entweder die ausführbare Datei und die Qt-DLLs auf einen Rechner, auf dem weder Qt noch irgendwelche Qt-Anwendungen installiert sind, oder stellen Sie, wenn Sie auf dem Build-Rechner testen wollen, sicher, dass dieser Rechner kein Qt in seiner Umgebung hat.

Wenn die Anwendung ohne Probleme startet, haben wir erfolgreich eine dynamisch gelinkte Version der Anwendung plugandpaint erstellt. Die Funktionalität der Anwendung wird jedoch noch nicht zur Verfügung stehen, da wir die zugehörigen Plugins noch nicht implementiert haben.

Plugins funktionieren anders als normale DLLs, daher können wir sie nicht einfach in dasselbe Verzeichnis wie die ausführbare Datei unserer Anwendung kopieren, wie wir es mit den Qt-DLLs getan haben. Bei der Suche nach Plugins sucht die Anwendung in einem Unterverzeichnis plugins innerhalb des Verzeichnisses der ausführbaren Datei der Anwendung.

Um die Plugins für unsere Anwendung verfügbar zu machen, müssen wir also das Unterverzeichnis plugins erstellen und die entsprechenden DLLs rüberkopieren:

plugins\pnp_basictools.dll
plugins\pnp_extrafilters.dll

Ein Archiv, das alle Qt-DLLs und anwendungsspezifischen Plugins enthält, die für die Ausführung der Plug & Paint-Anwendung erforderlich sind, müsste die folgenden Dateien enthalten:

Je nachdem, welche Funktionen die Anwendung verwendet, können weitere Plugins erforderlich sein (iconengines, imageformats).

Darüber hinaus muss das Archiv die folgenden compilerspezifischen Bibliotheken enthalten (unter der Annahme von Visual Studio 17 (2022)):

Wenn dynamisches OpenGL verwendet wurde, dann kann das Archiv zusätzlich enthalten:

Wenn Qt für die Verwendung von ICU konfiguriert wurde, muss das Archiv Folgendes enthalten:

Um zu überprüfen, ob die Anwendung nun erfolgreich bereitgestellt werden kann, können Sie dieses Archiv auf einem Rechner ohne Qt und ohne installierten Compiler entpacken und versuchen, es auszuführen.

Eine Alternative zum Ablegen der Plugins im Unterverzeichnis plugins ist das Hinzufügen eines benutzerdefinierten Suchpfades beim Starten Ihrer Anwendung mit QCoreApplication::addLibraryPath() oder QCoreApplication::setLibraryPaths().

QCoreApplication::addLibraryPath("C:/some/other/path");

Ein Vorteil der Verwendung von Plugins ist, dass sie leicht für eine ganze Familie von Anwendungen verfügbar gemacht werden können.

Oft ist es am praktischsten, den Pfad in der Funktion main() der Anwendung hinzuzufügen, gleich nachdem das Objekt QApplication erstellt wurde. Sobald der Pfad hinzugefügt ist, wird die Anwendung ihn nach Plugins durchsuchen, zusätzlich zur Suche im Unterverzeichnis plugins im Verzeichnis der Anwendung selbst. Es kann eine beliebige Anzahl von zusätzlichen Pfaden hinzugefügt werden.

Manifest-Dateien

Wenn Sie eine mit Visual Studio kompilierte Anwendung bereitstellen, sind einige zusätzliche Schritte erforderlich.

Zunächst muss die Manifestdatei kopiert werden, die beim Linken der Anwendung erstellt wurde. Diese Manifestdatei enthält Informationen über die Abhängigkeiten der Anwendung von Side-by-Side-Assemblies, wie z. B. die Laufzeitbibliotheken.

Die Manifestdatei muss in denselben Ordner kopiert werden wie die ausführbare Datei der Anwendung. Sie brauchen die Manifestdateien für gemeinsam genutzte Bibliotheken (DLLs) nicht zu kopieren, da sie nicht verwendet werden.

Wenn die gemeinsam genutzte Bibliothek Abhängigkeiten hat, die sich von der Anwendung, die sie verwendet, unterscheiden, muss die Manifestdatei in die DLL-Binärdatei eingebettet werden. Für die Einbettung von Manifesten stehen die folgenden CONFIG Optionen zur Verfügung:

embed_manifest_dll
embed_manifest_exe

Beide Optionen sind standardmäßig aktiviert. Um embed_manifest_exe zu entfernen, fügen Sie

CONFIG -= embed_manifest_exe

zu Ihrer .pro-Datei hinzu.

Weitere Informationen zu Manifestdateien und Side-by-Side-Assemblies finden Sie auf der Dokumentationsseite zu Side-by-Side-Assemblies.

Der richtige Weg, die Laufzeitbibliotheken in Ihre Anwendung einzubinden, besteht darin, sicherzustellen, dass sie auf dem System des Endbenutzers installiert sind.

Um die Laufzeitbibliotheken auf dem System des Endbenutzers zu installieren, müssen Sie die entsprechende ausführbare Datei des Visual C++ Redistributable Package (VCRedist) in Ihre Anwendung aufnehmen und sicherstellen, dass sie ausgeführt wird, wenn der Benutzer Ihre Anwendung installiert.

Die weiterverteilbare Datei trägt den Namen vc_redist.x64.exe (64-bit) und befindet sich im Ordner <Visual Studio install path>/VC/redist/<language-code>.

Alternativ kann es auch aus dem Internet heruntergeladen werden, z. B. https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads.

Anwendungsabhängigkeiten

Zusätzliche Bibliotheken

Je nach Konfiguration müssen compilerspezifische Bibliotheken zusammen mit Ihrer Anwendung weiterverteilt werden.

Mit dem Dependency Walker können Sie überprüfen, mit welchen Bibliotheken Ihre Anwendung verknüpft ist. Dazu müssen Sie es nur wie folgt ausführen:

depends <application executable>

Sie erhalten dann eine Liste der Bibliotheken, von denen Ihre Anwendung abhängt, sowie weitere Informationen.

Wenn Sie sich den Release-Build der ausführbaren Plug & Paint-Datei (plugandpaint.exe) mit dem Tool depends ansehen, listet das Tool die folgenden unmittelbaren Abhängigkeiten zu Nicht-System-Bibliotheken auf:

Bei den Plugin-DLLs sind genau dieselben Abhängigkeiten aufgeführt.

Qt-Plugins

Alle Qt GUI Anwendungen benötigen ein Plugin, das die Qt Platform Abstraction (QPA) Schicht in Qt implementiert. Für Windows lautet der Name des Plattform-Plugins qwindows.dll. Diese Datei muss sich in einem bestimmten Unterverzeichnis (standardmäßig platforms) unter Ihrem Distributionsverzeichnis befinden. Alternativ ist es möglich, den Suchpfad anzupassen, den Qt verwendet, um seine Plugins zu finden, wie unten beschrieben.

Ihre Anwendung kann auch von einem oder mehreren Qt-Plugins abhängen, wie z.B. dem Druckunterstützungs-Plugin, dem JPEG-Bildformat-Plugin oder einem SQL-Treiber-Plugin. Vergewissern Sie sich, dass Sie alle Qt-Plugins, die Sie benötigen, mit Ihrer Anwendung verteilen. Ähnlich wie beim Plattform-Plugin muss sich jedes Plugin in einem bestimmten Unterverzeichnis (z. B. printsupport, imageformats oder sqldrivers) in Ihrem Distributionsverzeichnis befinden.

Die Bibliotheken sind verschiebbar, es sei denn, Qt wurde mit ausgeschaltetem configure-Schalter -relocatable gebaut. Die Suchpfade für Qt-Plugins sind relativ zum Speicherort der Bibliothek QtCore und es sind keine weiteren Schritte erforderlich, um sicherzustellen, dass die Plugins nach der Installation der Anwendung auf dem Zielcomputer gefunden werden.

Sicherstellen, dass Plugins gefunden werden, wenn nicht relozierbare Builds verwendet werden

Bei nicht lokalisierbaren Builds müssen zusätzliche Schritte unternommen werden, um sicherzustellen, dass die Plugins gefunden werden, nachdem die Anwendung auf dem Zielcomputer installiert worden ist.

In diesem Fall ist der Suchpfad für Qt-Plugins in der Bibliothek QtCore fest einprogrammiert. Standardmäßig ist das Plugins-Unterverzeichnis der Qt-Installation der erste Plugin-Suchpfad. Vorgegebene Pfade wie der Standardpfad haben jedoch einige Nachteile. Zum Beispiel kann es sein, dass sie auf dem Zielrechner nicht existieren. Aus diesem Grund müssen Sie verschiedene Alternativen prüfen, um sicherzustellen, dass die Qt-Plugins gefunden werden:

• Verwendung von qt.conf. Dieser Ansatz wird empfohlen, wenn Sie ausführbare Dateien an verschiedenen Orten haben, die die gleichen Plugins verwenden.
• Verwendung von QApplication::addLibraryPath() oder QApplication::setLibraryPaths(). Dieser Ansatz wird empfohlen, wenn Sie nur eine ausführbare Datei haben, die das Plugin verwendet.
• Verwendung eines Installationsprogramms eines Drittanbieters, um die fest kodierten Pfade in der Bibliothek QtCore zu ändern.

Wenn Sie einen benutzerdefinierten Pfad mit QApplication::addLibraryPath hinzufügen, könnte dieser wie folgt aussehen:

QCoreApplication::addLibraryPath("C:/customPath/plugins");

Dann würde QCoreApplication::libraryPaths() etwas wie dieses zurückgeben:

• C:/customPath/plugins
• C:/Qt/%VERSION%/plugins
• E:/myApplication/directory

Die ausführbare Datei sucht in diesen Verzeichnissen nach den Plugins, und zwar in der gleichen Reihenfolge wie QStringList, die von QCoreApplication::libraryPaths() zurückgegeben wird. Der neu hinzugefügte Pfad wird dem QCoreApplication::libraryPaths() vorangestellt, was bedeutet, dass er zuerst durchsucht wird. Wenn Sie jedoch QCoreApplication::setLibraryPaths() verwenden, können Sie bestimmen, welche Pfade in welcher Reihenfolge durchsucht werden sollen.

Das Dokument How to Create Qt Plugins beschreibt die Punkte, die Sie beim Erstellen und Bereitstellen von Plugins für Qt-Anwendungen beachten müssen.