Techniques de débogage

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

Configurer Qt pour le débogage

Lors de la configuration de Qt pour l'installation, il est possible de s'assurer qu'il est construit pour inclure des symboles de débogage qui peuvent faciliter la détection des bogues dans les applications et les bibliothèques. Cependant, sur certaines plateformes, la construction de Qt en mode débogage entraînera des applications plus volumineuses que souhaitable.

Débogage dans macOS et Xcode

Débogage avec/sans frameworks

Les informations de base que vous devez connaître sur les bibliothèques de débogage et les frameworks se trouvent sur developer.apple.com dans : Apple Technical Note TN2124.

Lorsque vous compilez Qt, les frameworks sont compilés par défaut, et à l'intérieur du framework vous trouverez à la fois une version release et une version debug (par exemple, QtCore et QtCore_debug). Si vous passez le drapeau -no-framework lorsque vous construisez Qt, deux dylibs sont construites pour chaque bibliothèque Qt (par exemple, libQtCore.4.dylib et libQtCore_debug.4.dylib).

Ce qui se passe lorsque vous créez un lien dépend de l'utilisation ou non de frameworks. Nous ne voyons pas de raison impérieuse de recommander l'un plutôt que l'autre.

Avec des frameworks :

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

Sans Frameworks :

Lorsque vous dites à qmake de générer un Makefile avec la configuration de débogage, il s'appuiera sur 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 plates-formes, et vous serez en mesure de tracer à l'intérieur de Qt.

Options de ligne de commande reconnues par Qt

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

Variables d'environnement reconnues par Qt

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

Messages d'avertissement et de débogage

Qt inclut des macros C++ globales pour écrire des messages d'avertissement et de débogage. Les macros simples utilisent une valeur par défaut logging category; les macros de journalisation catégorisées vous permettent de spécifier la catégorie. Vous pouvez les utiliser dans les buts suivants :

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 s'imprime sur la 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 imprimé. Vous pouvez inclure des informations supplémentaires en définissant la variable d'environnement QT_MESSAGE_PATTERN. Par exemple, le format est documenté dans :

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

Le format est documenté dans qSetMessagePattern(). Vous pouvez également installer votre propre gestionnaire de messages en utilisant qInstallMessageHandler().

Si la variable d'environnement QT_FATAL_WARNINGS est définie, qWarning() se termine après l'affichage du message d'avertissement. Cela facilite l'obtention d'une trace rétrospective dans le débogueur.

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

Les fonctions de débogage QObject::dumpObjectTree() et QObject::dumpObjectInfo() sont souvent utiles lorsqu'une application a un aspect ou un comportement étrange. Elles sont plus utiles si vous utilisez object names que si vous ne l'utilisez pas, mais elles sont souvent utiles même sans nom.

En QML, dumpItemTree() sert le même objectif.

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

Vous pouvez implémenter l'opérateur de flux utilisé par qDebug() pour fournir un support de débogage à vos classes. La classe qui implémente le flux est QDebug. Utilisez QDebugStateSaver pour sauvegarder temporairement les options de formatage du flux. Utilisez nospace() et QTextStream manipulators pour personnaliser davantage le formatage.

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 traitée plus en profondeur dans le document Création de types Qt personnalisés.

Débogage des macros

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

Trois macros importantes sont :

• Q_ASSERT(cond), où cond est une expression booléenne, écrit l'avertissement "ASSERT :'cond' in file xyz.cpp, line 234" et sort si cond est faux.
• Q_ASSERT_X(cond, where, what), où cond est une expression booléenne, where un emplacement et what un message, écrit l'avertissement : "ASSERT failure in where: 'what', file xyz.cpp, line 234" et sort si cond est faux.
• Q_CHECK_PTR(ptr), où ptr est un pointeur. Écrit l'avertissement "Dans le fichier xyz.cpp, ligne 234 : Out of memory" et quitte le programme si ptr vaut 0.

Ces macros sont utiles pour détecter les 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 se développent pas 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 une 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 QT_NO_DEBUG défini, le code dans 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 contrôles 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 lorsque vous développez des logiciels basés sur Qt.

La journalisation et categorized logging sont également possibles dans QML.

Bogues 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 exécutez 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 se plaignant d'un manque de vtbl, _vtbl, __vtbl ou similaire est probablement due à ce problème.