<!-- ============= Debugging ====================== -->
 <chapter id="debugging">
  <title>Debugging</title>
  <para>
   <emphasis>To debug is human. To fix it is divine...</emphasis>
  </para>
  <para>
   Well, the <emphasis>human</emphasis> part is what this section is about. The 
   <emphasis>divine</emphasis> part is up to you!
  </para>
  <para>
   When a program does not behave in the way it is supposed to, we say the program
   contains a <emphasis>bug</emphasis>. A bug is not a compilation error &mdash; 
   compilation errors are relatively easy to clear, because the compiler tells you 
   where the problems are. By contrast, bugs are errors 
   that happen during program execution and they can be hard (sometimes very hard!) 
   to detect.
  </para>
  <para>
   Any program that you think is bug-free is never completely bug-free. All we can try 
   to do is to reduce the number of bugs contained in the program. The process of removing 
   bugs is known as <emphasis>debugging</emphasis>, and the tool that is used for debugging 
   is called the <emphasis>debugger</emphasis>. <application>Anjuta</application> provides a 
   very user-friendly and powerful debugging environment (actually, a GUI wrapper over 
   <application>gdb</application>, a powerful command line debugging tool and standard on Linux).
  </para>
  <para>
   A debugger tracks and traces the execution of the program and provides various 
   views of information needed to study the execution of the program.
  </para>

 <!-- Debugger: Start and stop -->

 <sect1 id="debugger-session">
  <title>Start and stop</title>

  <para>
   The debugger is always started with a program loaded. There are two ways to do this:
   <itemizedlist>
    <listitem><para><emphasis>Running an executable</emphasis></para></listitem>
    <listitem><para><emphasis>Attaching to a process</emphasis></para></listitem>
   </itemizedlist>
   <note>
    <para>
     Almost every feature of Anjuta is provided by a plugin. If you do not see
     the menus described here. It is probably because the debugger plugin is not
     loaded. Go in 
     <menuchoice><guisubmenu>Edit</guisubmenu><guimenuitem>Preferences</guimenuitem><guimenuitem>General</guimenuitem><guimenuitem>Installed plugins</guimenuitem></menuchoice>
     and check that the debugger plugin is loaded.
     It is an user activatable plugin, so loaded or unloaded on request.
    </para>
   </note>
  </para>

  <sect2 id="debug-run">
   <title>Running an executable</title>
   <para>
     Running a program with or without the debugger uses the same menu: select
     <menuchoice><guisubmenu>Run</guisubmenu><guimenuitem>Run Program</guimenuitem></menuchoice> 
     to run a program without the debugger and
     <menuchoice><guisubmenu>Run</guisubmenu><guimenuitem>Debug Program</guimenuitem></menuchoice>
     to run it with the debugger.
   </para>
   <note>
    <para>
     In order to better use the debugger, it is strongly recommended that you build your program
     with debugging information (-g for gcc) and no optimization (-O0 for gcc). This can be
     done by selecting the Debug configuration before building the program for the first time.
    </para>
   </note>
   <para>
    You can select which program to run and its environment using
    <menuchoice><guisubmenu>Run</guisubmenu><guimenuitem>Program Parameters&hellip;</guimenuitem></menuchoice>. 
    You can choose:
    <itemizedlist>
     <listitem><para>The program that you want to debug</para>
      <para>
       The drop-down menu of the target drop-down combination box 
       is pre-filled with all executables of the current project. But you can alternatively
       select another executable which is not part of the project. The debugger also accepts libtool
       executables; these are scripts generated by libtool which wrap real executables.
      </para>
     </listitem>
     <listitem><para>The command-line parameters</para></listitem>
     <listitem><para>The working directory</para></listitem>
     <listitem><para>Environment variables</para>
      <para>
       Environment variables displayed in light gray are the current environment variables. You can
       add, modify or remove environment variables here.
      </para>
      <tip><para>
       To debug Anjuta using Anjuta, you can use a different theme to change the look of the instance
       being debugged; for example, you could add "GTK2_RC_FILES=/usr/share/themes/Crux/gtk-2.0/gtkrc".
      </para></tip>
     </listitem>
     <listitem><para>Whether the program should run in a terminal or not.  If so, the Anjuta terminal plugin is used.</para></listitem>
    </itemizedlist>
   </para>
  </sect2>
	
  <sect2 id="debug-attach">
  <title>Attaching to a Process</title>
   <para>
    It is also possible to attach to a running process and debug it by choosing the menu item
    <menuchoice><guisubmenu>Run</guisubmenu>
	<guimenuitem>Debug Process &hellip;</guimenuitem></menuchoice>. A list of all
    processes running on the system will appear. 
   </para>
   <figure id="attach">
    <title>Attach to Process dialog</title>
    <screenshot>
	<screeninfo>Attach to Process dialog</screeninfo>
     <graphic fileref="figures/attach.png" format="PNG" srccredit="andyp"></graphic>
    </screenshot>
   </figure>
   <para>	
    Select the process to attach to and click <guibutton>OK</guibutton> to start the debugger,
    attach to the selected process and stop it.
   </para>
   <note>
    <para>
     It is currently not possible to load symbol information for an attached
 	process. Symbols should be included in the process. 
    </para>
   </note>
  </sect2>
  
  <sect2 id="debug-stop">
   <title>Stopping the Debugger</title>
    <para>
     Choose the menu item <menuchoice><guisubmenu>Run</guisubmenu>
     <guimenuitem>Stop Debugger</guimenuitem></menuchoice> to stop the debugger.
     This will kill the program which is being debugged. If the debugger has
     been attached to a running process, the debugger will just detach from it without killing
     it. You will get a confirmation box if a program is currently attached or running.
   </para>
  </sect2>

  <sect2 id="debug-add-sources">
   <title>Adding source directories</title>
   <para>
    Choose the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
    <guimenuitem>Add source paths&hellip;</guimenuitem></menuchoice> to display a dialog
    box allowing you to add and remove source directories.
   </para>
   <para>
    Most executables include full file paths, so defining the directories where are the source files
    is normally not useful. But some executables include only file names without paths; in this case,
    the debugger will search for source files in all these directories.
    The order of directories can be important if several files have the same name, so
    you can change it using the <guibutton>Up</guibutton> and <guibutton>Down</guibutton>  buttons.
    The directory list is sent to the debugger when it is started. After changing it,
    you need to restart the debugger to cause it to use the new list.
   </para>
  </sect2>

 </sect1>
 
 <!-- Debugger: Execution -->
 
 <sect1 id="debugger-exec">
  <title>Execution</title>
  <para>
   Execution of a program in the debugger can be finely controlled. The program can be 
   executed in single steps, or allowed to continue until it encounters a breakpoint. 
   Executing like this is essential for tracking program behavior. Like a video editing 
   session, the program can be executed in <emphasis>slow motion</emphasis>
   with the ability to go forward, pause, stop, and so on. You cannot go backward yet though.
  </para>
  <para>
   The methods those can be used to execute a program in the debugger are described in 
   the following sections. These commands are available only when the program has already
   been started.
  </para>
  
  <sect2 id="dbg-step-in">
   <title>Single stepping (step in)</title>
   <para>
    Choose the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
    <guimenuitem>Step In</guimenuitem></menuchoice>
    or click on the <guibutton>Step In</guibutton> icon in the 
	<interface>Debug toolbar</interface> to step into a program.
   </para>
   <para>
    Single stepping executes only one statement of the program (from the place where it 
	has stopped) and then returns control. If the statement that is executed contains one 
	or more functions, the debugger tries to step inside the functions (in the sequence in 
	which the functions are executed). Once the statement is executed and
    control is passed back, you can study your program's state.
   </para>
   <para>
    If the <interface>Disassembly window</interface> has the focus when this command is selected,
    it executes only one assembler instruction.
   </para>
  </sect2>

  <sect2 id="dbg-step-over">
   <title>Single stepping (step over)</title>
   <para>
    Choose the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
    <guimenuitem>Step Over</guimenuitem></menuchoice>
    or click on the <guibutton>Step Over</guibutton> icon in the 
	<interface>Debug toolbar</interface> to step over statements in a program.
   </para>
   <para>
    <emphasis>Step over</emphasis> is similar to <emphasis>step in</emphasis>,
    except that it does not step inside any function in the statement being executed.
    The statement will be executed in one go.
   </para>
   <para>
    If the <interface>Disassembly window</interface> has the focus when this command is selected,
    it executes one assembler instruction but does not stop inside if this instruction is a call
    to a subroutine. 
   </para>
   <note>
    <para>
     If a dynamic library is loaded during the step, the program will not
     stop at the end of the step. But it will run until it finds a breakpoint or you
     stop it.
    </para>
   </note>
  </sect2>
  
  <sect2 id="dbg-step-out">
   <title>Single stepping (step out)</title>
   <para>
    Choose the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
    <guimenuitem>Step Out</guimenuitem></menuchoice>
    or click on the <guibutton>Step Out</guibutton> icon in the 
	<interface>Debug toolbar</interface> to step out in a program.
   </para>
   <para>
    <emphasis>Step out</emphasis> will execute the current function until it 
	returns. The program will be stopped once it exits from the function. 
	Step out is not really single stepping, because it does not only execute 
	a single statement &mdash; it executes the whole function until that 
	function returns to the calling function.
   </para>
  </sect2>
  
  <sect2 id="dbg-run">
   <title>Run/Continue</title>
   <para>
    Choose the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
    <guimenuitem>Run/Continue</guimenuitem></menuchoice>
    or click on the <guibutton>Run/Continue</guibutton> icon in the 
	<interface>Debug toolbar</interface> to continue the execution of a program.
    </para>
   <para>
    This option continues the execution of the program until a breakpoint is 
	encountered, or the program exits.
   </para>
  </sect2>

  <sect2 id="dbg-runto">
   <title>Run To</title>
   <para>
    Choose the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
    <guimenuitem>Run to Cursor</guimenuitem></menuchoice>
    or click on the <guibutton>Run to Cursor</guibutton> icon in the 
	<interface>Debug toolbar</interface> to run until the line at the cursor is reached.
   </para>
   <para>
    This option continues the execution of the program until the line or the
    address (if the <interface>Disassembly window</interface> has the focus) at
    the cursor is reached. 
   </para>
  </sect2>
  
  <sect2 id="dbg-stop">
   <title>Stop Program</title>
   <para>
    While the program is running and has control, no debugging tasks can be 
	performed. To obtain control while the program is running, choose the menu item
	<menuchoice><guisubmenu>Debug</guisubmenu>
	<guimenuitem>Pause Program</guimenuitem></menuchoice> or click on the
    <guibutton>Pause Program</guibutton> icon in the <interface>Debug toolbar</interface>.
    This will interrupt the program and return control to the debugger.
   </para>
  </sect2>
  
 </sect1>
 
<!-- ============= Debugging: Breakpoints ====================== -->
 
 <sect1 id="debugging-breaks">
  <title>Breakpoints</title>
  <para>
   When debugging a program, it is useful to be able to stop the execution of the program at
   a particular point, so that the state of the program can be examined at that location. 
   Breakpoints enable this to happen. Breakpoints can be set at different locations in a 
   source file and then the program is allowed to run. When a breakpoint is encountered, 
   the execution of the program is suspended, enabling expressions to be evaluated, 
   variables to be inspected, the stack trace to be studied, and so on.
  </para>

  <sect2 id="breaks-list">
   <title>Listing Breakpoints</title>
   <para>
    The <interface>Breakpoint list window</interface> can be opened by 
	choosing <menuchoice><guisubmenu>View</guisubmenu>
    <guimenuitem>Breakpoints</guimenuitem></menuchoice>
   </para>
   <para>
    <figure>
      <title>Breakpoint view</title>
      <screenshot>
       <screeninfo>Breakpoint view</screeninfo>
       <graphic fileref="figures/brk_dlg.png" format="PNG" srccredit="andyp"></graphic>
      </screenshot>
    </figure>
   </para>
   <para>
    The view has the following columns:
    <variablelist>
     <varlistentry>
      <term>Location</term>
      <listitem>
       <para>
        This is the position of the breakpoint in the source file. When the breakpoint
        is set by the debugger, you can get additional information such as the function
        containing the breakpoint.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>Address</term>
      <listitem>
       <para>
        This field is filled with the 
        address of the breakpoint when it is set by the debugger.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>Type</term>
      <listitem>
       <para>
        This always displays "breakpoint". It will be used
        in a future release supporting different kinds of breakpoints.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>Condition</term>
      <listitem>
       <para>
        This is the breakpoint condition. It is empty if no condition is defined.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>Pass count</term>
      <listitem>
       <para>
        When the debugger is not running, this column displays the pass count of the breakpoint,
        or zero if it is not defined.
       </para>
       <para>
        When the debugger is running, if the pass count is zero, this column displays
        the number of times this breakpoint has been triggered. If the pass count is not
        zero, both numbers are displayed. The pass count is the second number.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>State</term>
      <listitem>
       <para>
        This is the state of the breakpoint. It may be
        <itemizedlist>
         <listitem><para>Pending: the breakpoint is not set in your program.</para></listitem>
         <listitem><para>Permanent: the breakpoint is set (its id number in given inside parentheses).</para></listitem>
         <listitem><para>Temporary: the breakpoint is set but will be deleted if reached.</para></listitem>
        </itemizedlist>
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
   <note>
    <para>
     All breakpoints are kept across Anjuta sessions even if they correspond to
     a non-existing location. In this case their states are set as pending. The interface
     tries to set them each time the program is started or a new dynamic library is loaded. 
    </para>
   </note>
  </sect2>  

  <sect2 id="breaks-set">
   <title>Adding or Setting Breakpoints</title>
   <para>
    Choose the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
    <guimenuitem>Add Breakpoint&hellip;</guimenuitem></menuchoice>
    or <menuchoice><guimenuitem>Add Breakpoint&hellip;</guimenuitem></menuchoice>
	in the breakpoint list popup menu to open the <interface>add breakpoint</interface> dialog.
   </para>
   <para>
    <figure>
      <title>Breakpoint add dialog</title>
      <screenshot>
	   <screeninfo>Breakpoint add dialog</screeninfo>
       <graphic fileref="figures/brk_add.png" format="PNG" srccredit="mkv"></graphic>
      </screenshot>
    </figure>
   </para>
   <para>
    Enter the location and, optionally, the
    break condition and the pass count; then click <guibutton>OK</guibutton> to set the 
    breakpoint.
    <variablelist>
     <varlistentry>
      <term>Location</term>
      <listitem>
       <para>
        Enter the location at which to set the breakpoint. It can be specified in any of
        the following formats:
       </para>
       <para>
        <orderedlist>
         <listitem><para>File_name:Line_number</para></listitem>
         <listitem><para>Function_name</para></listitem>
         <listitem><para>File:Function_name</para></listitem>
        </orderedlist>
       </para>
       <para>
        The first format is obvious &mdash; the location refers to the line number 
        <emphasis>Line_number</emphasis> in the source file <emphasis>File</emphasis>. 
        The second format refers to the first line of the function 
        <emphasis>Function_name</emphasis>. The third is similar to the second, except that 
        this notation is used where there is more than one function with the name 
        <emphasis>Function_name</emphasis> in the program. It is possible to 
        differentiate between them by providing the <emphasis>File</emphasis>, so the 
        notation refers to the function <emphasis>Function_name</emphasis> in the 
        file <emphasis>File</emphasis>.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>Condition</term>
      <listitem>
       <para>
        The <emphasis>Condition</emphasis> parameter displays a associated expression
        which should evaluate to a Boolean value &mdash; that is, the 
        evaluation of the expression should result in either TRUE(1) or FALSE(0). 
        If the final evaluation value is not a Boolean value, then it will be 
        appropriately type cast to a Boolean.
       </para>
       <para>
        Every time the breakpoint is encountered during your program's execution, the break 
        condition will be evaluated. The debugger will break the execution only if 
        the evaluation results in a TRUE value, otherwise it will continue the 
        execution as though there had been no breakpoint.
       </para>
       <para>
        The default value, if you leave this field blank, of <emphasis>Condition</emphasis>
        is TRUE. The debugger will always break the execution at the breakpoint location.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>Pass Count</term>
      <listitem>
       <para>
        The <emphasis>Pass count</emphasis> is an integer (unsigned) value which 
        tells the debugger to skip the breakpoint that number of times before it 
        is considered. <emphasis>Pass count</emphasis> has a higher priority than 
        the <emphasis>Break condition</emphasis>. Only when the 
        <emphasis>Pass count</emphasis> reaches zero will the debugger evaluate the 
        <emphasis>Break condition</emphasis> (if any condition is present). If there 
        is no condition, the debugger will break the execution once the 
        <emphasis>Pass count</emphasis> counts down to zero.
       </para>
       <para>
        The default value, if you leave this field blank, of the <emphasis>Pass count</emphasis>
        is zero. The breakpoint will be considered when it is first encountered.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
   <para>
    A breakpoint may also be set by selecting a line in the editor
    and choosing the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
	<guimenuitem>Toggle Breakpoint</guimenuitem></menuchoice> in the editor context
	menu
        or the <guibutton>Toggle Breakpoint</guibutton> icon in the 
	<interface>Debug toolbar</interface>.
   </para>
   <tip>
    <para>
     Breakpoints can be added even if the debugger is not started, or in a dynamic
     library which is not loaded yet. But they cannot be added while a program is running
     under control of the debugger.
    </para>
   </tip>
  </sect2>
  
  <sect2 id="breaks-edit">
   <title>Editing Breakpoints</title>
   <para>
    You can change the condition and the pass count by
    selecting the breakpoint in the breakpoint list and clicking <menuchoice><guimenuitem>Edit Breakpoint</guimenuitem></menuchoice>
    in the popup menu.
   </para>
   <para>
    Edit the entries as required and click on <guibutton>OK</guibutton> to
    commit the changes.
   </para>
  </sect2>

  <sect2 id="breaks-del">
   <title>Deleting Breakpoints</title>
   <para>
    Select the breakpoint in the breakpoint list view and click on
    <menuchoice><guimenuitem>Remove Breakpoint</guimenuitem></menuchoice> to delete it.
   </para>
   <para>
    A existing breakpoint may also be deleted by selecting its line in the editor
    and choosing the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
	<guimenuitem>Toggle Breakpoint</guimenuitem></menuchoice>,
    the editor context menu item
	<menuchoice><guimenuitem>Toggle Breakpoint</guimenuitem></menuchoice>
    or the <guibutton>Toggle Breakpoint</guibutton> icon in the 
	<interface>Debug toolbar</interface>.
   </para>
   <para>
    You can remove all breakpoints by clicking on <menuchoice><guisubmenu>Debug</guisubmenu>
	<guimenuitem>Remove All Breakpoints</guimenuitem></menuchoice> or on
    <menuchoice><guimenuitem>Remove All Breakpoints</guimenuitem></menuchoice> in
    the breakpoint list context menu.
   </para>
  </sect2>

  <sect2 id="breaks-enbdis">
   <title>Enabling or Disabling Breakpoints</title>
   <para>
    Click on the Enable column of the <interface>Breakpoint list window</interface> or
    in the context menu item <menuchoice><guimenuitem>Enable Breakpoint</guimenuitem></menuchoice>
    to enable or disable the selected breakpoint. 
	The breakpoint will be enabled or disabled, depending on its current state.
   </para>
   <para>
    To disable all breakpoints, click on <menuchoice><guisubmenu>Debug</guisubmenu>
	<guimenuitem>Disable All Breakpoints</guimenuitem></menuchoice> or on
    <menuchoice><guimenuitem>Disable All Breakpoints</guimenuitem></menuchoice> in
    the breakpoint list context menu.
   </para>
  </sect2>
 </sect1>

<!-- ============= Debugging: Expressions ====================== -->
 <sect1 id="debugging-expr">
  <title>Expressions</title>

  <sect2 id="var-local">
   <title>Listing local variables</title>
   <para>
    When a program is running under the control of the debugger, the 
    <interface>Locals list window</interface> can be opened by 
    choosing <menuchoice><guisubmenu>View</guisubmenu>
    <guimenuitem>Locals</guimenuitem></menuchoice>.
   </para>
   <para>
    Local variables of the current frame (the current function in which the program control
    is present) are displayed in the <interface>Locals window</interface>.
    During execution of the program (e.g. during single stepping), local
    variables will be updated. If any variable value was changed in the last debugging step, its
    value will be highlighted in red. Variables are presented in a tree form for easy
    view.
    <figure>
      <title>Local variables</title>
      <screenshot>
	  <screeninfo>Local variables</screeninfo>
       <graphic fileref="figures/local_variables.png" format="PNG" srccredit="naba"></graphic>
      </screenshot>
    </figure>
   </para>
   <para>
    The value of a local variable can be modified by selecting it and clicking in
    the <guilabel>Value</guilabel> column.
   </para>
   <note>
    <para>
     <application>gdb</application> is more and more often used as a back end for a graphical front end. It
     has been improved recently in this area. It is recommended that you use the latest
     version (6.6) of gdb. With older versions, gdb can crash when the front end
     asks for an pointer with an invalid (but unused) value.
    </para>
   </note>
  </sect2>

  <sect2 id="var-watch">
   <title>Listing watched expressions</title>
   <para>
    Inspecting or evaluating an expression provides the result only once. To continuously 
	monitor some variables or expressions, use <emphasis>expression watches</emphasis>.
   </para>
   <para>
	   Choose the menu item <menuchoice><guisubmenu>View</guisubmenu><guimenuitem>Watches</guimenuitem>
	   </menuchoice> to display the <interface>Watches window</interface>.
   </para>
  </sect2>

  <sect2 id="watch-add">
   <title>Adding an expression to watch</title>
   <para>
    Right-click on the <interface>Watches window</interface>
    to open the context menu. Choose the 
	menu item <guimenuitem>Add Watch&hellip;</guimenuitem>. Alternatively, you can
    use <menuchoice><guisubmenu>Debug</guisubmenu>
	<guimenuitem>Add Watch&hellip;</guimenuitem></menuchoice>
    A dialog prompting for the expression will appear. Enter the expression and 
    click <guibutton>OK</guibutton>.
   </para>
   <para>
    By default watch expressions are updated automatically 
    each time the program is stopped. This can be changed in the add watch dialog
    or later using the <guimenuitem>Automatic update</guimenuitem> menu item in the
    <interface>Watches window</interface> context menu. A watched expression
    can be updated manually by choosing
    <guimenuitem>Update Watch</guimenuitem> or <guimenuitem>Update All</guimenuitem> in
    the context menu.
   </para>
   <para>
    It is not necessary to have the debugger running to add a new watch expression.
    If the debugger is not running or the corresponding expression cannot be found, 
    the front end will try to create the watch expression each time the program
    is stopped.
   </para>
  </sect2>

  <sect2 id="watch-remove">
   <title>Removing a watched expression</title>
   <para>
    Right-click the watch expression that you want to remove in the <interface>Watches 
	window</interface>, then choose the context
	menu item <guimenuitem>Remove</guimenuitem> to remove it.
   </para>
   <para>
    All watches can be removed by choosing <guimenuitem>Remove All</guimenuitem> in the
    context menu of the <interface>Watches window</interface>.
   </para>
  </sect2>

  <sect2 id="expr-eval">
   <title>Evaluating expressions</title>
   <para>
    When control is returned from a program &mdash; possibly at a breakpoint &mdash; 
	it is possible to evaluate expressions or inspect the values of variables in the 
	program. Choose the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
    <guimenuitem>Inspect/Evaluate &hellip;</guimenuitem></menuchoice>, 
    <menuchoice><guimenuitem>Inspect/Evaluate &hellip;</guimenuitem></menuchoice>
    in the context menu of the editor or click 
	the <guibutton>Inspect</guibutton> button on the <interface>Debug Toolbar</interface>. 
   </para>
   <para>
	   A window will appear showing the evaluation of the expression
	   highlighted in the editor.
	   You can evaluate a new expression by clicking on the <guilabel>name</guilabel> column
	   and entering the new one.
   </para>
   <para>
    You can add the expression to the list of watched expressions directly by 
    clicking on the <guibutton>Add</guibutton> button. 
   </para>
  </sect2>

  <sect2 id="expr-hiver">
   <title>Inspecting expressions in editor window</title>
   <para>
    When the debugger is active with the program stopped, you can get the value of an
    expression just by putting the mouse pointer over it and staying there for a short time.
    If the expression is already present in the <interface>Locals</interface> or <interface>Watches</interface> window, its value is
    displayed in a tooltip.
   </para>
   <para>
    This capability is currently working only for simple variables, not for structures or arrays.
   </para>
  </sect2>

 </sect1>

<!-- ============= Debugging: Program Stack ====================== -->
 <sect1 id="debugging-stack">
  <title>Stack Trace</title>

  <sect2 id="stack-win">
   <title>Stack Window</title>
   <para>
    The <interface>stack trace window</interface> shows the contents of the 
	program stack. It lists all functions and their arguments in the 
	sequence they were called. There is also a number representing each call. 
	This number is called the <emphasis>frame</emphasis>. Each call in the trace 
	exists in a different frame. This starts from frame 0 (the last function
    called) and grows higher as function nesting becomes deeper.
   </para>
   <para>
	   Choose the menu item <menuchoice><guisubmenu>View
	   </guisubmenu><guimenuitem>Stack</guimenuitem></menuchoice> to open the stack trace for the program 
	being debugged.
   </para>
   <para>
    <figure>
      <title>Stack trace window</title>
      <screenshot>
	   <screeninfo>Stack trace window</screeninfo>
       <graphic fileref="figures/stack.png" format="PNG" srccredit="andyp"></graphic>
      </screenshot>
    </figure>
   </para>
   <para>
    A small arrow points to the currently selected frame in the stack trace. By 
	default, this will be frame 0, the last function called. All evaluation 
	and inspection of expressions or variables will be with reference to this selected 
	frame. The scope of variables or expressions being evaluated will be limited 
	to the selected frame only. The same applies for new expressions only in the watch.
   </para>
  </sect2>
  
  <sect2 id="stack-frame">
   <title>Setting the current frame</title>
   <para>
    Double-clicking on any frame in the stack trace sets that frame as the 
	currently selected frame.  The arrow will point to the frame, indicating that it 
	has been selected as the current frame. Alternatively, open the 
	context menu by right-clicking on the 
	<interface>Stack trace window</interface>, and choose the menu item 
	<guimenuitem>Set current frame</guimenuitem> to set the frame.
   </para>
   <para>
    Changing the stack frame changes the <interface>Locals window</interface>
    content, but not the <interface>Watches window</interface> as each
    expression is evaluated in the frame used when it was defined.
   </para>
  </sect2>
 </sect1>

<!-- ============= Debugging: Program Thread ====================== -->
 <sect1 id="debugging-thread">
  <title>Thread</title>

  <sect2 id="thread-win">
   <title>Thread Window</title>
   <para>
    The <interface>Thread window</interface> shows all threads used by the program
    and indicates the current thread. Choose the menu item <menuchoice><guisubmenu>View</guisubmenu>
    <guimenuitem>Thread</guimenuitem></menuchoice> to open this window.
   </para>
   <para>
    A small arrow points to the current thread. When the
    program is stopped, the current thread is the thread which has been interrupted.
    Each thread has its own stack frame, so changing the current thread changes
    the current stack frame. 
   </para>
  </sect2>

  <sect2 id="set-thread">
   <title>Setting the current thread</title>
   <para>
    Double-clicking on any thread in the thread list will set that thread as the 
	currently selected thread. The arrow will point to the thread, indicating that it 
	has been selected as the current thread. Alternatively, open the 
	context menu by right-clicking on the 
	<interface>Thread list window</interface>, and choose the menu item 
	<guimenuitem>Set current thread</guimenuitem> to set the thread.
   </para>
   <para>
    Changing the thread changes the value of CPU registers and the current
    stack frame, so the <interface>Locals window</interface> changes too.
   </para>
  </sect2>
 </sect1>

<!-- ============= Debugging: CPU ====================== -->
 <sect1 id="debugging-cpu">
  <title>CPU</title>

  <sect2 id="cpu-regs">
   <title>Register window</title>
   <para>
    It is possible to examine the contents of the internal registers of the 
	CPU (microprocessor). Choose the menu item <menuchoice><guisubmenu>View</guisubmenu>
	<guimenuitem>Registers</guimenuitem></menuchoice>. A window listing all 
	available registers in the microprocessor and their corresponding contents 
	will appear.
   </para>
   <para>
    If any register value was changed in the last debugging step, its
    value will be highlighted in red. It is possible to change one register value
    by selecting it and clicking in the <guilabel>value</guilabel> column.    
   </para>
  </sect2>

  <sect2 id="cpu-memory">
   <title>Memory window</title>
   <para>
    Choose the menu item <menuchoice><guisubmenu>View</guisubmenu><guimenuitem>Memory 
	</guimenuitem></menuchoice> to open the <interface>memory window</interface>
    for the program being debugged. This window shows the contents of all memory. 
   </para>
   <para>
    The first column displays memory addresses in hexadecimal, the second displays memory contents
    in hexadecimal and the last column shows memory contents in ASCII.
   </para>
   <para>
    The addressing space of even a 32-bit microprocessor is quite large (4 gigabytes),
    so it is very difficult to go to a particular address with the scrollbar. But
    you can click on the right mouse button to display a context menu and select
    <menuchoice><guimenuitem>Goto address</guimenuitem></menuchoice> to get
    a small edit box where you can enter an address in hexadecimal.
   </para>
  </sect2>

  <sect2 id="cpu-disassembly">
   <title>Disassembly window</title>
   <para>
    Choose the menu item <menuchoice><guisubmenu>View</guisubmenu><guimenuitem>Disassembly
	</guimenuitem></menuchoice> to open the <interface>disassembly window</interface>
    for the program being debugged.
   </para>
   <para>
    The first column displays addresses in hexadecimal. In the second column, you can
    have a label starting at the beginning of the line and ending with a colon or
    a assembly-language instruction indented by 4 space characters.
   </para>
   <para>
    Again, as the addressing space is very large, the scrollbar is quite useless.
    You can click on the right mouse button to display the context menu and select
    <menuchoice><guimenuitem>Goto address</guimenuitem></menuchoice> to get
    a small edit box where you can enter an address in hexadecimal. The position
    in the disassembly window will be changed to the program counter value when
    the program is stopped.
   </para>
  </sect2>
 </sect1>

<!-- Debugger: Others-->
 <sect1 id="debugger-others">
  <title>Others</title>

  <para>
   There are a number of other debugger features used less frequently and not
   very well integrated in the new front end but which are still working.
  </para>

  <sect2 id="dbg-dyna-libs">
   <title>Dynamically loaded Libraries</title>
   <para>
    To obtain a list of the dynamic libraries used by a program, choose the 
	menu item <menuchoice><guisubmenu>Debug</guisubmenu><guisubmenu>Info</guisubmenu>
	<guimenuitem>Shared Libraries</guimenuitem></menuchoice>. This will bring 
	open a window which will list all shared libraries the program has loaded 
	and their locations in memory. It also shows whether each library's symbol table is 
	loaded or not (Yes/No).
   </para>
   <para>
    <figure>
      <title>Shared Libraries window</title>
      <screenshot>
	   <screeninfo>Shared Libraries window</screeninfo>
       <graphic fileref="figures/sharedlibs.png" format="PNG" srccredit="andyp"></graphic>
      </screenshot>
    </figure>
   </para>
  </sect2>

  <sect2 id="dbg-signal">
   <title>Kernel Signals</title>
   <para>
    Kernel signals are a way of signaling between processes in Linux. The list 
	of signals available for a program can be displayed by choosing the menu item
    <menuchoice><guisubmenu>Debug</guisubmenu><guisubmenu>Info</guisubmenu><guimenuitem>Kernel Signals</guimenuitem></menuchoice>.
    A window will open which lists all signals available in the system along with
    a brief description of each signal.
   </para>
   <para>
    <figure>
      <title>Kernel Signals window</title>
      <screenshot>
	   <screeninfo>Kernel Signals window</screeninfo>
       <graphic fileref="figures/signals.png" format="PNG" srccredit="andyp"></graphic>
      </screenshot>
    </figure>
   </para>
   <para>
    There are three columns which specify what to do when a signal is received:
   </para>
   
   <orderedlist>
    <listitem>
     <para><emphasis>Stop</emphasis> &mdash; this tells the debugger whether to 
	 stop the program execution (and return control) when the program receives 
	 this signal.
     </para>
    </listitem>
    <listitem>
     <para><emphasis>Print</emphasis> &mdash; this tells the debugger whether to 
	 display the received signal.
     </para>
    </listitem>
    <listitem>
     <para><emphasis>Pass</emphasis> &mdash; this tells the debugger whether to pass 
	 the signal to the program.
     </para>
    </listitem>
   </orderedlist>
   <note>
    <para>
     The context menu that is displayed when you click on the right mouse button has
     all its items disabled because the corresponding functions are not implemented
     yet.
    </para>
   </note>
  </sect2>

  <sect2 id="dbg-files">
   <title>Information about used files</title>
   <para>
    You can get some information about the files used by the debugged program
	by choosing the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
	<guisubmenu>Information</guisubmenu><guimenuitem>Target files</guimenuitem></menuchoice>. 
	A window will open displaying this information.
   </para>
  </sect2>

  <sect2 id="dbg-program">
   <title>Information about debugged program</title>
   <para>
    You can get some information about the debugged program
	by choosing the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
	<guisubmenu>Information</guisubmenu><guimenuitem>Program</guimenuitem></menuchoice>. 
	A window will open displaying this information.
   </para>
  </sect2>
 
  <sect2 id="dbg-kernel">
   <title>Information about kernel structure</title>
   <para>
    You can get some information about kernel data for the current process
	by choosing the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
	<guisubmenu>Information</guisubmenu><guimenuitem>Kernel user struct</guimenuitem></menuchoice>. 
	A window will open displaying this information.
   </para>
  </sect2>

  <sect2 id="var-global">
   <title>Information about global variables</title>
   <para>
    You can list all global variables
	by choosing the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
	<guisubmenu>Information</guisubmenu><guimenuitem>Info Global Variable</guimenuitem></menuchoice>. 
	A window will open listing all global variables.
   </para>
  </sect2>

  <sect2 id="stack-frame-info">
   <title>Information about the current frame</title>
   <para>
    You can obtain information about the currently selected frame 
	by choosing the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
	<guisubmenu>Information</guisubmenu><guimenuitem>Info Current Frame</guimenuitem></menuchoice>. 
	A window will open describing the current frame.
   </para>
  </sect2>

  <sect2 id="stack-arg-info">
   <title>Information about the current function arguments</title>
   <para>
    You can obtain information about the arguments of the current function 
	by choosing the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
	<guisubmenu>Information</guisubmenu><guimenuitem>Arguments</guimenuitem></menuchoice>. 
	A window will open describing the arguments.
   </para>
  </sect2>
  
  <sect2 id="dbg-command">
   <title>User command</title>
   <para>
    To send directly a command to the back end choose the
	menu item <menuchoice><guimenu>Debug</guimenu>
	<guimenuitem>Debugger command</guimenuitem></menuchoice>. This will bring
    a small dialog where you can enter commands that will be send to the debugger
    when you press <keycap>Return</keycap>.
   </para>
   <note>
    <para>
     The front end sends this command directly to the back end without performing any checks.
     By example if you set a breakpoint like this, it will not appear in the
     <interface>breakpoint list window</interface>. It is better to avoid using this
     command unless you know exactly what you are doing.
    </para>
   </note>
  </sect2>
 </sect1> 

 </chapter>
