Qt pour Windows - Déploiement
Cette documentation décrit le processus de déploiement pour Windows. Nous nous référons à l'application d'exemple Plug & Paint tout au long du document pour démontrer le processus de déploiement.
Note : Ajoutez votre répertoire de construction de Qt à la liste des répertoires exclus de toute application antivirus fonctionnant sur votre système.
L'outil de déploiement pour Windows
L'outil de déploiement Windows windeployqt est conçu pour automatiser le processus de création d'un dossier déployable contenant les dépendances liées à Qt(bibliothèques, importations QML, plugins et traductions) nécessaires à l'exécution de l'application à partir de ce dossier. Il crée une arborescence d'installation pour les applications de bureau Windows, qui peut être facilement intégrée dans un paquet d'installation.
L'outil se trouve à l'adresse QTDIR/bin/windeployqt et doit être exécuté dans l'environnement de construction pour fonctionner correctement. Lorsque vous utilisez Qt Online Installer, le script QTDIR/bin/qtenv2.bat doit être utilisé pour le configurer.
windeployqt prend en argument un fichier .exe ou un répertoire contenant un fichier .exe et recherche les dépendances dans l'exécutable. Si un répertoire est fourni avec l'argument --qmldir, windeployqt utilise l'outil qmlimportscanner pour analyser les fichiers QML à l'intérieur du répertoire à la recherche de dépendances d'importation QML. Les dépendances identifiées sont ensuite copiées dans le répertoire de l'exécutable.
Dans le cas où Qt XML a été construit avec le commutateur configure -relocatable désactivé, windeployqt remplace les chemins locaux codés en dur dans Qt6Core.dll par des chemins relatifs.
Pour les applications de bureau Windows, les fichiers d'exécution requis pour le compilateur sont également copiés dans le dossier déployable par défaut (sauf si l'option --no-compiler-runtime est spécifiée). Dans le cas des versions utilisant Microsoft Visual C++, il s'agit des Visual C++ Redistributable Packages, qui sont destinés à une installation récursive par le programme d'installation de l'application sur la machine cible. Sinon, les bibliothèques partagées du compilateur sont utilisées.
L'application peut nécessiter des bibliothèques tierces supplémentaires (par exemple, des bibliothèques de base de données), qui ne sont pas prises en compte par windeployqt.
Les arguments supplémentaires sont décrits dans l'aide de l'outil :
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.Liaison statique
Pour construire des applications statiques, construisez Qt statiquement en configurant Qt avec -static:
cd C:\path\to\Qt configure -static <any other options you need>
Si vous devez par la suite reconfigurer et reconstruire Qt Location au même endroit, assurez-vous que toutes les traces de la configuration précédente sont supprimées en entrant dans le répertoire de construction et en exécutant nmake distclean ou mingw32-make distclean avant d'exécuter à nouveau configure.
Lier l'application à la version statique de Qt
À titre d'exemple, cette section construira l'exemple Plug & Paint de manière statique.
Une fois que Qt a fini de se construire, construisez l'application Plug & Paint. Tout d'abord, nous devons aller dans le répertoire qui contient l'application :
cd examples\tools\plugandpaint
Exécutez qmake pour créer un nouveau fichier makefile pour l'application, et effectuez un clean build pour créer l'exécutable lié statiquement :
nmake clean
qmake -config release
nmakeVous voudrez probablement faire un lien avec les bibliothèques de version, et vous pouvez le spécifier lorsque vous invoquez qmake. Maintenant, si tout a été compilé et lié sans erreur, nous devrions avoir un fichier plugandpaint.exe prêt à être déployé. Pour vérifier que l'application dispose des bibliothèques requises, copiez l'exécutable sur une machine sur laquelle Qt ou toute autre application Qt n'est pas installée, et exécutez-le sur cette machine.
N'oubliez pas que si votre application dépend de bibliothèques spécifiques au compilateur, celles-ci doivent être redistribuées avec votre application. Vous pouvez vérifier les bibliothèques avec lesquelles votre application est liée en utilisant l'outil depends. Pour plus d'informations, lisez la section Dépendances de l'application.
Étant donné que nous ne pouvons pas déployer de plugins en utilisant l'approche de liaison statique, l'application que nous avons préparée est incomplète. Elle fonctionnera, mais les fonctionnalités seront désactivées en raison des plugins manquants. Pour déployer des applications basées sur des plugins, nous devons utiliser l'approche des bibliothèques partagées.
Bibliothèques partagées
Le déploiement de l'application plugandpaint à l'aide de l'approche des bibliothèques partagées pose deux problèmes : Le moteur d'exécution Qt Location doit être correctement redistribué avec l'exécutable de l'application, et les plugins doivent être installés au bon endroit sur le système cible pour que l'application puisse les trouver.
Construire Qt en tant que bibliothèque partagée
Pour cet exemple, nous supposons que Qt est installé en tant que bibliothèque partagée, ce qui est le cas par défaut lors de l'installation de Qt, dans le répertoire C:\path\to\Qt.
Lier l'application à Qt en tant que bibliothèque partagée
Après s'être assuré que Qt est construit en tant que bibliothèque partagée, nous pouvons construire l'application plugandpaint. Tout d'abord, nous devons aller dans le répertoire qui contient l'application :
cd examples\tools\plugandpaint
Lancez maintenant qmake pour créer un nouveau fichier makefile pour l'application, et faites un clean build pour créer l'exécutable lié dynamiquement :
nmake clean
qmake -config release
nmakeCeci construit l'application de base, ce qui suit construira les plugins :
cd ..\plugandpaint/plugins nmake clean qmake -config release nmake
Si tout a été compilé et lié sans erreur, nous obtiendrons un exécutable plugandpaint.exe et les fichiers de plugins pnp_basictools.dll et pnp_extrafilters.dll.
Création du paquetage de l'application
Pour déployer l'application, nous devons veiller à copier les DLL Qt pertinentes (correspondant aux modules Qt utilisés dans l'application) et le plugin pour la plate-forme Windows, qwindows.dll, ainsi que l'exécutable dans la même arborescence de répertoires, dans le sous-répertoire release.
Contrairement aux plugins utilisateur, les plugins Qt doivent être placés dans des sous-répertoires correspondant au type de plugin. L'emplacement correct pour le plugin de plateforme est un sous-répertoire nommé platforms. La section Plugins Qt contient des informations supplémentaires sur les plugins et sur la manière dont Qt les recherche.
Si l'OpenGL dynamique est utilisé, vous pouvez également inclure la bibliothèque requise pour l'OpenGL logiciel, si l'application est compatible avec elle.
Si Qt XML a été configuré pour se lier à ICU ou OpenSSL, les DLL respectives doivent également être ajoutées au dossier release. Mais les paquets binaires pour Qt sur Windows en ont besoin. Pour plus de détails, voir aussi Bibliothèques tierces.
N'oubliez pas que si votre application dépend de bibliothèques spécifiques au compilateur, celles-ci doivent être redistribuées avec votre application. Vous pouvez vérifier les bibliothèques avec lesquelles votre application est liée en utilisant l'outil depends. Pour plus d'informations, voir la section Dépendances de l'application.
Nous aborderons les plugins dans un instant, mais nous allons d'abord vérifier que l'application fonctionnera dans un environnement déployé : Copiez l'exécutable et les DLL Qt sur une machine sur laquelle Qt ou des applications Qt ne sont pas installées, ou si vous voulez tester sur la machine de construction, assurez-vous que la machine n'a pas Qt dans son environnement.
Si l'application démarre sans problème, nous avons réussi à créer une version liée dynamiquement de l'application plugandpaint. Mais la fonctionnalité de l'application sera toujours manquante puisque nous n'avons pas encore déployé les plugins associés.
Les plugins fonctionnent différemment des DLL normales, nous ne pouvons donc pas simplement les copier dans le même répertoire que l'exécutable de notre application, comme nous l'avons fait avec les DLL Qt. Lorsqu'elle recherche des plugins, l'application effectue une recherche dans un sous-répertoire plugins à l'intérieur du répertoire de l'exécutable de l'application.
Pour mettre les plugins à la disposition de notre application, nous devons donc créer le sous-répertoire plugins et copier les DLL correspondantes :
plugins\pnp_basictools.dll plugins\pnp_extrafilters.dll
Une archive distribuant toutes les DLL Qt et les plugins spécifiques à l'application nécessaires pour faire fonctionner l'application Plug & Paint, devrait inclure les fichiers suivants :
| Composant | Nom du fichier | |
|---|---|---|
| L'exécutable | plugandpaint.exe | |
| Le plugin Basic Tools | plugins\pnp_basictools.dll | |
| Le plugin ExtraFilters | plugins\pnp_extrafilters.dll | |
| Le plugin Qt pour la plateforme Windows | platforms\qwindows.dll | |
| Le plugin Qt Windows Vista style | styles\qwindowsvistastyle.dll | |
| Le module Qt Core | Qt6Core.dll | |
| Le module Qt GUI | Qt6Gui.dll | |
| Le module Qt Widgets | Qt6Widgets.dll | |
D'autres plugins peuvent être nécessaires en fonction des fonctionnalités utilisées par l'application (iconengines, imageformats).
En outre, l'archive doit contenir les bibliothèques spécifiques au compilateur suivantes (en supposant Visual Studio 17 (2022)) :
| Composant | Nom du fichier | |
|---|---|---|
| Le moteur d'exécution C | vcruntime140.dll | |
| Le temps d'exécution C | msvcp170.dll | |
Si l'OpenGL dynamique a été utilisé, l'archive peut contenir en plus :
| Composant | Nom du fichier | |
|---|---|---|
| Bibliothèque de rendu OpenGL Software | opengl32sw.dll | |
Enfin, si Qt a été configuré pour utiliser ICU, l'archive doit contenir :
| Nom du fichier | ||
|---|---|---|
| icudtXX.dll | icuinXX.dll | icuucXX.dll |
Pour vérifier que l'application peut maintenant être déployée avec succès, vous pouvez extraire cette archive sur une machine sans Qt et sans compilateur installé, et essayer de l'exécuter.
Une alternative au placement des plugins dans le sous-répertoire des plugins est d'ajouter un chemin de recherche personnalisé lorsque vous démarrez votre application en utilisant QCoreApplication::addLibraryPath() ou QCoreApplication::setLibraryPaths().
QCoreApplication::addLibraryPath("C:/some/other/path");
L'un des avantages de l'utilisation des plugins est qu'ils peuvent facilement être mis à la disposition de toute une famille d'applications.
Il est souvent plus pratique d'ajouter le chemin dans la fonction main() de l'application, juste après la création de l'objet QApplication. Une fois le chemin ajouté, l'application le recherchera pour les plugins, en plus du sous-répertoire plugins dans le répertoire de l'application. Il est possible d'ajouter un nombre illimité de chemins supplémentaires.
Fichiers manifestes
Lors du déploiement d'une application compilée avec Visual Studio, il y a quelques étapes supplémentaires à franchir.
Tout d'abord, nous devons copier le fichier manifeste créé lors de la liaison de l'application. Ce fichier manifeste contient des informations sur les dépendances de l'application par rapport aux assemblages côte à côte, tels que les bibliothèques d'exécution.
Le fichier manifeste doit être copié dans le même dossier que l'exécutable de l'application. Il n'est pas nécessaire de copier les fichiers manifestes pour les bibliothèques partagées (DLL), car elles ne sont pas utilisées.
Si la bibliothèque partagée a des dépendances différentes de celles de l'application qui l'utilise, le fichier manifeste doit être incorporé dans le binaire de la DLL. Les options suivantes de CONFIG sont disponibles pour intégrer les manifestes :
embed_manifest_dll embed_manifest_exe
Les deux options sont activées par défaut. Pour supprimer embed_manifest_exe, ajoutez
CONFIG -= embed_manifest_exe
à votre fichier .pro.
Pour plus d'informations sur les fichiers manifestes et les assemblages côte à côte, consultez la page de documentation sur les assemblages côte à côte.
La bonne façon d'inclure les bibliothèques d'exécution dans votre application est de s'assurer qu'elles sont installées sur le système de l'utilisateur final.
Pour installer les bibliothèques d'exécution sur le système de l'utilisateur final, vous devez inclure l'exécutable Visual C++ Redistributable Package (VCRedist) approprié avec votre application et vous assurer qu'il est exécuté lorsque l'utilisateur installe votre application.
Le redistribuable s'appelle vc_redist.x64.exe (64-bit) et se trouve dans le dossier <Visual Studio install path>/VC/redist/<language-code>.
Il peut également être téléchargé sur le web, par exemple à l'adresse https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads.
Remarque : l'application que vous livrez doit être compilée avec exactement la même version du compilateur et la même version du moteur d'exécution C. Cela permet d'éviter les erreurs de déploiement causées par des versions différentes du moteur d'exécution. Cela permet d'éviter les erreurs de déploiement causées par des versions différentes des bibliothèques d'exécution C.
Dépendances de l'application
Bibliothèques supplémentaires
Selon la configuration, des bibliothèques spécifiques au compilateur doivent être redistribuées avec votre application.
Vous pouvez vérifier quelles sont les bibliothèques avec lesquelles votre application est liée en utilisant l'outil Dependency Walker. Tout ce que vous avez à faire est de l'exécuter comme suit :
depends <application executable>
Vous obtiendrez une liste des bibliothèques dont votre application dépend, ainsi que d'autres informations.
Lorsque l'on examine la version de l'exécutable Plug & Paint (plugandpaint.exe) à l'aide de l'outil depends, l'outil répertorie les dépendances immédiates suivantes pour les bibliothèques non liées au système :
| Qt | Visual Studio 17 (2022) | Mingw-w64 |
|---|---|---|
|
|
Lorsque l'on regarde les DLL de plugin, les mêmes dépendances sont listées.
Plugins Qt
Toutes les applications Qt GUI nécessitent un plugin qui met en œuvre la couche Qt Platform Abstraction (QPA) dans Qt. Pour Windows, le nom du plugin de plate-forme est qwindows.dll. Ce fichier doit être situé dans un sous-répertoire spécifique (par défaut, platforms) de votre répertoire de distribution. Il est également possible d'ajuster le chemin de recherche utilisé par Qt pour trouver ses plugins, comme décrit ci-dessous.
Votre application peut également dépendre d'un ou plusieurs plugins Qt, tels que le plugin de support d'impression, le plugin de format d'image JPEG ou un plugin de pilote SQL. Veillez à distribuer tous les plugins Qt dont vous avez besoin avec votre application. Comme pour le plugin de plate-forme, chaque type de plugin doit se trouver dans un sous-répertoire spécifique (tel que printsupport, imageformats ou sqldrivers) de votre répertoire de distribution.
Les bibliothèques sont relocalisables, sauf si Qt XML a été construit avec le commutateur de configuration -relocatable désactivé. Les chemins de recherche des plugins Qt Location sont relatifs à l'emplacement de la bibliothèque QtCore et aucune étape supplémentaire n'est nécessaire pour s'assurer que les plugins sont trouvés après l'installation de l'application sur la machine cible.
S'assurer que les plugins sont trouvés lors de l'utilisation de constructions non relocalisables
Pour les constructions non relocalisables, des mesures supplémentaires doivent être prises pour s'assurer que les plugins sont trouvés après l'installation de l'application sur la machine cible.
Dans ce cas, le chemin de recherche des plugins Qt est codé en dur dans la bibliothèque QtCore. Par défaut, le sous-répertoire plugins de l'installation de Qt est le premier chemin de recherche des plugins. Cependant, les chemins prédéterminés comme celui par défaut présentent certains inconvénients. Par exemple, ils peuvent ne pas exister sur la machine cible. C'est pourquoi vous devez examiner plusieurs alternatives pour vous assurer que les plugins Qt sont trouvés :
- Utilisation de
qt.conf. Cette approche est recommandée si vous avez des exécutables à différents endroits qui partagent les mêmes plugins. - En utilisant QApplication::addLibraryPath() ou QApplication::setLibraryPaths(). Cette approche est recommandée si vous n'avez qu'un seul exécutable qui utilisera le plugin.
- Utiliser un utilitaire d'installation tiers pour modifier les chemins codés en dur dans la bibliothèque QtCore.
Si vous ajoutez un chemin personnalisé à l'aide de QApplication::addLibraryPath, il pourrait ressembler à ceci :
QCoreApplication::addLibraryPath("C:/customPath/plugins");
Ensuite, QCoreApplication::libraryPaths() renverrait quelque chose comme ceci :
C:/customPath/pluginsC:/Qt/%VERSION%/pluginsE:/myApplication/directory
L'exécutable recherchera les plugins dans ces répertoires et dans le même ordre que le QStringList renvoyé par QCoreApplication::libraryPaths(). Le chemin nouvellement ajouté est ajouté au QCoreApplication::libraryPaths(), ce qui signifie qu'il sera recherché en premier. Toutefois, si vous utilisez QCoreApplication::setLibraryPaths(), vous pourrez déterminer les chemins et l'ordre dans lequel ils seront recherchés.
Le document Comment créer des plugins Qt décrit les points auxquels vous devez prêter attention lors de la création et du déploiement de plugins pour les applications Qt.
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.