Developer Release Notes: bdb 1.2, for BeOS R5+

Debugging with bdb Developer Release Notes

The Intel-only bdb source code debugger was new in Release 4.5. You can find it in the /boot/develop/tools/experimental/debugger/ directory. There is no real manual yet, but until one appears take note of the following:

Preparing your module for debugging

To compile a module (app, add-on, library) for debugging, you must include the -g and optionally -O0 (that's "capital-oh zero") compiler switches. "-g" tells the compiler to produce symbols, and "-O0" sets the optimization level to zero, i.e. no optimzation at all.

To generate debugging information from the BeIDE, select Project > Enable Debugger, or go to the Code Generation/x86 Code Generation panel in the Settings Window and turn on Generate debugging information.

Selective debugging

Generating debugging information can really bloat your object files. Fortunately, you don't have to generate this information for an entire system if all you want to do is debug a single module. For example, if you want to debug an add-on, you only have to generate information for that add-on— the app that will load the add-on doesn't have to be debuggable.

Launching bdb from the command line

As mentioned above, bdb is installed in /boot/develop/tools/experimental/debugger/. This directory probably isn't in your search path. If you want to be able to launch bdb from the command line, we suggest that you put a symbolic link to it in your /boot/home/config/bin directory. To do this, type the following command at any Terminal prompt:

`ln -s -f /boot/develop/tools/experimental/debugger/bdb /boot/home/config/bin/bdb`

When you launch bdb from the command line, any arguments you supply are propagated to the app. Note that you don't have to specify an application to debug when you launch from the command line. You can simply launch the debugger and then use the Running Teams Window (explained below) to choose a team to debug.

Launching bdb from BeIDE

The BeIDE will launch bdb for you (even if you haven't changed your search path or installed a symlink to the bdb binary). To tell BeIDE to run your program inside the debugger, select Project > Debug command to launch the bdb source code debugger when your application is run.

Launching bdb by drag and drop

You can also launch bdb by dropping an application icon on the bdb icon. A particularly handy trick is to create a link to bdb from the desktop. When you want to debug an app, you don't have to launch BeIDE, bring up a Terminal, or go crawling through Tracker folder windows—just drop the app's icon on the bdb link.

Windows

When you launch bdb you'll see (at least) two windows: One window represents your entire app ("Team: AppName"), and the other represents a particular thread in the team ("ThreadName"). The illustration here shows the windows for the BeApp application.

The team window (the one that's partially obscured in the illustration) lists the threads that comprise the app. Click on a thread name to bring up that thread's window.

The Thread Window

Most of the action takes place in a thread window. That's where you set breakpoints and step through code. To set a breakpoint, click on a hash mark in the left margin. A little red "x" appears, as shown here. Alt+click creates a one-shot breakpoint (the breakpoint is thrown away after one use).

To step through code, use the commands in the Debug menu, or use the icons at the top of the code display. If you're not sure what command an icon designates, simply poise the mouse over the icon and a little yellow box appears that tells you what it does.

The Function popup menu button [labelled "f(x)"] displays the functions in that source file in the order that they appear in the file. In order to sort them alphabetically, Option+click on the popup button.

Some other subtleties:

- The PC arrow (the little blue arrow between the breakpoints and the code) is draggable. Obviously, you have to be careful with this, but you can reset the PC simply be pointing the arrow to a line of code.

- When you first step into a function, the stack frame (for that function) won't yet be initialized. You have to step one more time to set things up. In particular, the function's variables will be garbage until you take that extra step.

- If you set a breakpoint in multi-threaded code, you'll get a separate Thread Window for every thread that hits that breakpoint. Don't be confused—the threads are executing the same code.

Running Teams
When you launch bdb one of the windows that appears is called "Running Teams". This lists all the teams that are running on your system. Teams are listed even if they're not debuggable. To attach bdb to a team, simply click on it.

Watchpoints and Malloc Debug

Definitely visit the Window menu. There you'll find a command that lets you set a watchpoint (Set Watchpoint...). (Watchpoint setting is little bit primitive—you have to type the exact address that you want to watch in a text view.).

The Window > Settings... command brings up the Settings Window, shown here, where you can set various preferences. Take particular note of the Malloc Debug Level slider. As you increase the level of malloc debugging, the sensitivity to corrupt memory is heightened. If the memory checker finds something wrong, bdb pops up an alert to tell you about it.

Once bdb has popped up a debugger error message, you can use the Window > Show Debugger Message command in the Thread window to display a small window that shows you the text of the error message. This is particularly helpful for Malloc Debug errors, so you can refer to the stack-crawl addresses given in the debugger message.

Copyright © 1999-2001 Be, Inc. All rights reserved.