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.

L'outil de déploiement 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. Lors de l'utilisation de 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.11.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.

Lier l'application à la version statique de Qt

À titre d'exemple, cette section construira l'exemple Plug & Paint à partir d'une version statique de Qt.

Une fois la construction de Qt terminée, construisez l'application Plug & Paint. Cette section suppose que la version statique de Qt a été installée sur C :\path\to \static \Qt . Nous devons d'abord aller dans le répertoire qui contient l'application :

cd examples\tools\plugandpaint

Maintenant, nous créons un répertoire de construction et appelons qt-cmake pour générer les fichiers du système de construction.

md build_static
cd build_static
C:\path\to\static\Qt\bin\qt-cmake .. -DCMAKE_BUILD_TYPE=Release -GNinja
ninja

Vous voudrez probablement faire un lien avec les bibliothèques de version, et nous l'avons spécifié avec la variable CMAKE_BUILD_TYPE. 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

Créez maintenant un répertoire de construction dédié et exécutez qt-cmake pour créer les fichiers du système de construction :

md build_shared
cd build_shared
C:\path\to\Qt\bin\qt-cmake .. -DCMAKE_BUILD_TYPE=Release -GNinja
ninja

Si tout a été compilé et lié sans erreur, nous obtiendrons un exécutable plugandpaint.exe et les fichiers 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 :

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

Si l'OpenGL dynamique a été utilisé, l'archive peut contenir en plus :

Enfin, si Qt a été configuré pour utiliser ICU, l'archive doit contenir :

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.

Génération du manifeste de l'application Windows

Lors de la construction sous Windows, Qt génère et intègre automatiquement un manifeste d'application pour les cibles exécutables.

Le manifeste généré :

• Déclare la compatibilité avec Windows 10 et Windows 11
• Active la prise en compte des longs chemins d'accès
• Définit la version de l'application (à partir de PROJECT_VERSION)
• Définit un identifiant de projet
• Configure le niveau d'exécution requis
• Désactive le manifeste généré par défaut par l'éditeur de liens (/MANIFEST:NO)

Si un fichier .manifest personnalisé est déjà fourni dans les sources de la cible, Qt ne le remplace pas.

Déclarer la compatibilité avec Windows 10/11 permet un comportement moderne de Windows, y compris :

• l'acceptation du comportement du gestionnaire de fenêtres moderne
• Support pour WS_EX_LAYERED sur les fenêtres enfants (supporté depuis Windows 8 mais limité par la prise de conscience de la compatibilité)
• Prise en charge des chemins d'accès longs (> 260 caractères)
• Configuration explicite du niveau d'exécution

En l'absence d'une déclaration de compatibilité appropriée, Windows peut appliquer à l'application un comportement hérité.

Contenu du manifeste par défaut

Identité de l'application

Le manifeste contient un élément assemblyIdentity:

<assemblyIdentity
    type="win32"
    name="com.yourcompany.myapp"
    version="1.0.0.0"
    processorArchitecture="*" />

• name - identifiant du projet
• version - normalisé à une version Windows en quatre parties

Par défaut, l'identifiant est :

com.yourcompany.<target_name>

Il peut être modifié pour chaque cible à l'aide de la propriété QT_WINDOWS_APP_PROJECT_IDENTIFIER:

set_target_properties(myapp PROPERTIES
    QT_WINDOWS_APP_PROJECT_IDENTIFIER "org.example.myapp"
)

Les manifestes des applications Windows nécessitent un numéro de version en quatre parties :

Major.Minor.Build.Revision

Chaque segment doit être un nombre entier compris entre 0 et 65535.

La valeur est dérivée de PROJECT_VERSION et normalisée comme suit :

• Si manquant → valeur par défaut 1.0.0.0
• Moins de quatre segments → remplissage avec des zéros
• Plus de quatre segments → tronqué
• Valeurs < 0 → clampées à 0
• Valeurs > 65535 → bridées à 65535 (avertissement émis)

Exemples :

2.3        -> 2.3.0.0
1.2.3.4.5  -> 1.2.3.4
70000.1    -> 65535.1.0.0

Compatibilité Windows

Le manifeste déclare prendre en charge Windows 10 et Windows 11.

<supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}" />

{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a} Le GUID correspond à ces systèmes d'exploitation : Windows 10, Windows 11, Windows Server 2016, Windows Server 2019 et Windows Server 2022.

Plus d'informations sur : Manifeste d'application Microsoft.

Sensibilisation aux chemins longs

<ws2:longPathAware>true</ws2:longPathAware>

Permet d'utiliser des chemins de fichiers de plus de 260 caractères, lorsque le système d'exploitation le prend en charge.

Niveau d'exécution

<requestedExecutionLevel level="asInvoker" uiAccess="false" />

Le niveau par défaut est asInvoker.

Pour définir le niveau d'exécution, utilisez la propriété QT_WINDOWS_APP_PROJECT_EXECUTION_LEVEL.

Valeurs valides :

• asInvoker (par défaut)
• highestAvailable
• requireAdministrator

Exemple :

set_target_properties(myapp PROPERTIES
    QT_WINDOWS_APP_PROJECT_EXECUTION_LEVEL "requireAdministrator"
)

Si une valeur non valide est fournie, un avertissement est émis et asInvoker est utilisé.

Fournir un manifeste personnalisé

Qt XML détecte le fichier manifeste et saute la génération automatique, si un exécutable inclut déjà un fichier .manifest dans ses sources :

add_executable(myapp
    main.cpp
    myapp.manifest
)

Exemple complet

L'exemple suivant montre un exécutable Windows utilisant le manifeste généré automatiquement avec un identifiant et un niveau d'exécution personnalisés :

cmake_minimum_required(VERSION 3.21)
project(MyApp VERSION 2.5.1)

find_package(Qt6 REQUIRED COMPONENTS Core Widgets)

qt_add_executable(MyApp
    main.cpp
)

set_target_properties(MyApp PROPERTIES
    QT_WINDOWS_APP_PROJECT_IDENTIFIER "org.example.myapp"
    QT_WINDOWS_APP_PROJECT_EXECUTION_LEVEL "highestAvailable"
)

Dans cet exemple, la version du manifeste généré sera :

2.5.1.0

Fichiers manifestes avec qmake

Lors du déploiement d'une application compilée avec Visual Studio, il y a quelques étapes supplémentaires à suivre.

Tout d'abord, nous devons copier le fichier manifest créé lors de l'édition de liens 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 veiller à ce qu'elles soient 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.

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. Il vous suffit de le lancer comme suit :

depends <application executable>

Vous obtiendrez une liste des bibliothèques dont dépend votre application, 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 hors système :

Lorsque l'on regarde les DLL des plugins, on retrouve exactement les mêmes dépendances.

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 greffon de plate-forme, chaque type de greffon doit être situé 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 sont relatifs à l'emplacement de la bibliothèque QtCore et aucune autre étape 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/plugins
• C:/Qt/%VERSION%/plugins
• E:/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. Cependant, 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 lorsque vous créez et déployez des plugins pour les applications Qt.