@#
@# This is the source for the how-to-get-help file, in a weird custom format.
@# Read makedoc.c for a description of what is going on...
@#
@html_text_substitution=readme.txt|<a href="readme.html">readme.txt</a>
@document_title=What to do when your Allegro program doesn't work
@!html
@!rtf
	       ____      _   _   _               _   _      _
	      / ___| ___| |_| |_(_)_ __   __ _  | | | | ___| |_ __
	     | |  _ / _ \ __| __| | '_ \ / _` | | |_| |/ _ \ | '_ \
	     | |_| |  __/ |_| |_| | | | | (_| | |  _  |  __/ | |_) |
	      \____|\___|\__|\__|_|_| |_|\__, | |_| |_|\___|_| .__/
					 |___/               |_|



@html
@external-css=allegro.css
@rtf
@!text
<center><h1><b><i>
What to do when your Allegro program doesn't work
</i></b></h1></center>
<hr>
@heading
Contents

@shortcontents



@text
@heading
Introduction

   When things go wrong, it often seems like a good idea to ask other people 
   for help. Fortunately for people in this situation, there are many people 
   (both Allegro developers and users) who are happy to spend their time 
   answering support questions of this type, but there are various things 
   you can do to make this process work more efficiently. This document 
   describes some steps to take whenever you have a problem with an Allegro 
   program, suggesting ways that you can try to solve it yourself, and also 
   giving some tips about when/how to ask for help. Following these 
   guidelines will make life easier both for the helper (because all the 
   relevant information will be presented to them in a concise and useful 
   way), and for the helpee (because they are more likely to get a prompt 
   and accurate reply).



@heading
Part 1 - who is the culprit?

   Is the problem a bug in Allegro, or in your code? To find out, try 
   running the Allegro test programs, in particular the test.exe (for 
   graphics related problems), the play.exe (for soundcard troubles), and 
   the entire contents of the examples directory (for anything that is going 
   wrong). If you can't reproduce the problem with any of these, it is 
   probably your fault, in which case you should skip to part 3 below. 

   If the problem is related to DOS graphics modes, you should start by 
   getting a copy of Display Doctor from <link>http://www.scitechsoft.com/</a>.
   If this fixes the trouble, it almost certainly means that your original 
   VESA driver was broken in some way. I'm not interested in hearing reports 
   about problems of this type: there is nothing I can do to fix them, so 
   I'm afraid your only option is to get a better VESA driver, for instance
   by downloading Display Doctor. This is now free for download from SciTech's
   website, but there is no longer support for it. Alternatively, you can see
   if there is a FreeBE/AF driver for your card (see 
   <link>http://www.talula.demon.co.uk/freebe/</a>).

   For Windows graphics modes, you should probably check if DirectX is 
   installed properly on your system and if new drivers have been released for 
   your card.



@heading
Part 2 - when Allegro is at fault

   If you still think the problem lies with Allegro, post a system report 
   containing a description of the problem, what platform and library 
   version you are using, your hardware specs, and a list of exactly which 
   programs you were able to reproduce the problem with (it is important to 
   know not only what programs had trouble, but also which ones worked 
   correctly, if any).

   Try running the test.exe program with various display drivers (any native 
   drivers that you think might work with your card), and in various video 
   modes, and report exactly what modes and color depths cause problems. If 
   you are able to use any high resolutions at all, run test.exe with the 
   Autodetect option and report the entire text that it displays in the 
   middle of the screen.

   If the problem is related to DOS graphics modes, you should also post the 
   output from running the afinfo and vesainfo programs (the short version 
   is enough unless you are explicitly asked to add the -v switch: all that 
   extra data isn't usually needed).    

   If the problem is related to the sound system, try using the setup 
   program to manually configure your card. You may need to manually enter 
   the hardware parameters, and if it is an SB clone card, try selecting 
   some earlier breed of SB card than whatever it is autodetecting (SB Pro, 
   SB 2.0, or SB 1.0). If you are still unable to get anything working, your 
   post should include the name and descriptions of whatever digital and 
   MIDI sound drivers are being autodetected (this information is displayed 
   by the play.exe program).



@heading
Part 3 - when your program crashes

@hnode crashes under DOS
   When a djgpp program crashes, you will usually get a stack traceback 
   looking something like:
<textblock>
      Exiting due to signal SIGSEGV
      General Protection Fault at eip=00001eca
      [snip]

      Call frame traceback EIPs:
	0x00001eca
	0x00001590
	0x00001aea
<endblock>
   This information tells you exactly where the crash occurred. To make 
   sense of it, you should compile your program with debugging information 
   (using the -g switch), and then run "symify program.exe" while this 
   traceback is displayed onscreen. That will change the traceback to 
   something along the lines of:
<textblock>
      Call frame traceback EIPs:
	0x00001eca   _strcpy+14
	0x00001590   _main+56, line 7 of t.c
	0x00001aea   ___crt1_startup+138
<endblock>
   In this case, you can see that the crash occurred in the strcpy() 
   function, which was called at line 7 of the main() function in the t.c 
   source file. Now you just have to go to that line, have a look at 
   whatever you are doing there, and change it to be correct :-)

   Note: if the crash happens deep inside an Allegro function, this 
   traceback may not be so useful. When this happens you can recompile 
   Allegro with debugging information (see the readme file), and then 
   link your program with the debugging library version.

   Note 2: even when this crash traceback points to one of the Allegro 
   functions, that does not necessarily mean the Allegro routine is at 
   fault. Anything will crash if you pass it invalid parameters, so unless 
   you can duplicate the problem in one of the Allegro example programs, you 
   should start out by assuming that it is a case of operator error and 
   double-check exactly what you are passing to the Allegro function.

@hnode crashes under Linux/Unix
   When your Allegro compiled Linux/Unix program crashes, you will usually
   get a not very meaningful message along with a core dump:
<textblock>
      Shutting down Allegro due to signal #11
      Segment violation (core dumped)
<endblock>
   Look at your filesystem: there should be a file named core or something
   similar with information telling you exactly where the crash occurred.
   If there is no core, check your environment settings, under bash this is
   done with the 'ulimit -a' command. Usually 'ulimit -c unlimited'
   somewhere in your login scripts should work fine.

   Just like with djgpp, to make sense of the core, you should compile your
   program with debugging information (using the -g switch), and then run
   the GNU debugger on it "gdb binary core". That will load the debugger,
   print some information about linked libraries and leave you at a prompt.
   Now you can get the full backtrace:
<textblock>
      (gdb) backtrace
      #0  0x08065237 in utf8_getx (s=0xbffffc5c) at ./src/unicode.c:347
      #1  0x0806953f in ustrzcpy (dest=0x0, size=2147483646, src=0x0) at ./src/unicode.c:1770
      #2  0x08057575 in _mangled_main () at t.c:9
      #3  0x0806c9bf in main (argc=1, argv=0xbffffd14) at ./src/unix/umain.c:39
      #4  0x4015414f in __libc_start_main () from /lib/libc.so.6
<endblock>
   In this case, you can see that the crash occurred in the ustrzcpy()
   function, which was called at line 9 of the main() function in the t.c
   source file. Now you just have to go to that line, have a look at 
   whatever you are doing there, and change it to be correct :-)

   Note that the crash happened deep inside an Allegro function, which is
   also revealed by the traceback. However, the binary was linked against a
   static debug version of Allegro, we wouldn't have had so much luck with
   a non debug or dynamically linked version.

   Since gdb is an interactive debugger, you could also select a frame and
   check out the values of the variables, to see better who is the culprit:
<textblock>
      (gdb) frame 2
      #2  0x08057575 in _mangled_main () at t.c:9
      9          ustrcpy(p1, p2);
      (gdb) list
      4
      5       int main(void)
      6       {
      7          char *p1 = 0, *p2 = 0;
      8          allegro_init();
      9          ustrcpy(p1, p2);
      10         return 0;
      11      }
      12      END_OF_MAIN()
      (gdb) print p1
      $1 = 0x0
      (gdb) print p2
      $2 = 0x0
<endblock>
   Yuck! Playing with NULL values doesn't really pay off. Ok, while this was
   a slightly out-of-the-can example, you surely get the point. Remember to
   check out GDB's manual to learn about more useful commands and/or how to
   debug your program while it's running and many other things. You might also
   want to check out Peter Wang's "Debugging with GDB" article, featured in
   the ninth number of the Pixelate online magazine
   (<link>http://pixwiki.bafsoft.com/</a>).



@heading
Part 4 - things people don't do (but should)

   One of the most common errors made by programmers is to neglect to check 
   the return value from a function that may fail. Such an error will often 
   lead to unexpected and downright unusual errors, making for a debugging 
   nightmare. There are many functions in and out of Allegro that may or may 
   not work depending on varying circumstances. They are, however, nice 
   enough to let you know whether or not they were successful through 
   documented return values.

   Whenever you call a function that might fail (most importantly 
   set_gfx_mode(), install_sound(), and anything that loads data from the 
   disk), it is _essential_ that you check the return code from this, and 
   respond accordingly.

   Another commonly forgotten but important tool is to use whatever option 
   enables strict warnings for your compiler (gcc uses -Wall), when 
   compiling your code. Any warnings reported by this option will almost 
   certainly represent errors in your program, and should be fixed before 
   doing anything else. When using gcc, a useful trick is to compile with 
   the -O setting as well, because this causes gcc to examine the program's 
   actions in more detail, enabling more useful warnings. You should 
   normally disable optimisation while debugging, though. Although it gives 
   better compile time warnings, it is likely to upset any debugging tools 
   that you later try to use.



@heading
Part 5 - asking for help

   Ok, so you've tried everything described above, and your program still 
   doesn't work. You have no idea what to do next, so it is time to cast 
   yourself unto the mercies of the net, in hopes of finding some kind of 
   wise man, seer, or oracle that holds an answer for your question...

   The best places to ask are the Allegro mailing list (see readme.txt for 
   details) and the Allegro.cc forums. Please remember that the mailing list 
   is an Allegro-specific list. Problems relating to the C language or djgpp 
   compiler belong in other forums (comp.lang.c and comp.os.msdos.djgpp 
   respectively). The Allegro.cc forums can be found at 
   <link>http://www.allegro.cc/</a>. You can usually ask any question related
   to Allegro here.   
   
   Both the Allegro and djgpp mailing lists are archived, and can be 
   searched via their respective homepages. It is very likely that you will 
   be able to find a solution to your problem by looking through the answers 
   to past questions, which will save you needing to post a query at all.

   In accordance with proper netiquette, it is assumed that when you post to 
   any forum on the Internet you have at least consulted the relevant 
   documentation first, if not read it in its entirety. If the problem you 
   are having is worth asking hundreds of people the answer for, then it is 
   certainly worth taking a few minutes to try to solve the problem 
   yourself. Allegro is extensively and painstakingly documented and it is 
   considered a prerequisite to posting that you have not only read the 
   text, but examined the example programs as well.



@heading
Part 6 - learn from my mistakes

   What not to do, Part One:
<textblock>
      "My program crashes. Please tell me why."
<endblock>
   Yes, people really do sometimes send me questions like this :-) Despite 
   years of practice I am still totally unable to read minds, so this is a 
   very pointless thing to ask. In order to get help with a problem you must 
   describe it in enough detail that other people will be able to understand 
   and reproduce it: this usually means posting some of your source code.


   What not to do, Part Two:
<textblock>
      "I've got a problem with my program. I'm attaching a 500k zip file 
      containing ten thousand lines of source code and all the graphics and 
      sound data: can you please debug it and tell me what the trouble is?"
<endblock>
   After wasting the time and phone bills to download such a huge file, it 
   is unlikely that anyone will even _want_ to help you, let alone invest 
   the amount of time it would take to read and understand such a huge mess 
   of information. You must try to isolate a smaller chunk of code that 
   demonstrates the trouble: the smaller you can make it, the more chance 
   that someone will be able to help you with it. Remember that you are 
   asking other people to do you a favour, so it is your responsibility to 
   make this process as easy for them as you possibly can.



@heading
Part 7 - wording your plea

   The most important thing is to include code that can be compiled and 
   tested by the person reading your message. Don't just post your entire 
   program: try to extract a small section that includes the specific lines 
   causing your problem, or reproduces the trouble in a simpler way (you 
   will often find that you can locate the error yourself in the process of 
   making this simpler version, so it is a good exercise in itself). This 
   code should be a small but complete program that can actually be compiled 
   and run, because it is very hard to debug incomplete code fragments.

   It is best to include the code directly in the text of your email 
   message, because it is easier for people to read this than if they have 
   to extract it from an attachment.

   Ideally your example should avoid using any external graphics and data 
   files. It is ok to include a small (max 2k) zip containing such 
   information, or failing that a description of what other files it needs 
   (eg. "put a 32x32 .pcx file called 'tile.pcx' into the same directory as 
   the program). If there is no way that you can simplify things this far, 
   you should upload the program and data to a website and then just post 
   that URL in your message.

   You should say what compiler options you used to build the program. These
   should include extra warnings. If you use gcc, post the list of compiler
   switches you used.

   Describe what you intended this program to do (it may not be instantly 
   obvious to other people), and also what it really does when you run it. 
   There is usually no need to post the actual crash traceback (other people 
   can duplicate this for themselves as long as they are able to compile and 
   run your code), but you should say whether you do get such a traceback, 
   or a lockup, or just incorrect results (and if so, in exactly what way 
   they differ from what you were expecting). It is useful to mark your 
   source with a comment to show what line the crash traceback points to.

   Any other information that you can include may also be useful. Most 
   importantly a brief machine description, information about any relevant 
   drivers, and your Allegro version (please don't just say "WIP", but give 
   the exact date if you are using anything other than an official numbered 
   release). 



@heading
Part 8 - a model of perfection

   For reference, here is an example of what I would consider to be an ideal 
   problem report:

<textblock>
   I'm having some trouble using the hicolor video modes in my program, 
   although they work fine with the Allegro tests. I'm using Allegro 4.0 
   with MinGW 3.1.0 (gcc version 3.3.1) on a Pentium 1.2GHz, running under
   Windows 2000 and an ATi Radeon 7000 videocard.

   This program is supposed to select a 640x480 16 bit resolution, draw a 
   blue rectangle near the top left corner of the screen, and then wait for 
   a keypress before quitting, but I just get a General Protection Fault 
   when I run it.

   I compile it using "gcc -Wall t.c -o t.exe -lalleg", and don't get any 
   warnings.


   --- cut here, t.c ---

   #include &ltstdio.h&gt
   #include &ltallegro.h&gt

   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);

      /* crashes during this rectangle call! */
      rectfill(bmp, 32, 32, 64, 64, 0x001F);

      readkey();
   }
<endblock>

