Le système de ressources Qt

Le système de ressources Qt est un mécanisme indépendant de la plate-forme pour l'expédition des fichiers de ressources dans une application. Utilisez-le si votre application a toujours besoin d'un certain ensemble de fichiers (comme des icônes, des fichiers de traduction, des images), et que vous ne voulez pas utiliser des moyens spécifiques au système pour empaqueter et localiser ces ressources.

Le plus souvent, les fichiers de ressources sont intégrés dans l'exécutable de votre application, ou dans des bibliothèques et des modules d'extension chargés par l'exécutable de l'application. Les fichiers de ressources peuvent également être stockés dans un fichier de ressources externe.

Le système de ressources est basé sur une coopération étroite entre le compilateur de ressources rcc de Qt, le système de construction et l'API d'exécution de Qt.

Le Qt Resource Compiler (rcc)

L'outil en ligne de commande Resource Compiler (rcc) lit les fichiers de ressources et génère soit un fichier source C++ ou Python, soit un fichier .rcc.

La liste des fichiers et des métadonnées associées est transmise à rcc sous la forme d'un fichier de collecte de ressources Qt.

Par défaut, rcc génère un code source C++ qui est ensuite compilé en tant que partie d'un exécutable ou d'une bibliothèque. L'option -g python génère un code source Python à la place. L'option -binary génère une archive binaire qui, par convention, est enregistrée dans un fichier .rcc et peut être chargée au moment de l'exécution.

Fichier de collecte des ressources Qt (.qrc)

Un fichier .qrc est un document XML qui énumère les fichiers locaux à inclure en tant que ressources d'exécution. Il sert d'entrée à rcc.

Voici un exemple de fichier .qrc:

<RCC>
    <qresource prefix="/">
        <file>images/copy.png</file>
        <file>images/cut.png</file>
        <file>images/new.png</file>
        <file>images/open.png</file>
        <file>images/paste.png</file>
        <file>images/save.png</file>
    </qresource>
</RCC>

Chaque élément <file> du XML identifie un fichier dans l'arbre source de l'application. Le chemin est résolu relativement au répertoire contenant le fichier .qrc.

Le chemin est également utilisé par défaut pour identifier le contenu du fichier au moment de l'exécution. Ainsi, le fichier copy.png sera disponible dans le système de ressources en tant que :/images/copy.png ou qrc:/images/copy.png. Pour remplacer ce nom d'exécution par défaut, voir Préfixes et alias.

Qt Creator, Qt Design Studio, Qt Widgets Designer et Qt Visual Studio Tools vous permettent de créer, d'inspecter et de modifier les fichiers .qrc au moyen d'une interface utilisateur pratique. À l'exception de Qt Widgets Designer, ils fournissent également des assistants pour les projets utilisant le système de ressources Qt.

Intégration du système de construction

Le traitement des fichiers de ressources avec rcc est généralement effectué au moment de la construction de l'application. Plusieurs outils de construction disposent d'un support dédié à cet effet, notamment CMake et qmake.

CMake

Si CMAKE_AUTORCC est activé, vous pouvez simplement ajouter les fichiers .qrc en tant que sources à votre exécutable ou à votre bibliothèque. Les fichiers de ressources référencés seront alors intégrés dans le binaire :

set(CMAKE_AUTORCC ON)

qt_add_executable(my_app
    application.qrc
    main.cpp
)

Voir la documentation AUTORCC de CMake pour plus de détails sur AUTORCC.

Une alternative à AUTORCC est l'utilisation de la fonction CMake qt_add_resources de Qt6Core, qui donne plus de contrôle sur la création des ressources. Par exemple, elle vous permet de spécifier le contenu de la ressource directement dans le fichier du projet sans écrire un fichier .qrc au préalable :

qt_add_resources(my_app "app_images"
    PREFIX "/"
    FILES
        images/copy.png
        images/cut.png
        images/new.png
        images/open.png
        images/paste.png
        images/save.png
)

Enfin, qt_add_qml_module vous permet d'intégrer les ressources Qt Quick dans le système de ressources de votre application. La fonction est définie dans le composant Qml du paquet CMake Qt6.

qmake

qmake prend en charge le transfert de ressources à l'aide de la variable RESOURCES. Si vous ajoutez un chemin de fichier .qrc à la variable, les fichiers de ressources listés seront incorporés dans la bibliothèque ou l'exécutable généré :

RESOURCES = application.qrc

Pour les applications simples, il est également possible de laisser qmake générer le fichier .qrc pour vous, évitant ainsi la nécessité de maintenir un fichier supplémentaire :

resources.files = \
    images/copy.png \
    images/cut.png \
    images/new.png \
    images/open.png \
    images/paste.png \
    images/save.png
resources.prefix = /

RESOURCES = resources

Cela crée une ressource de plusieurs fichiers .png, qui peuvent être adressés comme suit : ":/images/copy.png".

Si la disposition des répertoires des fichiers que vous souhaitez intégrer dans la ressource ne correspond pas aux attentes de l'application, vous pouvez spécifier resources.base. base est un préfixe de chemin qui indique le point racine de l'alias du fichier. Dans l'exemple ci-dessous, si resources.base est défini comme "images", copy.png peut être adressé comme ":/copy.png".

API d'exécution

L'API Qt qui traite de l'itération et de la lecture des fichiers dispose d'un support intégré pour le système de ressources Qt. Vous pouvez passer un chemin de ressource au lieu d'un chemin de fichier local à QFile et QDir, mais aussi par exemple aux constructeurs QIcon, QImage, et QPixmap:

    cutAct = new QAction(QIcon(":/images/cut.png"), tr("Cu&t"), this);

Le préfixe : indique explicitement que "/images/cut.png" doit être chargé à partir du système de ressources Qt.

Vous pouvez également faire référence au système de ressources Qt par le biais d'un préfixe QUrl. Utilisez le schéma qrc dans ce cas :

    QQmlApplicationEngine engine;
    engine.load(QUrl("qrc:/myapp/main.qml"));

Sujets avancés

Préfixes

Un fichier .qrc peut définir un préfixe à ajouter à chaque nom de fichier local, donné dans un élément <file>, pour obtenir le nom par lequel le fichier sera connu dans le système de ressources.

Les préfixes vous permettent de structurer les ressources, en évitant les conflits entre les fichiers de ressources ajoutés par l'intermédiaire de différents fichiers .qrc dans différentes bibliothèques ou modules d'extension.

Alias

Il est parfois pratique de rendre un fichier de ressources disponible sous un chemin différent au moment de l'exécution. Les fichiers .qrc le permettent en définissant un attribut alias:

<file alias="cut-img.png">images/cut.png</file>

Le fichier provient de l'application et n'est alors accessible que sous :/cut-img.png ou qrc:/cut-img.png.

Rejeter le contenu d'un fichier

Il arrive que vous souhaitiez ajouter un nœud de fichier au système de fichiers de ressources sans pour autant ajouter le contenu du fichier. Les fichiers .qrc le permettent en définissant l'attribut empty sur true.

<file empty="true">Button.qml</file>

Le fichier résultant est alors toujours accessible à partir de l'application, mais son contenu est vide.

Ceci est utile pour retirer le code source QML d'une application binaire.

Sélecteurs de langue

Certaines ressources doivent être modifiées en fonction de la langue de l'utilisateur, comme les fichiers de traduction ou les icônes. Les fichiers de collecte de ressources prennent en charge cette fonction grâce à l'attribut lang de la balise qresource, qui spécifie une chaîne de caractères locale appropriée. En voici un exemple :

<qresource>
    <file>cut.jpg</file>
</qresource>
<qresource lang="fr">
    <file alias="cut.jpg">cut_fr.jpg</file>
</qresource>

Si la langue locale de l'utilisateur est le français (c'est-à-dire que QLocale::system().language() est le français), :/cut.jpg ou qrc:/cut.jpg devient une référence à l'image cut_fr.jpg. Pour les autres langues, c'est cut.jpg qui est utilisé.

Voir la documentation de QLocale pour une description du format à utiliser pour les chaînes de caractères locales.

Voir QFileSelector pour un mécanisme supplémentaire de sélection des ressources locales.

Intégration de fichiers volumineux

Par défaut, rcc incorpore les fichiers de ressources dans les exécutables sous la forme de tableaux C++. Cela peut s'avérer problématique, en particulier pour les ressources volumineuses.

Si le compilateur prend trop de temps, voire échoue en raison d'un dépassement de mémoire, vous pouvez opter pour un mode spécial dans lequel les ressources sont intégrées dans le cadre d'un processus en deux étapes. Le compilateur C++ réserve uniquement un espace suffisant dans l'exécutable ou la bibliothèque cible pour les ressources. L'incorporation effective du contenu et des métadonnées du fichier de ressources est alors effectuée après la phase de compilation et d'édition de liens, par le biais d'un autre appel à rcc.

Pour qmake, ceci est activé en ajoutant resources_big à la variable CONFIG:

CONFIG += resources_big

Pour CMake, vous devez utiliser la fonction qt_add_big_resources.

Fichiers de ressources externes

Une alternative à l'intégration des fichiers de ressources dans le binaire est de les stocker dans un fichier .rcc séparé. rcc le permet avec l'option -binary. Un tel fichier .rcc doit alors être chargé au moment de l'exécution avec QResource.

Par exemple, un ensemble de données de ressources spécifié dans un fichier .qrc peut être compilé de la manière suivante :

rcc -binary myresource.qrc -o myresource.rcc

Dans l'application, cette ressource serait enregistrée avec un code comme celui-ci :

QResource::registerResource("/path/to/myresource.rcc");

Si vous utilisez CMake, vous pouvez utiliser la fonction qt_add_binary_resources pour programmer l'appel rcc ci-dessus :

qt_add_binary_resources(resources application.qrc DESTINATION application.rcc)
add_dependencies(my_app resources)

Ressources dans une application Qt for Python

Le fichier de collecte des ressources est converti en module Python à l'aide du compilateur de ressources rcc:

rcc -g python mainwindow.qrc > mainwindow_rc.py

Le module peut ensuite être importé dans l'application :

import mainwindow_rc.py

Compression

rcc tente de compresser le contenu afin d'optimiser l'utilisation de l'espace disque dans les binaires finaux. Par défaut, il effectue une vérification heuristique pour déterminer si la compression en vaut la peine et stocke le contenu non compressé s'il ne parvient pas à le compresser suffisamment. Pour contrôler le seuil, vous pouvez utiliser l'option -threshold, qui indique à rcc le pourcentage de la taille du fichier original qui doit être gagné pour qu'il stocke le fichier sous forme compressée.

rcc -threshold 25 myresources.qrc

La valeur par défaut est "70", ce qui signifie que le fichier compressé doit être 70 % plus petit que l'original (pas plus de 30 % de la taille du fichier original).

Il est possible de désactiver la compression si vous le souhaitez. Cela peut être utile si vos ressources contiennent déjà un format compressé, comme les fichiers .png, et que vous ne voulez pas avoir à supporter le coût de l'unité centrale au moment de la création pour confirmer que le fichier ne peut pas être compressé. Une autre raison est que l'utilisation du disque n'est pas un problème et que l'application préfère conserver le contenu sous forme de pages mémoire propres au moment de l'exécution. Vous pouvez le faire en donnant l'argument de ligne de commande -no-compress.

rcc -no-compress myresources.qrc

rcc Cette option vous permet également de contrôler le niveau de compression et l'algorithme de compression, par exemple :

rcc -compress 2 -compress-algo zlib myresources.qrc

Il est également possible d'utiliser compress, threshold comme attributs dans une balise .qrc file. Pour sélectionner l'algorithme, définissez l'attribut compression-algorithm.

<qresource>
    <file compress="1" compression-algorithm="zstd">data.txt</file>
</qresource>

L'exemple ci-dessus sélectionnera l'algorithme zstd avec le niveau de compression 1.

rcc prend en charge les algorithmes et les niveaux de compression suivants :

• bestalgorithme de compression : utilise le meilleur algorithme parmi les algorithmes ci-dessous, à son niveau de compression le plus élevé, afin d'obtenir la meilleure compression possible au prix d'une utilisation importante du temps de l'unité centrale pendant la compilation. Cette valeur est utile dans le fichier XML pour indiquer qu'un fichier doit être le plus compressé, quels que soient les algorithmes pris en charge par rcc.
• zstdLes algorithmes de compression suivants sont utilisés : la bibliothèque Zstandard pour compresser le contenu. Les niveaux de compression valides vont de 1 à 19, 1 étant la compression la plus faible (moins de temps CPU) et 19 la compression la plus forte (plus de temps CPU). Le niveau par défaut est 14. Une valeur spéciale de 0 indique à la bibliothèque zstd de choisir une valeur par défaut définie par l'implémentation.
• zlibLa bibliothèque utilise la bibliothèque zlib pour compresser les contenus. Les niveaux de compression valides vont de 1 à 9, 1 appliquant la compression la plus faible (moins de temps CPU) et 9 la compression la plus forte (plus de temps CPU). La valeur spéciale 0 signifie "pas de compression" et ne doit pas être utilisée. La valeur par défaut est définie par l'implémentation, mais il s'agit généralement du niveau 6.
• none0 : pas de compression. C'est la même chose que l'option -no-compress.

La prise en charge de Zstandard et de zlib est facultative. Si une bibliothèque donnée n'a pas été détectée au moment de la compilation, la tentative de passer -compress-algo pour cette bibliothèque entraînera une erreur. L'algorithme de compression par défaut est zstd s'il est activé, zlib dans le cas contraire.

Chargement et déchargement explicites des ressources intégrées

Les ressources intégrées dans le code d'un exécutable ou d'une bibliothèque C++ sont automatiquement enregistrées dans le système de ressources de Qt dans un constructeur d'une variable globale interne. Comme les variables globales sont initialisées avant l'exécution de main(), les ressources sont disponibles lorsque le programme commence à s'exécuter.

Lorsque vous intégrez des ressources dans des bibliothèques statiques, l'éditeur de liens C++ peut supprimer les variables statiques qui enregistrent les ressources. Si vous intégrez des ressources dans une bibliothèque statique, vous devez donc enregistrer explicitement vos ressources en appelant Q_INIT_RESOURCE() avec le nom de base du fichier .qrc. Par exemple :

MyClass::MyClass() : BaseClass()
{
    Q_INIT_RESOURCE(resources);

    QFile file(":/myfile.dat");
    //...
}

Vous pouvez également supprimer explicitement les ressources enregistrées de l'application, par exemple lors du déchargement d'un plugin. Pour ce faire, utilisez Q_CLEANUP_RESOURCE().

Remarque : les initialisateurs de ressources générés par rcc étant déclarés dans l'espace de noms global, vos appels à Q_INIT_RESOURCE() et Q_CLEANUP_RESOURCE() doivent être effectués en dehors de tout espace de noms.