NOTE : Ce chapitre est une copie du document de Kalle Dalheimer kalle@kde.org expliquant les macros KDEBUG incluses dans le paquetage KDE-libs, à la page kdebug.html.
Dernière modification : Sat Sep 13 11:56:01 CEST 1997
Qu'est-ce que KDebug
KDebug est un système de macros et de fonctions qui rendent plus performante l'utilisation de messages de diagnostic dans votre code. Vous pouvez donner à un message un niveau de sévérité parmi 4 et une zone. Vous pouvez choisir à l'exécution où doivent aller les messages de diagnostic et lesquels doivent être imprimés. Voici comment utiliser KDebug dans votre code.
La macro KDEBUG
Utiliser KDebug est très simple. Tout ce que vous avez à faire, c'est d'ajouter &#;include &<;kdebug.h&>; au début de chaque fichier source dans lequel vous voulez utiliser les messages de diagnostic et les afficher en appelant la macro KDEBUG . Cette macro attend trois paramètres. Le premier est le niveau de sévérité. Utilisez une des constantes suivantes :
KDEBUG&_;INFO
KDEBUG&_;WARN
KDEBUG&_;ERROR
KDEBUG&_;FATAL
Le deuxième paramètres est la zone. Une zone est une partie de KDE que vous définissez vous-même. Ensuite, à l'exécution, vous pouvez choisir de quelles zones les messages de diagnostic doivent être imprimés. Veuillez consulter kdelibs/kdecore/kdebugareas.txt pour la liste des plages de zones déjà allouées. Choisissez une zone dans la plage allouée pour votre application. Si votre application n'y est pas déjà et que vous avez un accès CVS, vous pouvez y ajouter une plage pour votre application, sinon, envoyez-moi juste un courrier électronique. Il est probablement judicieux de définir des constantes symboliques pour les zones que vous voulez utiliser mais vous êtes entièrement maître à bord. Enfin, le troisième paramètre est le texte que vous voulez afficher. KDebug met automatiquement en préfixe le nom logique de l'application si vous effectuez la sortie dans un fichier, vers stderr (NdT : la sortie d'erreur standard) ou le syslog. Un changement de ligne est toujours ajouté donc vous n'avez pas besoin de (et ne devriez pas) le faire. Si vous avez besoin de paramètres, vous pouvez utiliser l'une des macros KDEBUG1, ..., KDEBUG9. Elles autorisent d'un à neuf paramètres. La syntaxe est exactement la même que printf ie vous devez inclure dans votre message les descripteurs de format qui seront remplacés par les paramètres additionnels. Voici un exemple :
KDEBUG3( <idx/KDEBUG_INFO/, kmail_composer, "Message no. %d to %s has %d bytes", message_no, aMessage.to(), aMessage.length() ); |
KASSERT
Il y a aussi les macros KASSERT, KASSERT1, ..., KASSERT9 qui fonctionnent comme leurs équivalents KDEBUG , sauf qu'elles ont un booléen supplémentaire comme premier paramètre. Le message sera affiché uniquement si ce paramètre vaut false. Note : vous ne devriez utiliser ni KDEBUG ni KASSERT avant que l'objet KApplication soit construit. Note 2& ;: KDebug ne fournit aucun support de l'internationalisation car il doit servir uniquement pour les développeurs. Si vous voulez informer l'utilisateur qu'une condition est refusée (comme "il est impossible d'écrire dans ce fichier"), utilisez KMsgBox.
Options de compilation
Aucune option de compilation supplémentaire n'est nécessaire pour utiliser KDebug. Mais quand vous sortez votre produit (cela s'applique essentiellement aux personnes qui créent des distributions comme les paquetages .rpm ou .deb), vous devriez compiler avec l'option -DNDEBUG. Cela supprimera simplement tout le code de déboguage de votre application et la rendra plus petite et plus rapide (par exemple, elle utilisera 256 ko de mémoire non partageable en moins).
Comment gérer les messages de diagnostic à l'exécution
Vous pouvez appuyer sur Ctrl-Shift-F12, à n'importe quel moment, dans toute KApplication et la boîte de dialogue "Debug Settings" apparaîtra. Vous pourrez y définir, séparément pour chaque niveau de sécurité, quoi faire avec les messages de diagnostic de ce niveau. Les configurations possibles sont les suivnates :
Output : dans cette liste déroulante, vous pouvez choisir où seront dirigés les messages. Les choix possibles sont : "File", "Message Box", "Shell" (c'est-à-dire stderr) et "syslog". Ne dirigez pas directement les messages fatals vers le syslog à moins que vous ne soyez vous-même administrateur système. La valeur par défaut est : "Message Box".
File : ceci est significatif seulement si vous avez dirigé les messages dans un fichier (NdT : option "File"). Ici, vous donnez le nom du fichier (relativement au répertoire courant) qui est défini à kdebug.dbg par défaut.
Area : les zones qui doivent être prises en compte. Chaque message qui n'est pas mentionné ici ne sera simplement pas affiché (à moins que ce champ reste vide qui est la valeur par défaut et signifie que tous les messages doivent être affichés). Vous pouvez saisir plusieurs zones séparées par des virgules et vous pouvez aussi utiliser des plages avec la syntaxe début-fin. Aussi, une entrée valide pourrait être : 117,214-289,356-359,221. Veuillez ne pas utiliser d'espace.
Sinon, vous pouvez aussi cocher la case "Abort on fatal errors". Dans ce cas, si un message de diagnostic ayant le niveau de sévérité "KDEBUG&_;FATAL " arrive, l'application s'arrête avec un signal SIGABRT après avoir affiché le message. Lorsque vous fermez la boîte de dialogue avec OK, vos choix s'appliquent immédiatement et sont enregistrés dans un fichier de configuration spécifique à l'application. N'oubliez pas que ces paramètres sont spécifiques à une seule application ! Lorsque vous appuyez sur Annuler, vos valeurs sont perdues et les anciennes sont restaurées.