Qt pour Windows - Déploiement

Cette documentation décrit le processus de déploiement sous Windows. Nous nous référons tout au long de ce document à l'application exemple Plug & Paint pour illustrer ce processus.

L'outil de déploiement Windows

La méthode recommandée et la plus simple pour déployer une application Qt sous Windows consiste à utiliser l'outil windeployqt, qui rassemble automatiquement toutes les bibliothèques Qt, les plugins, les modules QML et les dépendances d'exécution nécessaires dans un dossier de déploiement prêt à l'emploi.

Il crée une arborescence d'installation pour les applications de bureau Windows, qui peut être facilement intégrée dans un package d'installation.

Configuration de l'environnement de compilation

Si vous avez installé Qt via Qt Online Installer, vous devez configurer l'environnement de compilation avant d'exécuter windeployqt. Pour ce faire, exécutez :

<qt-installation-folder>/bin/qtenv2.bat

Utilisation

windeployqt se trouve dans <qt-installation-folder>/bin/; il prend en argument un fichier .exe ou un répertoire contenant un fichier .exe, puis analyse l'exécutable à la recherche de ses dépendances.

Veuillez noter les points suivants :

• Si un répertoire est passé avec l’argument --qmldir, windeployqt utilise l’outil qmlimportscanner pour analyser les fichiers QML présents dans ce 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.
• Si Qt a été compilé avec l’option de configuration ` -relocatable ` désactivée, windeployqt remplace les chemins locaux codés en dur dans ` Qt6Core.dll ` par des chemins relatifs.
• Pour les applications de bureau Windows, windeployqt copie par défaut les fichiers d’exécution du compilateur requis, sauf si l’option ` --no-compiler-runtime ` est spécifiée. Pour les versions finales compilées avec Microsoft Visual C++, cela signifie que l’outil s’attend à ce que le programme d’installation de l’application inclue les packages redistributables officiels de Visual C++.

  Si le package de redistribution n’est pas disponible, windeployqt peut se rabattre sur l’utilisation des DLL d’exécution partagées du compilateur présentes sur la machine du développeur. Ces DLL individuelles ne sont pas destinées à la redistribution ni autorisées à cette fin, et ne doivent pas être fournies directement. Seul le programme d'installation officiel des composants redistribuables Microsoft doit être utilisé pour le déploiement sur les systèmes des utilisateurs finaux.

Cas d'utilisation courants

Déploiement d'une application standard d'Qt Widgets

windeployqt.exe .\build\MyApp.exe

Déploiement d'une application « Qt Quick » avec des sources QML

windeployqt.exe --qmldir .\qml .\build\MyApp.exe

Génération d’un manifeste appx pour le packaging

Utilisez cette option lorsque vous préparez votre application en vue de son empaquetage sous forme de package Windows AppX.

L'option « --appx » crée un fichier « AppxManifest.xml », et « --appx-certificate » spécifie le certificat à intégrer dans le manifeste.

windeployqt.exe --appx --appx-certificate MyCompany.cer .\build\MyApp.exe

Effectuer un test sans exécution

Un test sans modification simule le déploiement sans rien copier ni mettre à jour.

windeployqt.exe --dry-run MyApp.exe

Options

Général

Contrôle des entrées et des sorties

Résolution du chemin d'accès Qt

Configuration de compilation

Comportement de déploiement

Plug-ins

QML

Traductions

Composants système et d'exécution

Liste des fichiers générés

Liaison statique

Pour compiler des applications statiques, compilez Qt de manière statique en configurant Qt avec l'option « -static » :

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

Si vous devez par la suite reconfigurer et recompiler Qt à partir du même emplacement, assurez-vous que toutes les traces de la configuration précédente ont été supprimées.

Lier l’application à la version statique de Qt

À titre d'exemple, cette section explique comment compiler l'exemple Plug & Paint avec une version statique de Qt.

Une fois la compilation de Qt terminée, compilez l'application Plug & Paint. Cette section part du principe que la version statique de Qt a été installée dans le répertoire C:\path\to \static \Qt . Nous devons d'abord nous rendre dans le répertoire contenant l'application :

cd examples\tools\plugandpaint

Nous créons ensuite un répertoire de compilation et appelons la commande « qt-cmake » pour générer les fichiers du système de compilation.

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

Vous souhaiterez probablement lier l'application aux bibliothèques de version finale ; nous avons spécifié cette option à l'aide de la variable ` CMAKE_BUILD_TYPE `. À présent, à condition que la compilation et la liaison se soient déroulées sans erreur, nous devrions disposer d'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 ni aucune application Qt n’est installé, puis exécutez-le sur cette machine.

N’oubliez pas que si votre application dépend de bibliothèques spécifiques à un compilateur, celles-ci doivent tout de même être redistribuées avec votre application. Vous pouvez vérifier les bibliothèques auxquelles votre application est liée à l’aide de l’outil depends. Pour plus d’informations, consultez la section « Dépendances de l’application ».

Comme nous ne pouvons pas déployer de plugins en utilisant l'approche de la liaison statique, l'application que nous avons préparée est incomplète. Elle s'exécutera, mais ses 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 défis : le runtime Qt doit être correctement redistribué avec l'exécutable de l'application, et les plugins doivent être installés à l'emplacement approprié sur le système cible afin que l'application puisse les trouver.

Compilation de Qt en tant que bibliothèque partagée

Pour cet exemple, nous partons du principe 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 nous être assurés que Qt a été compilé en tant que bibliothèque partagée, nous pouvons compiler l’application plugandpaint. Tout d’abord, nous devons nous rendre dans le répertoire contenant l’application :

cd examples\tools\plugandpaint

Créez ensuite un répertoire de compilation dédié et exécutez la commande « qt-cmake » pour générer les fichiers du système de compilation :

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

Si la compilation et la liaison se sont déroulées sans erreur, vous obtiendrez un exécutable plugandpaint.exe ainsi que les fichiers de plugins pnp_basictools.dll et pnp_extrafilters.dll.

Création du package d'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 plateforme Windows, qwindows.dll, ainsi que l'exécutable, dans la même arborescence de répertoires, au sein du 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 vous utilisez OpenGL dynamique, vous pouvez également inclure la bibliothèque requise pour OpenGL logiciel, si l’application est compatible avec celle-ci.

Si Qt a été configuré pour être lié à ICU ou OpenSSL, les DLL correspondantes devront peut-être également être ajoutées au dossier ` release `. Toutefois, les paquets binaires de Qt sous Windows ne nécessitent pas cette opération. Si vous avez configuré Qt avec une version spécifique d’ICU ou d’OpenSSL, windeployqt devrait détecter les DLL des bibliothèques correspondantes si celles-ci se trouvent dans le répertoire ` [bin] ` de Qt. Pour plus de détails, consultez également la section 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 auxquelles votre application est liée à l’aide de l’outil « depends ». Pour plus d’informations, consultez la section « Dépendances de l’application ».

Nous aborderons les plugins dans un instant, mais nous allons d’abord vérifier que l’application fonctionne dans un environnement de déploiement : Soit vous copiez l’exécutable et les DLL Qt sur une machine sur laquelle Qt ni aucune application Qt n’est installé, soit, si vous souhaitez effectuer le test sur la machine de compilation, vous vous assurez que Qt n’est pas présent dans l’environnement de cette machine.

Si l'application démarre sans problème, cela signifie que nous avons réussi à créer une version à liaison dynamique de l'plugandpaint. Cependant, les fonctionnalités de l'application seront encore absentes, car nous n'avons pas encore déployé les plugins associés.

Les plugins fonctionnent différemment des DLL classiques ; 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 sa recherche dans un sous-répertoire « plugins » situé à l’intérieur du répertoire de l’exécutable de l’application.

Pour que notre application puisse utiliser ces plugins, nous devons donc créer le sous-répertoire ` plugins ` et y copier les DLL concernées :

plugins\pnp_basictools.dll
plugins\pnp_extrafilters.dll

Une archive distribuant toutes les DLL Qt et les plugins spécifiques à l'application nécessaires au fonctionnement de 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).

De plus, l'archive doit contenir les bibliothèques spécifiques au compilateur suivantes (en supposant l'utilisation de Visual Studio 17 (2022)) :

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

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

Pour vérifier que l'application peut désormais être déployée correctement, vous pouvez extraire cette archive sur une machine ne disposant ni de Qt ni de compilateur, puis essayer de l'exécuter.

Au lieu de placer les plugins dans le sous-répertoire « plugins », vous pouvez également ajouter un chemin de recherche personnalisé lors du lancement de votre application à l’aide de QCoreApplication::addLibraryPath() ou QCoreApplication::setLibraryPaths().

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

L'un des avantages de l'utilisation de plugins est qu'ils peuvent facilement être mis à la disposition de toute une famille d'applications.

Il est souvent plus pratique d’ajouter ce 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 y recherchera les plugins, en plus de consulter le sous-répertoire ` plugins ` situé dans le répertoire de l’application elle-même. Il est possible d’ajouter autant de chemins supplémentaires que souhaité.

Génération du manifeste d’application Windows

Lors de la compilation 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
• Prend en charge les chemins d'accès longs
• Définit la version de l'application (à partir de PROJECT_VERSION)
• Définit un identifiant de projet
• Configure le niveau d'exécution demandé
• Désactive le manifeste par défaut généré par l'éditeur de liens (/MANIFEST:NO)

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

La déclaration de compatibilité avec Windows 10/11 active les comportements modernes de Windows, notamment :

• Activation du comportement moderne du gestionnaire de fenêtres
• Prise en charge de l’ WS_EX_LAYERED sur les fenêtres enfants (prise en charge depuis Windows 8 mais soumise à des restrictions de 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 un comportement hérité à l’application.

Contenu par défaut du manifeste

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é en une version Windows en quatre parties

Par défaut, l’identifiant est :

com.yourcompany.<target_name>

Il peut être redéfini 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 d'applications Windows doivent comporter un numéro de version en quatre parties :

Major.Minor.Build.Revision

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

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

• En cas de valeur manquante → valeur par défaut : 1.0.0.0
• Moins de quatre segments → complétée par des zéros
• Plus de quatre segments → troncature
• Valeurs < 0 → limitées à 0
• Valeurs > 65535 → limité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é avec Windows

Le manifeste indique la prise en charge de Windows 10 et Windows 11.

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

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

Pour plus d’informations : Manifestes d’applications Microsoft.

Prise en charge des chemins d'accès longs

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

Permet d'utiliser des chemins d'accès aux 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 la méthode ` asInvoker ` est utilisée.

Fournir un manifeste personnalisé

Qt détecte le fichier manifeste et ne procède pas à 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 illustre 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 de manifeste avec qmake

Lors du déploiement d'une application compilée avec Visual Studio, certaines étapes supplémentaires doivent être effectuées.

Tout d'abord, il faut 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 vis-à-vis des assemblages « side-by-side », 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 des bibliothèques partagées (DLL), car ceux-ci ne sont pas utilisés.

Si la bibliothèque partagée présente des dépendances différentes de celles de l'application qui l'utilise, le fichier manifeste doit être intégré au fichier binaire de la DLL. Les options suivantes de l'CONFIG e sont disponibles pour l'intégration des manifestes :

embed_manifest_dll
embed_manifest_exe

Ces deux options sont activées par défaut. Pour désactiver l'embed_manifest_exe, ajoutez

CONFIG -= embed_manifest_exe

à votre fichier .pro.

Vous trouverez plus d’informations sur les fichiers de manifeste et les assemblages côte à côte sur la page de documentation consacrée aux assemblages côte à côte.

La bonne façon d'inclure les bibliothèques d'exécution dans votre application consiste à vous 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 le fichier exécutable approprié du package de redistribution Visual C++ (VCRedist) avec votre application et vous assurer qu'il est exécuté lorsque l'utilisateur installe votre application.

Le package de redistribution s'intitule « vc_redist.x64.exe » (64 bits) et se trouve dans le dossier « <Visual Studio install path>/VC/redist/<language-code> ».

Il est également possible de le télécharger sur Internet, 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, les bibliothèques spécifiques au compilateur doivent être redistribuées avec votre application.

Vous pouvez vérifier quelles bibliothèques sont liées à votre application à l'aide de l'outil Dependency Walker. Il vous suffit de l'exécuter comme suit :

depends <application executable>

Vous obtiendrez ainsi la liste des bibliothèques dont dépend votre application, ainsi que d'autres informations.

Lorsque l'on examine la version finale de l'exécutable Plug & Paint (plugandpaint.exe) à l'aide de l'outil depends, celui-ci répertorie les dépendances directes suivantes vis-à-vis de bibliothèques non système :

Lorsque l'on examine les DLL des plugins, on constate que les dépendances répertoriées sont exactement les mêmes.

Plug-ins Qt

Toutes les applications Qt GUI nécessitent un plugin qui implémente la couche Qt Platform Abstraction (QPA) dans Qt. Sous Windows, le nom du plugin de plateforme est qwindows.dll. Ce fichier doit se trouver dans un sous-répertoire spécifique (par défaut, platforms) sous votre répertoire de distribution. Il est également possible de modifier 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 Qt Print Support, le plugin du format d’image JPEG ou un plugin de pilote SQL. Veillez à distribuer tous les plugins Qt dont vous avez besoin avec votre application. À l’instar du plugin de plateforme, chaque type de plugin doit se trouver dans un sous-répertoire spécifique (tel que printsupport, imageformats ou sqldrivers) au sein de votre répertoire de distribution.

Les bibliothèques sont relocalisables, sauf si Qt a été compilé avec l’option de configuration « -relocatable » désactivée. Les chemins de recherche des plug-ins Qt sont relatifs à l’emplacement de la bibliothèque QtCore et aucune autre étape n’est nécessaire pour garantir que les plug-ins soient détectés après l’installation de l’application sur la machine cible.

S'assurer que les plugins sont détectés lors de l'utilisation de versions non relocalisables

Pour les versions non relocalisables, des étapes supplémentaires doivent être effectuées pour garantir que les plugins soient détectés une fois l'application installée 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 Qt est le premier chemin de recherche des plugins. Cependant, les chemins prédéfinis, 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 différentes alternatives pour vous assurer que les plugins Qt seront détectés :

• Utilisation de ` qt.conf `. Cette approche est recommandée si vous disposez d’exécutables situés à différents emplacements et partageant les mêmes plugins.
• Utiliser ` QApplication::addLibraryPath()` ou ` QApplication::setLibraryPaths()`. Cette approche est recommandée si vous ne disposez que d’un seul exécutable qui utilisera le plugin.
• Utiliser un utilitaire d’installation tiers pour modifier les chemins d’accès codés en dur dans la bibliothèque ` QtCore `.

Si vous ajoutez un chemin personnalisé à l’aide de `QApplication::addLibraryPath`, cela pourrait ressembler à ceci :

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

Dans ce cas, la fonction ` QCoreApplication::libraryPaths()` renverrait un résultat similaire à celui-ci :

• 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 celui renvoyé par la fonction ` QStringList ` de ` QCoreApplication::libraryPaths()`. Le chemin nouvellement ajouté est placé en tête de la liste renvoyée par ` QCoreApplication::libraryPaths()`, ce qui signifie qu'il sera exploré en premier. Cependant, si vous utilisez ` QCoreApplication::setLibraryPaths()`, vous pourrez déterminer quels chemins seront explorés et dans quel ordre.

Le document « Comment créer des plugins Qt » présente les points auxquels vous devez prêter attention lors de la création et du déploiement de plugins pour les applications Qt.