How To Use the Debugger

Below these steps are listed again, with details on how to perform them.

1. Comile your app with debugging enabled

   The GNU compiler supports several important switches which determine the type of code which is output. Of particular interest are -O, which causes your code to be optimized, and -g, which can't coexist with optimization, but provides debugging symbols in your code. While gdb can run without your app being compiled with -g, it's not very useful - all you get is raw data - no datatypes, no line numbers, nothing. In PRC-Tools, it is worth noting that the debugging symbols enabled with -g aren't made a part of your PRC file: They are stored in your linked code, but are stripped out by build-prc, which collects your app's resources into a single database for upload. So basically, look in your makefile for a CFLAGS or similar variable, put -g in there, take out -O optimization if it's in.

2. Install your compiled app in the emulator

   This one is pretty straightforward. Just load the apps into the emulator's memory. In POSE use the right-click menu.

3. Run gdb

   When you start gdb (or in this case, more often m68k-palmos-coff-gdb) you need to supply the name of the linked code as the first argument. Usually, when your code is built the linked code will appear in your work directory as an M68K COFF executable with your app's name as its filename, with no extension. For example, to debug AppView you would type m68k-palmos-coff-gdb AppView.

   I like to use the Emacs "Grand Unified Debugger" when debugging my Palm apps, and so have found the following snippet in my .emacs file to be useful:

   (defun gdb-palmos ()
     (interactive)
     (setq gdb-command-name "m68k-palmos-gdb")
     (call-interactively 'gdb)
   )
                 

   Then, M-x gdb-palmos will bring a prompt for the binary filename, then a GDB window in which you can enter the usual GDB commands: except that you'll also have Emacs tracking your current line, etc.
4. The Target command

   The target command in gdb specifies a means for debugging a program. The PRC-Tools version includes a target called pilot, which allows debugging of PalmOS code over a network connection. POSE normally listens on two different ports for debugging connections: the easier one to remember is 2000. Once you enter the command "target pilot localhost:2000" gdb will wait until you start your app.

5. Start your application

   If everything's working correctly, when you start your application on the emulator, gdb should catch it as a breakpoint, halt your app, and enter the debugging loop. From the gdb command line, you can then get a backtrace of the calling stack, look at local variables, set breakpoints, etc.

   Limitations and Caveats

   There are some limitations to what you can do with gdb. I don't know if these are still true:

   • When your app is executing PalmOS code, such as the API functions, the debugger is basically lost. This is a problem, for example, when your program passes bad data to a form object or data block, which is then used when your code returns control to PalmOS. GDB will halt with the crash, but you'll have no local variables, no useful stack trace, and few options for directly figuring out what happened.
   • While gdb can perform evaluations using your app's functions and data, some evaluations will cause a crash, presumably due to call stack overflow or the like.

   Front-ends

   The gdb command line interface is a pretty good way to debug code, but there are better ways that can be more productive depending on how you like to work.

   • Emacs has a gdb mode. If you can instruct Emacs to run the right copy of gdb with the right arguments, you'll have yourself a very nice integrated development environment.
   • DDD, the Data Display Debugger, is an open-source graphical front-end to GDB. Again, the challenge here is to get it to run the right debugger with the right arguments to get your debug session started. Once started, DDD offers some very nice graphical data representations and interface options.