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. Andernfalls werden die gemeinsamen Bibliotheken 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 [options] [files]
Qt Deploy Tool 6.0.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 ICU, etc. are not in the bin directory, they need to be in the PATH
variable. 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 Qt specific options.
  -v, --version               Displays version information.
  --dir <directory>           Use directory instead of binary directory.
  --qmake <path>              Use specified qmake instead of qmake from PATH.
  --libdir <path>             Copy libraries to path.
  --plugindir <path>          Copy plugins 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.
  --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.
  --compiler-runtime          Deploy compiler runtime (Desktop only).
  --no-virtualkeyboard        Disable deployment of the Virtual Keyboard.
  --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.
  --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). Available libraries:
bluetooth concurrent core declarative designer designercomponents gui qthelp
multimedia multimediawidgets multimediaquick network nfc opengl openglwidgets
positioning printsupport qml qmltooling quick quickparticles quickwidgets script
scripttools sensors serialport sql svg svgwidgets test websockets widgets xml
webenginecore webengine webenginewidgets 3dcore 3drenderer 3dquick
3dquickrenderer 3dinput 3danimation 3dextras geoservices webchannel serialbus
webview

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, auf die Sie bei der Erstellung und Bereitstellung von Plugins für Qt-Anwendungen achten müssen.