Qt pour Linux - Déploiement

Cette documentation traite des problèmes de déploiement spécifiques à Qt sous Linux. Nous allons illustrer ces procédures à l'aide de l'application d'exemple Plug & Paint 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 sous Unix est un sujet complexe. Avant de commencer, sachez que les programmes compilés pour une variante d’Unix ne fonctionneront probablement pas sur un autre système Unix. Par exemple, à moins d’utiliser un compilateur croisé, vous ne pouvez pas compiler votre application sous Irix et la distribuer sous AIX.

Bibliothèques partagées

Deux défis se posent lors du déploiement de l’application « plugandpaint » à l’aide de l’approche des bibliothèques partagées : 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

Nous partons du principe 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 vous être assuré que Qt est 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 /path/to/Qt/examples/tools/plugandpaint

Exécutez ensuite qmake pour créer un nouveau fichier makefile pour l’application, puis effectuez une compilation « clean » pour créer l’exécutable lié dynamiquement :

make clean
qmake -config release
make

Cela compile le cœur de l’application ; la commande suivante compilera les plugins :

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

Si tout s’est compilé et lié sans erreur, nous obtiendrons un exécutable « plugandpaint » ainsi que les fichiers de plugins « libpnp_basictools.so » et « libpnp_extrafilters.so ».

Création du paquet de l’application

Il n’existe pas de système de gestion de paquets standard sous Unix ; la méthode présentée ci-dessous est donc une solution générique. Consultez la documentation de votre système cible pour savoir comment créer un paquet.

Pour déployer l'application, vous devez vous assurer de copier les bibliothèques Qt pertinentes (correspondant aux modules Qt utilisés dans l'application), le plugin de la plateforme et le fichier exécutable dans la même arborescence de répertoires. N'oubliez pas que si votre application dépend de bibliothèques spécifiques à un compilateur, celles-ci doivent également être redistribuées avec votre application. Pour plus d'informations, consultez la section « Dépendances de l'application ».

Nous aborderons les plugins dans un instant, 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 recherche 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éfini à l’option de ligne de commande ` -rpath ` lors de la liaison de l’application. Cela indiquera à l’éditeur de liens dynamiques de rechercher dans ce répertoire au démarrage de votre 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 `).

  Remarque : si votre application s’exécute avec l’option « Définir l’ID utilisateur à l’exécution » et si elle appartient à root, la variable LD_LIBRARY_PATH sera ignorée sur certaines plateformes. Dans ce cas, l’utilisation de la variable LD_LIBRARY_PATH n’est pas envisageable).

L'inconvénient de la première approche est que l'utilisateur doit disposer des privilèges de super-utilisateur. L'inconvénient de la deuxième approche est que l'utilisateur peut ne pas disposer des privilèges nécessaires pour effectuer l'installation dans le chemin prédéfini. Dans les deux cas, les utilisateurs n'ont pas la possibilité d'installer l'application dans leur répertoire personnel. Nous recommandons d’utiliser la troisième approche, car c’est la plus flexible. 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 à la place de l’exécutable, vous êtes assuré que les bibliothèques Qt seront détectées par l’éditeur de liens dynamiques. Notez qu’il vous suffit de renommer le script pour l’utiliser avec d’autres applications.

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. Vous devez soit copier manuellement les plugins dans le répertoire « plugins », soit définir l’ DESTDIR e dans les fichiers de projet des plugins :

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

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

Sur la plupart des systèmes, l'extension des 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 à un compilateur, celles-ci doivent tout de même être redistribuées avec votre application. Pour plus d'informations, consultez la section « Dépendances de l'application ».

Pour vérifier que l’application peut désormais être déployée avec succès, vous pouvez extraire cette archive sur une machine ne disposant ni de Qt ni de compilateur, puis essayer de l’exécuter, c’est-à-dire lancer le script plugandpaint.sh.

Au lieu de placer les plugins dans le sous-répertoire « plugins », vous pouvez également ajouter un chemin de recherche personnalisé lorsque vous lancez votre application à l'aide de ` QApplication::addLibraryPath()` ou ` QApplication::setLibraryPaths()`.

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

Liaison statique

La liaison statique est souvent le moyen le plus sûr et le plus simple de distribuer une application sous Unix, car elle vous évite d’avoir à distribuer les bibliothèques Qt et à vous assurer qu’elles se trouvent dans le chemin de recherche par défaut des bibliothèques sur le système cible.

Compilation statique de Qt

Pour utiliser cette approche, vous devez commencer par compiler une version _statique_ des bibliothèques Qt. Suivez les étapes décrites dans la section « Qt pour Linux - Compilation à partir du code source », mais n'oubliez pas d'ajouter l'argument -static à la commande configure :

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

Lier l’application à la version statique de Qt

Une fois Qt compilé de manière statique, l’étape suivante consiste à régénérer le fichier makefile et à recompiler l’application. Tout d’abord, vous devez vous placer dans le répertoire contenant l’application :

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

Exécutez ensuite qmake pour créer un nouveau makefile pour l’application, puis effectuez une compilation « clean » afin de générer l’exécutable lié de manière statique :

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

Vous souhaiterez probablement lier l’application aux bibliothèques de version finale, ce que vous pouvez spécifier lors de l’exécution de ` qmake`. Notez que nous devons définir le chemin d’accès au Qt statique que nous venons de compiler.

Pour vérifier que l’application est bien liée statiquement à Qt, exécutez l’outil ` ldd ` (disponible sur la plupart des systèmes Unix) :

ldd ./application

Vérifiez que les bibliothèques Qt ne sont pas mentionnées dans la sortie.

À présent, à condition que la compilation et la liaison se soient déroulées sans erreur, vous devriez disposer d’un fichier ` plugandpaint ` prêt à être déployé. Un moyen simple de vérifier que l’application peut réellement fonctionner de manière autonome consiste à la copier sur une machine sur laquelle Qt ou aucune application Qt n’est installé, puis à 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 tout de même être redistribuées avec votre application. Pour plus d’informations, consultez la section « Dépendances de l’application ».

L'exemple Plug & Paint se compose de plusieurs éléments : l'application principale (Plug & Paint), ainsi que les plugins « Basic Tools » et « Extra Filters ». Comme il n'est pas possible de déployer des plugins à l'aide de la liaison statique, l'exécutable que nous avons préparé jusqu'à présent est incomplet. L'application 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.

Dépendances de l’application

Bibliothèques supplémentaires

Pour connaître les bibliothèques dont dépend votre application, exécutez l’outil « ldd » (disponible sur la plupart des systèmes Unix) :

ldd ./application

Cela répertoriera toutes les dépendances de bibliothèques partagées de votre application. Selon la configuration, ces bibliothèques doivent être redistribuées avec votre application. En particulier, la bibliothèque C++ standard doit être redistribuée si vous compilez votre application avec un compilateur binaire incompatible avec le compilateur du système. Dans la mesure du possible, la solution la plus sûre consiste à lier ces bibliothèques de manière statique.

Vous souhaiterez probablement effectuer une liaison dynamique avec les bibliothèques X11 standard, car certaines implémentations tenteront d’ouvrir d’autres bibliothèques partagées à l’aide de ` dlopen()`, et en cas d’échec, la bibliothèque X11 pourrait provoquer le plantage de votre application.

Il convient également de mentionner que Qt recherchera certaines extensions X11, telles que Xinerama et Xrandr, et pourra les intégrer, y compris toutes les bibliothèques auxquelles elles sont liées. Si vous ne pouvez pas garantir la présence d'une extension donnée, l'approche la plus sûre consiste à 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 au niveau binaire. Aussi étrange que cela puisse paraître, certains éditeurs de logiciels ont réussi à compiler leurs logiciels sur des machines très anciennes et ont pris grand soin de ne mettre à jour aucun des logiciels qui y tournaient.

Lorsque vous liez votre application aux bibliothèques Qt statiques, 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.

Plug-ins Qt

Toutes les applications Qt GUI nécessitent un plugin qui implémente la couche Qt Platform Abstraction (QPA) dans Qt. Pour Linux/X11, le nom du plugin de plateforme est libqxcb.so. 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 pour le 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 imageformats ou sqldrivers) au sein de votre répertoire de distribution.

Le chemin de recherche des plug-ins Qt (ainsi que quelques autres chemins) est codé en dur dans la bibliothèque QtCore. Par défaut, le premier chemin de recherche des plug-ins sera codé en dur sous la forme /path/to/Qt/plugins. Comme mentionné ci-dessus, l’utilisation de chemins prédéfinis présente certains inconvénients ; vous devez donc examiner différentes alternatives pour vous assurer que les plug-ins Qt seront bien trouvés :

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

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

Guide pratique : créer un paquet DEB

Cette section décrit comment créer un paquet DEB pour votre application Qt sous Linux à l’aide de l’API de déploiement CMake disponible dans Qt 6.5 ou une version plus récente. Il n’existe pas d’outil linuxdeployqt dédié. La solution actuelle repose uniquement sur les fonctionnalités intégrées de CMake.

Configuration d’un projet d’exemple

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éparation de l’installation

Ajoutez des commandes pour installer l'application et générer un script de déploiement afin de 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})

Compilez et installez 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, contenant des informations sur la structure du répertoire. Ce fichier est nécessaire lors de l'exécution pour localiser les plugins et les ressources. Consultez la documentation de qt.conf pour plus de détails.
• Analyse l'exécutable et les plugins Qt utilisés à l'aide de la fonction intégrée de CMake (GET_RUNTIME_DEPENDENCIES) afin de déterminer les bibliothèques Qt à déployer.
• Installe les plugins et bibliothèques Qt nécessaires.

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

Étape 2 : Créer le paquet DEB

Après l’installation, créez un paquet à partir du 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, accédez au répertoire de compilation (il doit contenir le fichier ` CPackConfig.cmake `), puis 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