Techniques de débogage

Nous vous présentons ici quelques conseils utiles pour vous aider à déboguer vos logiciels basés sur Qt.

Configuration de Qt pour le débogage

Lors de la configuration de Qt pour l'installation, il est possible de s'assurer qu'il est compilé de manière à inclure des symboles de débogage qui facilitent la recherche de bogues dans les applications et les bibliothèques. Cependant, sur certaines plateformes, la compilation de Qt en mode débogage entraîne une taille d'application plus importante que souhaitable.

Débogage sous macOS et Xcode

Débogage avec ou sans frameworks

Les informations de base à connaître concernant les bibliothèques et les frameworks de débogage se trouvent sur developer.apple.com dans la note technique Apple TN2124.

Lorsque vous compilez Qt, les frameworks sont générés par défaut ; à l’intérieur de chaque framework, vous trouverez à la fois une version « release » et une version « debug » (par exemple, QtCore et QtCore_debug). Si vous passez l’option « -no-framework » lors de la compilation de Qt, deux bibliothèques dylib sont générées pour chaque bibliothèque Qt (par exemple, libQtCore.4.dylib et libQtCore_debug.4.dylib).

Le résultat de la liaison dépend de l’utilisation ou non de frameworks. Nous ne voyons aucune raison valable de recommander l’une plutôt que l’autre.

Avec les frameworks :

Comme les bibliothèques de version finale et de débogage se trouvent dans le framework, l'application est simplement liée au framework. Ensuite, lorsque vous l'exécutez dans le débogueur, vous obtenez soit la version finale, soit la version de débogage, selon que vous avez défini ou non DYLD_IMAGE_SUFFIX. Si vous ne le définissez pas, vous obtenez la version finale par défaut (c'est-à-dire non _debug). Si vous définissez DYLD_IMAGE_SUFFIX=_debug, vous obtenez la version de débogage.

Sans Frameworks :

Lorsque vous demandez à qmake de générer un Makefile avec la configuration de débogage, il effectuera la liaison avec la version _debug des bibliothèques et générera des symboles de débogage pour l'application. L'exécution de ce programme dans GDB fonctionnera alors comme l'exécution de GDB sur d’autres plateformes, et vous pourrez effectuer un traçage au sein de Qt.

Options de ligne de commande reconnues par Qt

Lorsque vous exécutez une application Qt, vous pouvez spécifier plusieurs options de ligne de commande qui peuvent faciliter le débogage. Celles-ci sont reconnues par QApplication.

Variables d’environnement reconnues par Qt

Au moment de l'exécution, une application Qt reconnaît de nombreuses variables d'environnement, dont certaines peuvent s'avérer utiles pour le débogage :

Messages d’avertissement et de débogage

Qt inclut des macros C++ globales permettant d’afficher des messages d’avertissement et de débogage. Les macros simples utilisent un format par défaut logging category; les macros de journalisation par catégorie vous permettent de spécifier la catégorie. Vous pouvez les utiliser aux fins suivantes :

Si vous incluez le fichier d’en-tête <QtDebug>, la macro qDebug() peut également être utilisée comme flux de sortie. Par exemple :

qDebug() << "Widget" << widget << "at position" << widget->pos();

L'implémentation Qt de ces macros affiche les messages dans le flux de sortie stderr sous Unix/Linux et macOS. Sous Windows, s'il s'agit d'une application console, le texte est envoyé à la console ; sinon, il est envoyé au débogueur.

Par défaut, seul le message est affiché. Vous pouvez inclure des informations supplémentaires en définissant la variable d’environnement QT_MESSAGE_PATTERN. Par exemple :

QT_MESSAGE_PATTERN="[%{time process} %{type}] %{appname} %{category} %{function} - %{message}"

Le format est documenté dans la fonction ` qSetMessagePattern()`. Vous pouvez également installer votre propre gestionnaire de messages à l’aide de la fonction ` qInstallMessageHandler()`.

Si la variable d’environnement QT_FATAL_WARNINGS est définie, la fonction qWarning() se termine après avoir affiché le message d’avertissement. Cela facilite l’obtention d’une trace de pile dans le débogueur.

qDebug(), qInfo() et qWarning() sont des outils de débogage. Ils peuvent être désactivés lors de la compilation en définissant QT_NO_DEBUG_OUTPUT, QT_NO_INFO_OUTPUT ou QT_NO_WARNING_OUTPUT.

Les fonctions de débogage QObject::dumpObjectTree() et QObject::dumpObjectInfo() s’avèrent souvent utiles lorsqu’une application présente un comportement ou un aspect inhabituel. Elles sont d’autant plus utiles si vous utilisez object names, mais restent souvent pratiques même sans cette définition.

En QML, dumpItemTree() remplit la même fonction.

Prise en charge de l’opérateur de flux qDebug()

Vous pouvez implémenter l’opérateur de flux utilisé par qDebug() afin de fournir une prise en charge du débogage pour vos classes. La classe qui implémente le flux est QDebug. Utilisez QDebugStateSaver pour enregistrer temporairement les options de mise en forme du flux. Utilisez nospace() et QTextStream manipulators pour personnaliser davantage la mise en forme.

Voici un exemple de classe représentant une coordonnée 2D.

QDebug operator<<(QDebug dbg, const Coordinate &c)
{
    QDebugStateSaver saver(dbg);
    dbg.nospace() << "(" << c.x() << ", " << c.y() << ")";

    return dbg;
}

L'intégration des types personnalisés au système de méta-objets de Qt est abordée plus en détail dans le document Création de types Qt personnalisés.

Macros de débogage

Le fichier d'en-tête <QtGlobal> contient plusieurs macros de débogage et des #defines.

Voici trois macros importantes :

• Q_ASSERT(cond), où cond est une expression booléenne, affiche l’avertissement « ASSERT :'cond' dans le fichier xyz.cpp, ligne 234 » et quitte le programme si cond est faux.
• Q_ASSERT_X(cond, where, what), où cond est une expression booléenne, where un emplacement et what un message, affiche l'avertissement : « Échec d'ASSERT dans where: 'what', fichier xyz.cpp, ligne 234 » et quitte le programme si cond est faux.
• Q_CHECK_PTR(ptr), où ptr est un pointeur. Affiche l’avertissement « Dans le fichier xyz.cpp, ligne 234 : mémoire insuffisante » et se termine si ptr vaut 0.

Ces macros sont utiles pour détecter des erreurs de programme, par exemple comme ceci :

char *alloc(int size)
{
    Q_ASSERT(size > 0);
    char *ptr = new char[size];
    Q_CHECK_PTR(ptr);
    return ptr;
}

Q_ASSERT(), Q_ASSERT_X() et Q_CHECK_PTR() ne donnent rien si QT_NO_DEBUG est défini lors de la compilation. C'est pourquoi les arguments de ces macros ne doivent pas avoir d'effets secondaires. Voici un exemple d'utilisation incorrecte de Q_CHECK_PTR():

char *alloc(int size)
{
    char *ptr;
    Q_CHECK_PTR(ptr = new char[size]);  // WRONG
    return ptr;
}

Si ce code est compilé avec la définition de ` QT_NO_DEBUG `, le code de l'expression ` Q_CHECK_PTR()` n'est pas exécuté et `alloc` renvoie un pointeur non initialisé.

La bibliothèque Qt contient des centaines de vérifications internes qui affichent des messages d’avertissement lorsqu’une erreur de programmation est détectée. Nous vous recommandons donc d’utiliser une version de débogage de Qt lors du développement de logiciels basés sur Qt.

La journalisation et l'categorized logging sont également possibles en QML.

Bugs courants

Il existe un bogue si courant qu’il mérite d’être mentionné ici : si vous incluez la macro Q_OBJECT dans une déclaration de classe et que vous lancez le Meta-Object Compiler (moc), mais que vous oubliez de lier le code objet généré par moc à votre exécutable, vous obtiendrez des messages d’erreur très déroutants. Toute erreur de liaison signalant l’absence de vtbl, _vtbl, __vtbl ou tout autre fichier similaire est probablement due à ce problème.