Quand les choses vont mal, çà semble souvent être une bonne idée de demander de l'aide à d'autres personnes. Heureusement, pour ceux qui sont dans cette situation, il y a pas mal de gens (aussi bien développeurs qu'utilisateurs d'Allegro) qui sont prêts à donner de leur temps pour répondre à ce genre de questions, mais il y a certaines choses que vous pouvez faire pour rendre ce processus plus efficace. Ce document décrit quelques étapes à suivre quand vous avez un problème avec un programme Allegro, en suggérant quelques méthodes à essayer pour en venir à bout vous-même, et aussi en vous donnant quelques conseils pour savoir quand et comment demander de l'aide. En suivant ces indications, vous rendrez la vie plus facile aussi bien aux personnes qui vous aideront (parce que toutes les informations nécessaires leurs seront présentées d'une façon concise et pratique), que pour les personnes en difficulté (parce qu'elles auront plus de chance d'avoir une réponse rapide et exacte).
Est-ce que le problème est du à un bug dans Allegro, ou dans votre code ? Pour le savoir, essayez de lancer les programmes de test d'Allegro, en particulier le programme test.exe (pour les problèmes liés aux graphiques), play.exe (pour les problèmes de carte son), et tous les programmes du répertoire examples (pour tous les types de problèmes). Si vous n'arrivez à reproduire le problème avec aucun de ces programmes, c'est probablement de votre faute, auquel cas vous devriez sauter à la partie 3 un peu plus bas.
Si le problème est lié aux modes graphiques DOS, vous devriez commencer par récupérer Display Doctor à http://www.scitechsoft.com/. Si çà règle le problème, çà veut surement dire que votre driver VESA d'origine est défectueux d'une façon ou d'une autre. Je n'ai pas envie de recevoir des rapports à propos de problèmes de ce type : je ne peux rien faire pour les corriger, donc j'ai bien peur que votre seule option soit de récupérer un meilleur driver VESA, soit en demandant au constructeur de corriger ses bugs, soit en achetant Display Doctor, ou encore en écrivant un driver FreeBE/AF pour votre carte (dans ce cas regardez http://www.talula.demon.co.uk/freebe/).
Si vous pensez toujours que le problème vient d'Allegro, postez un rapport contenant une description du problème, de la platforme et de la version de la librairie que vous utilisez, de vos spécifications matérielles, et une liste exacte des programmes avec lesquels vous avez pu reproduire le problème (il est important de savoir non seulement quels programmes posent problème, mais également lesquels fonctionnent correctement, s'il y en a).
Si le problème est lié à des modes graphiques DOS, vous devriez aussi poster le résultat des sorties produites en lançant les programmes afinfo et vesainfo (la version courte est suffisante si on ne vous demande pas explicitement d'ajouter le paramètre -v : ces données supplémentaires ne sont généralement pas nécessaires). Essayez de lancer le programme test.exe avec différents drivers Allegro (tous les drivers natifs qui selon vous devraient fonctionner avec votre carte, les drivers VESA 2.0 et VESA 1.x), et dans différents modes vidéos, et précisez exactement quels modes graphiques et quels modes de couleur [color depths] causent des problèmes. Si vous ne pouvez utiliser aucune résolution SVGA, lancez test.exe avec l'option Autodetect et rapportez l'ensemble du texte qu'il affiche au milieu de l'écran.
Si le problème est lié au système sonore DOS, essayez d'utiliser le programme de setup pour configurer votre carte manuellement. Vous pouvez avoir besoin de saisir manuellement les paramètres matériels, et si votre carte est un clône SB, essayez de sélectionner un modèle plus ancien de carte SB que celui qui est autodétecté (SB Pro, SB 2.0, ou SB 1.0). Si vous n'arrivez toujours pas à faire fonctionner quoi que ce soit, votre rapport devrait inclure le nom et la description des drivers sons digitaux et MIDI qui sont autodétectés (cette information est affichée par le programme play.exe).
Quand un programme djgpp plante, vous devez habituellement récupérer une trace de la pile ressemblant à quelque chose comme çà :
Exiting due to signal SIGSEGV
General Protection Fault at eip=00001eca
[snip]
Call frame traceback EIPs:
0x00001eca
0x00001590
0x00001aea
Cette information vous dit exactement où le plantage s'est produit. Pour la
rendre compréhensible, vous devriez compiler votre programme avec les options
de débuggage (en utilisant le paramètre -g), puis lancer "symify program.exe"
quand ce message est affiché à l'écran. Cette commande va changer le message
d'erreur en produisant quelque chose comme ceci à la suite des lignes
originales :
Call frame traceback EIPs:
0x00001eca _strcpy+14
0x00001590 _main+56, line 7 of t.c
0x00001aea ___crt1_startup+138
Dans ce cas, vous pouvez constater que le plantage s'est produit dans la
fonction strcpy(), qui a été appelée à la ligne 7 de la fonction main() dans
le fichier source t.c. Maintenant, vous avez juste à aller à cette ligne,
jeter un oeil à ce que vous faites à cet endroit, et à le changer pour que ce
soit correct :-)
Note: si le plantage se produit à l'intérieur d'une fonction Allegro, le message d'erreur ne sera pas forcément aussi utile. Quand çà arrive vous pouvez recompiler Allegro avec les informations de debuggage (regardez le fichier readme), puis lier votre programme avec la version de débuggage de la librairie.
Note 2: même si ce message de plantage pointe sur une des fonctions d'Allegro, çà ne veut pas forcément dire que la routine d'Allegro est en cause. N'importe quoi peut planter si vous passez des paramètres invalides, donc jusqu'à ce que vous puissiez reproduire le problème dans un des programmes d'exemple d'Allegro, vous devriez supposer que c'est une erreur de type d'opérateur et vous devriez revérifier exactement ce que vous passez comme paramètres à la fonction d'Allegro.
Une des erreurs les plus courantes faite par les programmeurs est de négliger de vérifier la valeur de retour d'une fonction qui peut échouer. Une telle erreur produit souvent des erreurs vraiment inattendues, rendant le débuggage cauchemardesque. Il y a beaucoup de fonctions dans et en dehors d'Allegro qui peuvent ou peuvent ne pas marcher dans différentes circonstances. Elles sont, malgré tout, généralement suffisamment bien écrites pour vous permettre de sa voir si elles se sont bien déroulées en renvoyant des valeurs de retour documentées.
Quand vous appelez une fonction qui peut échouer (le plus souvent set_gfx_mode(), install_sound(), et tout ce qui charge des données à partir du disque), il est _essentiel_ que vous preniez la peine de vérifier le code de retour, et de réagir à ce code convenablement.
Un autre élément souvent oublié mais important, est d'utiliser toutes les options permettant d'activer les warnings de votre compilateur (gcc utilise -Wall), quand vous compilez votre code. Tous les warnings affichés par cette option vont dans la plupart des cas certainement mettre en évidence des erreurs dans votre programme, et devraient être corrigés avant d'envisager quoi que ce soit d'autre. Si vous utilisez gcc, une astuce utile consiste à compiler également avec le paramètre -O, parce que cela oblige gcc à examiner les opérations du programme plus en détail, permettant l'affichage de warning plus utiles. Normalement vous devriez également désactiver les options d'optimisation quand vous débuggez. Bien que cela donne des meilleurs warnings pendant la compilation, çà a de grandes chances de perturber l'outil de débuggage que vous essayerez d'utiliser par la suite.
D'accord, vous avez essayé tout ce qui est décrit avant, et votre programme ne marche toujours pas. Vous n'avez aucune idée de ce qu'il faut faire après çà, donc c'est le moment de vous en remettre aux grâces du net, dans l'espoir de trouver une sorte d'homme sage, de voyant, ou d'oracle qui détient la réponse à votre question...
Le meilleur endroit pour demander est la liste de diffusion [mailing list] d'Allegro : regardez readme.txt pour les détails. S'il vous plaît, rappelez-vous quand même que c'est une liste spécifique à Allegro. Les problèmes liés au langage C ou au compilateur djgpp concernent d'autres forums (comp.lang.c et comp.os.msdos.djgpp respectivement).
Les listes de diffusion d'Allegro et de djgpp sont archivées, et peuvent être consultées à partir de leurs pages d'accueil respectives. Il y a de bonnes chances que vous puissiez trouver une solution à votre problème en regardant les réponses aux questions déjà posées, ce qui vous permettra d'éviter d'avoir à poster une question.
En accord avec la netiquette, il est supposé que quand vous postez sur n'importe quel forum sur Internet vous avez au moins d'abord consulté la documentation appropriée, si vous ne l'avez pas lue dans sa totalité. Si le problème que vous avez mérite que vous demandiez une réponse à plusieurs centaines de personnes, alors çà vaut certainement la peine de prendre quelques minutes pour essayer de le corriger vous-même. Allegro est documenté de façon extensive et soigneuse et il est considéré comme un pré-requis avant de poster que vous ayez non seulement lu le texte, mais également examiné les programmes d'exemple.
Ce qu'il ne faut pas faire, Première Partie :
"Mon programme plante. S'il vous plaît dites moi pourquoi."
Oui, il arrive que certaines personnes m'envoient réellement des questions de
ce genre :-) Malgré des années de pratique je suis encore complètement
incapable de lire dans les esprits, donc c'est vraiment inutile de poser ce
genre de question. Pour trouver de l'aide pour résoudre un problème vous
devez le décrire suffisamment en détail pour que d'autres personnes puissent
le comprendre et le reproduire : çà signifie généralement poster un bout de
votre code source.
Ce qu'il ne faut pas faire, Deuxième Partie :
"J'ai un problème avec mon programme. J'ai attaché un fichier zip de 500
Ko contenant dix mille lignes de code source et toutes les données
graphiques et sonores : s'il vous plaît, est-ce que vous pourriez le
débugger et me dire quel est le problème ?"
Après avoir perdu du temps et l'argent de la communication téléphonique à
télécharger un si gros fichier, il y a peu de chance que qui que se soit
_veuille_ vous aider, sans parler du temps qu'il faudrait passer à lire et
comprendre un si gros paquet d'information. Vous devez essayer d'isoler un
plus petit bout de code qui met en évidence le problème: plus il sera petit,
plus vous aurez de chances que quelqu'un puisse vous aider. Rappelez vous
que vous êtes en train de demander à d'autres personnes de vous accorder une
faveur, donc il est de votre responsabilité de rendre ce processus aussi
simple pour eux que vous le pouvez.
La chose la plus importante est d'inclure du code qui pourra être compilé et testé par la personne qui va lire votre message. Ne postez pas juste votre programme complet : essayez d'extraire une petite section qui inclut les lignes spécifiques qui causent votre problème, ou reproduisez le d'une façon plus simple (vous allez vous rendre compte que vous pouvez souvent localiser l'erreur en le faisant, donc c'est un bon exercice en soi). Ce code doit être un programme petit mais complet qui peut être compilé et exécuté, parce qu'il est très difficile de débugger des fragments de code incomplets.
Il est préférable d'inclure le code directement dans le texte de votre message, parce que c'est plus facile à lire pour les autres que s'ils avaient à l'extraire d'un attachement.
Idéalement votre exemple devrait éviter d'avoir à utiliser des données graphiques ou d'un autre type à partir de fichiers. Il n'y a pas de problème si vous incluez un petit (2 Ko max) fichier zip contenant des données, ou une description des autres fichiers nécessaires (ex : mettez un fichier 'tile.pcx' de 32x32 au format pcx dans le même répertoire que le programme). Si vous ne pouvez pas simplifier les choses de cette façon, vous devriez placer le programme et les données sur un site web puis juste poster l'adresse du site dans votre message.
Vous devriez dire quelle ligne de commande gcc vous utilisez pour compiler le programme, et elle devrait inclure le paramètre -Wall.
Décrivez ce que vous voulez que ce programme fasse (ce n'est pas forcément évident immédiatemment pour tout le monde), et également ce qu'il fait réellement quand vous le lancez. Il n'est généralement pas nécessaire de poster le message d'erreur du plantage (les autres personnes peuvent le reproduire eux-mêmes s'ils peuvent compiler et exécuter votre code), mais vous devriez dire si vous obtenez un message d'erreur, un blocage, ou seulement des résultats incorrects (et si c'est le cas, en quoi diffèrent-ils exactement de ce que vous attendiez). Il est utile de marquer votre source avec un commentaire montrant quelle est la ligne correspondant au plantage.
Toute autre information que vous pouvez inclure peut également se révéler utile. Plus généralement une brève description de la machine, des drivers utilisés, et de la version d'Allegro que vous utilisez (s'il vous plaît ne dites pas juste "WIP", mais donnez la date exacte date si vous utilisez autre chose qu'une version numérotée officiellement).
A titre de référence, voici un exemple de ce que je considère comme étant un rapport de problème idéal :
J'ai quelques problèmes lorsque j'utilise les modes vidéos hicolor dans mon programme, bien qu'ils fonctionnent correctement dans les tests d'Allegro. J'utilise la version 3.0 d'Allegro avec la version 2.02 de djgpp (gcc version 2.8.1) sur un p166, sous win95 et en utilisant les drivers VESA 2.0 intégrés, que le programme vesainfo décrit comme "Matrox Graphics Inc.".Ce programme est sensé sélectionner une résolution de 640x480 en 16 bits, dessiner un rectangle bleu près du coin en haut à gauche de l'écran, puis il attend qu'une touche soit pressée avant de quitter, mais j'obtiens juste une erreur de protection générale [General Protection Fault] quand je le lance.
Je compile en utilisant la commande "gcc -Wall t.c -o t.exe -lalleg", et je n'ai aucun warning.
--- cut here, t.c ---
#include <stdio.h> #include <allegro.h>
void main() { BITMAP *bmp = screen;
install_keyboard();
if (set_gfx_mode(GFX_AUTODETECT, 640, 480, 0, 0) != 0) { printf("Error setting video mode\n"); return; }
set_color_depth(16);
/* plantage à l'appel de cet appel de tracé de rectangle ! */ rectfill(bmp, 32, 32, 64, 64, 0x001F);
readkey(); }