
<HTML><HEAD>
<TITLE>
Developer Release Notes: BeOS Release 4.5, bdb
</TITLE>
</HEAD><BODY BGCOLOR='#ffeee0' link=#440044>
<CENTER>
	<table cellpadding=4>
	<TR>
	<TD><a href=../index.html>&nbsp;index&nbsp;</a>
	<TD><a href=../RN4.1_Headlines.html>&nbsp;headlines&nbsp;</a>
	<TD><a href=../RN4.1_AppKit.html>&nbsp;&lt;&lt;previous&nbsp;</a>
	<TD><a href=../BeIDE/RN4.1_BeIDE.html>&nbsp;next&gt;&gt;&nbsp;</a>
	</TABLE>
</CENTER>
<HR>


<TABLE cellpadding=20 bgcolor=ffeeff border= 4>
<TR><TD>
	<FONT SIZE="+4" color="#330033"><b>Debugging with bdb</FONT>
	<br>
	<i><FONT SIZE="+3" color="#330033">Developer Release Notes</FONT></i>
	<br>
	<i><FONT SIZE="+3" color="#330033">BeOS Release 4.5</FONT></i></b>
	
</TABLE>



<!----------------->
<HR>
<P>
<!----------------->

The Intel-only <b>bdb</b> source code debugger is new in Release 4.5.&nbsp;
You can find it in the <b>/boot/develop/tools/experimental/debugger/</b> directory.&nbsp;
Complete documentation is forthcoming, but until then, take note of
the following:
<P>
<hr>
<b><font color=880011 size=+1 face=helvetica>Preparing your module for debugging</font></b><P>
		To compile a module (app, add-on, library) for debugging, you must
	include the <b>-g</b> and <b>-O0</b> (that's "capital oh zero")
	compiler switches.&nbsp;
	This tells the compiler to produce symbols and sets the optimization
	level to 0.&nbsp;
	<P>
	To generate debugging information from the <b>BeIDE</b>,
	select <b><u>Project</u></b>&nbsp&gt&nbsp<b><u>Enable Debugger</u></b>, or
	go to the <b>Code Generation/x86 Code Generation</b>
	panel in the Settings Window and turn on
	<b><u>Generate debugging information</u></b>.
<P>
<hr>
<b><font color=880011 size=+1 face=helvetica>Selective debugging</font></b><P>
	Generating debugging information can really bloat your object files.&nbsp;
	Fortunately, you don't have to generate this information for an entire system if
	all you want to do is debug a single module.&nbsp;For example, if you want to
	debug an add-on, you only have to generate information for that add-on&mdash;
	the app that will load the add-on doesn't have to be debuggable.
<P>

<hr>
<b><font color=880011 size=+1 face=helvetica>Launching bdb from the command line</font></b><P>
	As mentioned above, <b>bdb</b> lives in
	<b>/boot/develop/tools/experimental/debugger/</b>.&nbsp;
	This directory probably isn't in your search path.&nbsp;
	If you want to be able to
	launch <b>bdb</b> from the command line, add this line to your
	<b>/boot/home/.profile</b> file:
	<P>
	<CODE>
	export PATH=$PATH:/boot/develop/tools/experimental/debugger
	</code>
	<P>
	When you launch <b>bdb</b> from the command line,
	any arguments you supply are propagated to the app.&nbsp;
	Note that you don't have to specify an application to debug when
	you launch from the command line.&nbsp;
	You can simply launch the debugger and then use the
	<a href=#TeamWindow>Running Teams Window</a>
	(explained below) to choose a team to debug.
	<P>
<hr>
<b><font color=880011 size=+1 face=helvetica>Launching bdb from BeIDE</font></b><P>	
	The BeIDE will launch <b>bdb</b> for you (even if you haven't
	massaged your search path).&nbsp;
	To tell BeIDE to run your program inside the debugger, select
	<b><u>Project</u></b>&nbsp&gt&nbsp<b><u>Debug</u></b> command launches the
	new <b>bdb</b> source code debugger.
<P>
<hr>
<b><font color=880011 size=+1 face=helvetica>Launching bdb by drag and drop</font></b><P>	
	You can also launch <b>bdb</b> by dropping an application icon
	on the <b>bdb</b> icon.&nbsp;
	A particularly handy trick is to create a link to <b>bdb</b> from
	the desktop.&nbsp;
	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&mdash;just drop
	the app's icon on the <b>bdb</b> link.
	
	
	<P>

<hr>
<b><font color=880011 size=+1 face=helvetica>Windows</font></b><P>
	When you launch <b>bdb</b> you'll see (at least) two windows:  One window
	represents your entire app ("Team: <i>AppName</i>"), and
	the other represents a particular thread in the team ("<i>ThreadName</i>").&nbsp;
	The illustration here shows the windows for the <b>BeApp</b> application.&nbsp;
	<img src=art/TeamBeApp.gif align=bottom border=2>
	<p>
	The team window (the one that's partially obscured in the illustration) lists
	the threads that comprise the app.&nbsp;
	Click on a thread name to bring up that thread's window.&nbsp;
	
	<P>
<hr>
<b><font color=880011 size=+1 face=helvetica>The Thread Window</font></b><P>
	<img src=art/Breakpoint.gif align=right border=2>
	Most of the action takes place in a
	thread window.&nbsp; That's where you set breakpoints and step through code.&nbsp;
	To set a breakpoint, click on a hash mark in the left margin.&nbsp;
	A little red "x" appears, as shown here.&nbsp;
	<b><u>Alt</b></u>+click creates a one-shot breakpoint (the breakpoint is
	thrown away after one use). 

	<P>


	<img src=art/IconCommands.gif align=right border=2>
	To step through code, use the commands in the <b><u>Debug</u></b> menu, or
	use the icons at the top of the code display.&nbsp;
	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.
	<P>
	Some other subtleties:
	<UL>
		<LI>The PC arrow (the little blue arrow between the breakpoints and
		the code) is draggable.&nbsp;Obviously, you have to be careful with this,
		but you can reset the PC simply be pointing the arrow to a line of code.
		<P>
		<LI>When you first step into a function, the stack frame
		(for that function) won't yet be
		initialized.&nbsp;
		You have to step one more time to set things up.&nbsp;In particular,
		the function's variables will be garbage until you take that extra step.
		<P>
		<LI>If you set a breakpoint in multi-threaded code, you'll get a
		separate Thread Window for each thread that hits that breakpoint.&nbsp;
		Don't be confused&mdash;the threads <i>are</i> executing the same code.
	</UL>
	<P>
<hr>
	<img src=art/TeamWindow.gif align=right border=2>
<a name=TeamWindow><b><font color=880011 size=+1 face=helvetica>Running Teams</font></b></a><br>
	When you launch <b>bdb</b> one of the windows that appears is called
	"Running Teams".&nbsp;
	This lists all the teams that are running on your system.&nbsp;Teams are listed even
	if they're not debuggable.&nbsp;To switch to a team, simply click on it.

	<P>

<hr>
<b><font color=880011 size=+1 face=helvetica>Watchpoints and Malloc Debug</font></b><P>
	Definitely visit the <b><u>Window</b></u> menu.&nbsp;
	There you'll find a command that lets you set a watchpoint
	(<b><u>Set Watchpoint...</b></u>).&nbsp;
	(Watchpoint setting is little bit primitive&mdash;you have to
	type the exact address that you want to watch in a text view.).
	<p>
	<img src=art/SettingsWindow.gif align=right border=2>
	The <b><u>Window</b></u>&nbsp;<b>&gt;</b>&nbsp;<b><u>Settings...</b></u>
	command brings up the Settings Window, shown here,
	where you can set various
	preferences.&nbsp;
	Take particular note of the <b><u>Malloc Debug Level</b></u> slider.&nbsp;
	As you increase the level of malloc debugging, the sensitivity to corrupt
	memory is heightened.&nbsp;If the memory checker finds something
	wrong, <b>bdb</b> pops up an alert to tell you about it.

	<P>
	


<!-- Footer for Release Notes; BeOS 4.5 -->
<HR>
<BR>

<CENTER>
	<table cellpadding=4>
	<TR>
	<TD><a href=../index.html>&nbsp;index&nbsp;</a>
	<TD><a href=../RN4.1_Headlines.html>&nbsp;headlines&nbsp;</a>
	<TD><a href=../RN4.1_AppKit.html>&nbsp;&lt;&lt;previous&nbsp;</a>
	<TD><a href=../BeIDE/RN4.1_BeIDE.html>&nbsp;next&gt;&gt;&nbsp;</a>
	</TABLE>
</CENTER>

<p>

<CENTER>
	<TABLE>
	<TR>
	<TD>
	<i><FONT size="+6" COLOR='#234567'>BeOS Release 4.5</i></FONT>
	</TABLE>
</CENTER>

<P>
<BR>
	<FONT size=-1 >
	Copyright <FONT color=888888>&copy;</FONT>
	1999 <FONT color=blue>B</font><FONT color=red>e</font>, Inc.&nbsp
	All rights reserved.
	</FONT>

</body>
</html>

