Qt pour Linux - Déploiement

Cette documentation traite de questions spécifiques au déploiement de Qt pour Linux. Nous démontrerons les procédures en termes de déploiement de l'application d'exemple Plug & Paint qui est fournie avec le paquet source de Qt.

En raison de la prolifération des systèmes Unix (tels que les Unix commerciaux ou les distributions Linux), le déploiement sur Unix est un sujet complexe. Avant de commencer, sachez que les programmes compilés pour un système Unix donné ne fonctionneront probablement pas sur un système Unix différent. Par exemple, à moins d'utiliser un compilateur croisé, vous ne pouvez pas compiler votre application sur Irix et la distribuer sur AIX.

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

Nous supposons que vous avez déjà installé Qt 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 /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 /path/to/Qt/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 :

make clean
qmake -config release
make

Ceci construit l'application principale, la suite construira les plugins :

cd ../plugandpaint/plugins
make clean
qmake -config release
make

Si tout a été compilé et lié sans erreur, nous obtiendrons un exécutable plugandpaint et les fichiers plugins libpnp_basictools.so et libpnp_extrafilters.so.

Création du paquetage de l'application

Il n'y a pas de gestion standard des paquets sous Unix, aussi la méthode que nous présentons ci-dessous est une solution générique. Consultez la documentation de votre système cible pour savoir comment créer un paquetage.

Pour déployer l'application, nous devons nous assurer que nous copions les bibliothèques Qt pertinentes (correspondant aux modules Qt utilisés dans l'application), le plugin de plate-forme et l'exécutable dans la même arborescence de répertoires. N'oubliez pas que si votre application dépend de bibliothèques spécifiques au compilateur, celles-ci doivent également être redistribuées avec votre application. Pour plus d'informations, voir la section Dépendances de l'application.

Nous aborderons les plugins sous peu, mais le principal problème avec les bibliothèques partagées est que vous devez vous assurer que l'éditeur de liens dynamiques trouvera les bibliothèques Qt. Sauf indication contraire, l'éditeur de liens dynamiques ne cherche pas dans le répertoire où réside votre application. Il existe plusieurs façons de résoudre ce problème :

• Vous pouvez installer les bibliothèques Qt dans l'un des chemins d'accès aux bibliothèques du système (par exemple, /usr/lib sur la plupart des systèmes).
• Vous pouvez passer un chemin prédéterminé à l'option de ligne de commande -rpath lors de l'édition de liens de l'application. Cela indiquera à l'éditeur de liens dynamiques de rechercher ce répertoire au démarrage de l'application.
• Vous pouvez écrire un script de démarrage pour votre application, dans lequel vous modifiez la configuration de l'éditeur de liens dynamiques (par exemple, en ajoutant le répertoire de votre application à la variable d'environnement LD_LIBRARY_PATH ).

  Note : Si votre application s'exécute avec "Set user ID on execution", et si elle appartient à root, LD_LIBRARY_PATH sera ignoré sur certaines plates-formes. Dans ce cas, l'utilisation de l'approche LD_LIBRARY_PATH n'est pas une option).

L'inconvénient de la première approche est que l'utilisateur doit disposer des privilèges de superutilisateur. L'inconvénient de la seconde approche est que l'utilisateur peut ne pas avoir les privilèges nécessaires pour installer dans le chemin prédéterminé. Dans les deux cas, les utilisateurs n'ont pas la possibilité d'installer dans leur répertoire personnel. Nous recommandons d'utiliser la troisième approche, car elle est la plus souple. Par exemple, un script plugandpaint.sh ressemblera à ceci :

#!/bin/sh
appname=`basename $0 | sed s,\.sh$,,`

dirname=`dirname $0`
tmp="${dirname#?}"

if [ "${dirname%$tmp}" != "/" ]; then
dirname=$PWD/$dirname
fi
LD_LIBRARY_PATH=$dirname
export LD_LIBRARY_PATH
$dirname/$appname "$@"

En exécutant ce script au lieu de l'exécutable, vous êtes sûr que les bibliothèques Qt seront trouvées par l'éditeur de liens dynamiques. Notez qu'il suffit de renommer le script pour l'utiliser avec d'autres applications.

Lors de la recherche de plugins, l'application cherche dans un sous-répertoire plugins à l'intérieur du répertoire de l'exécutable de l'application. Vous devez copier manuellement les plugins dans le répertoire plugins ou vous pouvez définir le répertoire DESTDIR dans les fichiers de projet des plugins :

DESTDIR = /path/to/Qt/plugandpaint/plugins

Une archive distribuant toutes les bibliothèques Qt XML et tous les plugins nécessaires à l'exécution de l'application plugandpaint devrait inclure les fichiers suivants :

Sur la plupart des systèmes, l'extension pour les bibliothèques partagées est .so. Une exception notable est HP-UX, qui utilise .sl.

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. Pour plus d'informations, voir la section Dépendances de l'application.

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, c'est-à-dire exécuter le script plugandpaint.sh.

Une alternative au placement des plugins dans le sous-répertoire plugins est d'ajouter un chemin de recherche personnalisé lorsque vous démarrez votre application en utilisant QApplication::addLibraryPath() ou QApplication::setLibraryPaths().

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

Liens statiques

L'édition de liens statiques est souvent le moyen le plus sûr et le plus simple de distribuer une application sous Unix, car elle vous dispense de distribuer les bibliothèques Qt et de vous assurer qu'elles se trouvent dans le chemin de recherche par défaut des bibliothèques sur le système cible.

Construction statique de Qt

Pour utiliser cette approche, vous devez commencer par construire une version _statique_ des bibliothèques Qt. Suivez les étapes de Qt for Linux - Building from Source, mais n'oubliez pas d'ajouter un argument -static à configure :

mkdir -p ~/dev/qt-build
cd ~/dev/qt-build
/tmp/qt-everywhere-src-6.11.0/configure -static

Lier l'application à la version statique de Qt

Une fois que Qt est construit statiquement, l'étape suivante consiste à régénérer le fichier makefile et à reconstruire l'application. Tout d'abord, nous devons aller dans le répertoire qui contient l'application :

cd /path/to/Qt/examples/widgets/tools/plugandpaint/app

Lancez maintenant qmake pour créer un nouveau makefile pour l'application, et faites un clean build pour créer l'exécutable lié statiquement :

make clean
PATH=/path/to/Qt/bin:$PATH
export PATH
qmake -config release
make

Vous voudrez probablement faire un lien avec les bibliothèques de version, et vous pouvez le spécifier lorsque vous invoquez qmake. Notez que nous devons définir le chemin vers le Qt statique que nous venons de construire.

Pour vérifier que l'application est réellement liée statiquement à Qt, exécutez l'outil ldd (disponible sur la plupart des Unix) :

ldd ./application

Vérifiez que les bibliothèques Qt ne sont pas mentionnées dans le résultat.

Maintenant, si tout a été compilé et lié sans erreur, nous devrions avoir un fichier plugandpaint prêt à être déployé. Un moyen facile de vérifier que l'application peut vraiment être exécutée de manière autonome est de la copier sur une machine sur laquelle Qt ou toute autre application Qt n'est pas installée, et de l'exécuter 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. Pour plus d'informations, voir la section Dépendances de l'application.

L'exemple Plug & Paint se compose de plusieurs éléments : L'application principale(Plug & Paint), et les plugins Basic Tools et Extra Filters. Étant donné que nous ne pouvons pas déployer les plugins en utilisant l'approche de liaison statique, l'exécutable que nous avons préparé jusqu'à présent est incomplet. L'application 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 de la bibliothèque partagée.

Dépendances de l'application

Bibliothèques supplémentaires

Pour savoir de quelles bibliothèques dépend votre application, lancez l'outil ldd (disponible sur la plupart des Unix) :

ldd ./application

Vous obtiendrez ainsi la liste de toutes les bibliothèques partagées qui dépendent de votre application. Selon la configuration, ces bibliothèques doivent être redistribuées avec votre application. En particulier, la bibliothèque standard C++ doit être redistribuée si vous compilez votre application avec un compilateur incompatible avec le compilateur du système. Dans la mesure du possible, la solution la plus sûre consiste à établir un lien statique avec ces bibliothèques.

Vous voudrez probablement établir un lien dynamique avec les bibliothèques X11 ordinaires, car certaines implémentations essaieront d'ouvrir d'autres bibliothèques partagées avec dlopen(), et si cela échoue, la bibliothèque X11 pourrait faire planter votre application.

Il convient également de mentionner que Qt recherchera certaines extensions X11, telles que Xinerama et Xrandr, et les intégrera éventuellement, y compris toutes les bibliothèques avec lesquelles elles sont liées. Si vous ne pouvez pas garantir la présence d'une certaine extension, l'approche la plus sûre est de la désactiver lors de la configuration de Qt (par exemple, ./configure -no-xrandr).

FontConfig et FreeType sont d'autres exemples de bibliothèques qui ne sont pas toujours disponibles ou qui ne sont pas toujours compatibles avec les binaires. Aussi étrange que cela puisse paraître, certains éditeurs de logiciels ont réussi à compiler leurs logiciels sur de très vieilles machines et ont pris soin de ne pas mettre à jour les logiciels fonctionnant sur ces machines.

Lorsque vous liez votre application aux bibliothèques statiques de Qt, vous devez explicitement lier les bibliothèques dépendantes mentionnées ci-dessus. Pour ce faire, ajoutez-les à la variable LIBS dans votre fichier de projet.

Plugins Qt

Toutes les applications Qt GUI nécessitent un plugin qui met en œuvre la couche Qt Platform Abstraction (QPA) dans Qt. Pour Linux/X11, le nom du plugin de plateforme est libqxcb.so. 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 de plusieurs plugins Qt, tels que le plugin du format d'image JPEG ou le plugin d'un 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 imageformats ou sqldrivers) de votre répertoire de distribution.

Le chemin de recherche des plugins Qt (ainsi que quelques autres chemins) est codé en dur dans la bibliothèque QtCore. Par défaut, le premier chemin de recherche des plugins est codé en dur sous la forme /path/to/Qt/plugins. Comme indiqué plus haut, l'utilisation de chemins prédéterminés présente certains inconvénients. Vous devez donc examiner différentes alternatives pour vous assurer que les plugins Qt sont trouvés :

• Utilisation de qt.conf. C'est l'approche recommandée car elle offre le plus de flexibilité.
• En utilisant QApplication::addLibraryPath() ou QApplication::setLibraryPaths().
• En utilisant un utilitaire d'installation tiers ou le gestionnaire de paquets du système cible pour modifier les chemins codés en dur dans la bibliothèque QtCore.

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.

Marche à suivre : Créer un paquet DEB

Cette section décrit comment créer un paquet DEB pour votre application Qt sur Linux en utilisant l'API de déploiement CMake disponible dans Qt 6.5 ou plus récent. Il n'y a pas d'outil dédié à linuxdeployqt. La solution actuelle repose uniquement sur la fonctionnalité intégrée de CMake.

Exemple de configuration de projet

Commencez par un projet CMake simple :

cmake_minimum_required(VERSION 3.22)
project(MyApp)

find_package(Qt6 REQUIRED COMPONENTS Widgets)
qt_standard_project_setup()

qt_add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE Qt::Widgets)

Étape 1 : Préparer l'installation

Ajoutez des commandes pour installer l'application et générer un script de déploiement pour créer un répertoire autonome :

# Install the executable to "${CMAKE_INSTALL_PREFIX}/bin".
install(TARGETS MyApp
    BUNDLE  DESTINATION .
    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
)

# Generate the deployment script for MyApp.
qt_generate_deploy_app_script(
    TARGET MyApp
    FILENAME_VARIABLE deploy_script
    NO_UNSUPPORTED_PLATFORM_ERROR
)

# Run the deployment script during installation (on "cmake --install").
install(SCRIPT ${deploy_script})

Construire et installer le projet :

qt-cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/tmp/my-application ..
cmake --build .
cmake --install .

Le script de déploiement :

• Crée un fichier qt.conf à côté de l'exécutable qui contient des informations sur la disposition du répertoire. Ces informations sont nécessaires au moment de l'exécution pour trouver les plugins et les ressources. Voir la documentation qt.conf pour plus de détails.
• Inspecte l'exécutable et les plugins Qt utilisés avec le fichier intégré de CMake (GET_RUNTIME_DEPENDENCIES) pour déterminer quelles bibliothèques Qt déployer.
• Installe les plugins et bibliothèques Qt nécessaires.

Le répertoire d'installation peut maintenant être copié sur une autre machine, et l'application devrait toujours fonctionner.

Étape 2 : Créer le paquetage DEB

Après l'installation, empaquetez le répertoire à l'aide de CPack. Ajoutez ce qui suit à votre projet CMake :

set(CPACK_PACKAGE_NAME my-app)
set(CPACK_PACKAGE_DESCRIPTION_SUMMARY "My amazing application")
set(CPACK_PACKAGE_VENDOR "My Company")
set(CPACK_PACKAGE_INSTALL_DIRECTORY ${CPACK_PACKAGE_NAME})
set(CPACK_VERBATIM_VARIABLES ON)
set(CPACK_PACKAGING_INSTALL_PREFIX "/opt/myapp")
set(CPACK_DEBIAN_PACKAGE_MAINTAINER "Package Maintainer <maintainer@example.com>")
set(CPACK_DEBIAN_PACKAGE_DEPENDS libc6 libstdc++6 libgcc-s1)
include(CPack)

Reconfigurez le projet, naviguez jusqu'au répertoire de construction (il doit contenir le fichier CPackConfig.cmake ), et exécutez CPack pour générer le paquet DEB :

cpack -G DEB

Pour inspecter le contenu du paquet :

dpkg -c my_app-1.0-Linux.deb

Pour installer le paquet :

sudo dpkg -i my_app-1.0-Linux.deb