manuals/anjuta-manual/C/debugger.xml

   1 <!-- ============= Debugging ====================== -->
   2  <chapter id="debugging">
   3   <title>Debugging</title>
   4   <para>
   5    <emphasis>To debug is human. To fix it is divine...</emphasis>
   6   </para>
   7   <para>
   8    Well, the <emphasis>human</emphasis> part is what this section is about. The
   9    <emphasis>divine</emphasis> part is up to you!
  10   </para>
  11   <para>
  12    When a program does not behave in the way it is supposed to, we say the program
  13    contains a bug or bugs. This does not refer to compilation errors &mdash; those are
  14    simply errors and they are relatively easy to clear, because the compiler tells you
  15    where the problems are. On the other hand, <emphasis>bugs</emphasis> are errors
  16    that happen during the execution of the program and they can be hard (sometimes very hard!)
  17    to detect.
  18   </para>
  19   <para>
  20    Any program that you think is bug-free is never completely bug-free. All we can try
  21    to do is to reduce the number of bugs contained in the program. The process of removing
  22    bugs is known as <emphasis>debugging</emphasis>, and the tool that is used for debugging
  23    is called the <emphasis>debugger</emphasis>. <application>Anjuta</application> provides a
  24    very user-friendly and powerful debugging environment (actually, a GUI wrapper over
  25    <application>gdb</application>, a powerful command line debugging tool and standard on Linux).
  26   </para>
  27   <para>
  28    A debugger tracks and traces the execution of the program and provides various
  29    views of information needed to study the execution of the program.
  30   </para>
  31
  32   <note>
  33    <para>
  34     The debugger has been heavily changed since anjuta 2.0.2. Some features have
  35     been dropped but will be reenabled, a few have been added.
  36    </para>
  37   </note>
  38
  39  <!-- Debugger: Start and stop -->
  40
  41  <sect1 id="debugger-session">
  42   <title>Start and stop</title>
  43
  44   <para>
  45    There are two ways to start the debugger:
  46    <itemizedlist>
  47     <listitem><para><emphasis>Running an executable</emphasis></para></listitem>
  48     <listitem><para><emphasis>Attaching to a process</emphasis></para></listitem>
  49    </itemizedlist>
  50   </para>
  51
  52   <sect2 id="debug-run">
  53    <title>Running an executable</title>
  54    <para>
  55     Choose the menu item
  56     <menuchoice><guisubmenu>Debug</guisubmenu><guimenuitem>Run Target&hellip;</guimenuitem></menuchoice>
  57     to display a dialog box where you can select
  58     the executable that you want to debug, the command line parameters
  59     and if you want a terminal or not. The popup menu of the target combo box
  60     is already filled with all executables of the current project, so you can easily
  61     select one of them. But it is not mandatory, you can select any other executable.
  62     The debugger accepts libtool executable, I mean script wrapping the real
  63     executable generated by libtool. When you have set everything you can click on
  64     <guibutton>Execute</guibutton>
  65     to start the debugger, load your program and stop at its beginning.
  66    </para>
  67    <tip>
  68     <para>
  69      In order to better user the debugger, it is recommended to debug program
  70      with debugging information (-g for gcc) and no optimization (-O0 for gcc).
  71     </para>
  72    </tip>
  73   </sect2>
  74
  75   <sect2 id="debug-attach">
  76   <title>Attaching to a Process</title>
  77    <para>
  78     It is also possible to attach to a running process for debugging. Choose the menu item
  79     <menuchoice><guisubmenu>Debug</guisubmenu>
  80         <guimenuitem>Attach to Process &hellip;</guimenuitem></menuchoice>. A list of all the
  81     process running on the system will appear.
  82    </para>
  83    <figure id="attach">
  84     <title>Attach to Process dialog</title>
  85     <screenshot>
  86         <screeninfo>Attach to Process dialog</screeninfo>
  87      <graphic fileref="figures/attach.png" format="PNG" srccredit="andyp"></graphic>
  88     </screenshot>
  89    </figure>
  90    <para>
  91     Select the process to attach to and click <guibutton>OK</guibutton>.
  92    </para>
  93    <note>
  94     <para>
  95      It is currently not possible to load symbol information for the attached
  96      process.
  97     </para>
  98    </note>
  99   </sect2>
 100
 101   <sect2 id="debug-restart">
 102    <title>Restarting an executable</title>
 103    <para>
 104     After running a executable at least one time, you can
 105     choose the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
 106     <guimenuitem>Restart Target</guimenuitem></menuchoice> to restart your program.
 107     It is just a shortcut that will stop the debugger if it is currently running
 108     and restart it with the last executable.
 109    </para>
 110   </sect2>
 111
 112   <sect2 id="debug-stop">
 113    <title>Stopping the Debugger</title>
 114    <para>
 115     Choose the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
 116     <guimenuitem>Stop Debugger</guimenuitem></menuchoice> to stop the debugger.
 117     This option will kill the program which is being debugged. If the debugger has
 118     been attached to a running process, it will just detach from it without killing
 119     it. You will get a confirmation box if a program is currently attached or running.
 120    </para>
 121   </sect2>
 122
 123  </sect1>
 124
 125  <!-- Debugger: Execution -->
 126
 127  <sect1 id="debugger-exec">
 128   <title>Execution</title>
 129   <para>
 130    Execution of a program in the debugger can be finely controlled. The program can be
 131    executed in single steps, or allowed to continue until it encounters a breakpoint.
 132    Executing like this is essential for tracking program behaviour. Like a video editing
 133    session, the program can be executed in <emphasis>slow motion</emphasis>
 134    with the ability to go forward, pause, stop, and so on.
 135   </para>
 136   <para>
 137    The methods that can be used to execute a program in the debugger are described in
 138    the next few sections.
 139   </para>
 140
 141   <sect2 id="dbg-step-in">
 142    <title>Single stepping (step in)</title>
 143    <para>
 144     Single stepping executes only one statement of the program (from the place where it
 145         has stopped) and then returns control. If the statement that is executed contains one
 146         or more functions, the debugger tries to step inside the functions (in the sequence in
 147         which the functions are executed). Once the statement is executed and
 148     control is passed back, it is possible to study the various program parameters.
 149    </para>
 150    <para>
 151     If the program need to been started to use single stepping.
 152    </para>
 153    <para>
 154     Choose the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
 155     <guimenuitem>Step In</guimenuitem></menuchoice>
 156     or click on the <guibutton>Step In</guibutton> icon in the
 157         <interface>Debug toolbar</interface> to step into a program.
 158    </para>
 159   </sect2>
 160
 161   <sect2 id="dbg-step-over">
 162    <title>Single stepping (step over)</title>
 163    <para>
 164     <emphasis>Step over</emphasis> is similar to <emphasis>step in</emphasis>,
 165     except that it does not step inside any function in the statement being executed.
 166     The statement will be executed in one go.
 167    </para>
 168    <para>
 169     Choose the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
 170     <guimenuitem>Step Over</guimenuitem></menuchoice>
 171     or click on the <guibutton>Step Over</guibutton> icon in the
 172         <interface>Debug toolbar</interface> to step over statements in a program.
 173    </para>
 174    <note>
 175     <para>
 176      If a dynamic library is loaded during the step, the program will not
 177      stop at the end of the step. But it will run until it finds a breakpoint or you
 178      stop it.
 179     </para>
 180    </note>
 181   </sect2>
 182
 183   <sect2 id="dbg-step-out">
 184    <title>Single stepping (step out)</title>
 185    <para>
 186     <emphasis>Step out</emphasis> will execute the current function until it
 187         returns. The program will be stopped once it exits from the function.
 188         Step out is not really single stepping, because it does not only execute
 189         a single statement &mdash; it executes the whole function until that
 190         function returns to the calling function.
 191    </para>
 192    <para>
 193     Choose the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
 194     <guimenuitem>Step Out</guimenuitem></menuchoice>
 195     or click on the <guibutton>Step Out</guibutton> icon in the
 196         <interface>Debug toolbar</interface> to step out in a program.
 197    </para>
 198   </sect2>
 199
 200   <sect2 id="dbg-run">
 201    <title>Run/Continue</title>
 202    <para>
 203     This option will continue the execution of the program until a breakpoint is
 204         encountered, or the program exits.
 205    </para>
 206    <para>
 207     Choose the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
 208     <guimenuitem>Run/Continue</guimenuitem></menuchoice>
 209     or click on the <guibutton>Run/Continue</guibutton> icon in the
 210         <interface>Debug toolbar</interface> to continue the execution of a program.
 211     </para>
 212   </sect2>
 213
 214   <sect2 id="dbg-runto">
 215    <title>Run To</title>
 216    <para>
 217     This option will continue the execution of the program until the line where
 218     cursor is is reached.
 219    </para>
 220    <para>
 221     Choose the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
 222     <guimenuitem>Run to Cursor</guimenuitem></menuchoice>
 223     or click on the <guibutton>Run to Cursor</guibutton> icon in the
 224         <interface>Debug toolbar</interface> to run until the line at cursor is reached.
 225     </para>
 226   </sect2>
 227
 228   <sect2 id="dbg-stop">
 229    <title>Stop Program</title>
 230    <para>
 231     While the program is running and has control, no debugging tasks can be
 232         performed. To obtain control while the program is running, choose the menu item
 233         <menuchoice><guisubmenu>Debug</guisubmenu>
 234         <guimenuitem>Interrupt Program</guimenuitem></menuchoice> or click on the
 235     <guibutton>Stop Program</guibutton> icon in the <interface>Debug toolbar</interface>.
 236     This will interrupt the program and return control to the debugger.
 237    </para>
 238   </sect2>
 239
 240  </sect1>
 241
 242 <!-- ============= Debugging: Breakpoints ====================== -->
 243
 244  <sect1 id="debugging-breaks">
 245   <title>Breakpoints</title>
 246   <para>
 247    When debugging a program, it is useful to be able to stop the execution of the program at
 248    a particular point, so that the state of the program can be examined at that location.
 249    Breakpoints enable this to happen. Breakpoints can be set at different locations in a
 250    source file, and then the program is allowed to run. When a breakpoint is encountered,
 251    the execution of the program is suspended, enabling expressions to be evaluated,
 252    variables to be inspected, the stack trace to be studied, and so on.
 253   </para>
 254
 255   <sect2 id="breaks-list">
 256    <title>Listing Breakpoints</title>
 257    <para>
 258     The <interface>Breakpoint list window</interface> can be opened by
 259         choosing <menuchoice><guisubmenu>View</guisubmenu>
 260     <guimenuitem>Breakpoints</guimenuitem></menuchoice>
 261    </para>
 262    <para>
 263     <figure>
 264       <title>Breakpoint view</title>
 265       <screenshot>
 266        <screeninfo>Breakpoint view</screeninfo>
 267        <graphic fileref="figures/brk_dlg.png" format="PNG" srccredit="andyp"></graphic>
 268       </screenshot>
 269     </figure>
 270    </para>
 271    <para>
 272     <emphasis>Location</emphasis>, refers to the location of the code in the source
 273     file. <emphasis>Location</emphasis> can be specified in any of the following
 274     formats:
 275    </para>
 276    <para>
 277     <orderedlist>
 278      <listitem><para>File_name:Line_number</para></listitem>
 279      <listitem><para>Function_name</para></listitem>
 280      <listitem><para>File:Function_name</para></listitem>
 281     </orderedlist>
 282    </para>
 283    <para>
 284     The first one is obvious &mdash; The location refers to the line number
 285     <emphasis>Line_number</emphasis> in the source file <emphasis>File</emphasis>.
 286     The second refers to the first line of the function
 287     <emphasis>Function_name</emphasis>. The third is similar to the second, except that
 288     this notation is used where there is more than one function with the name
 289     <emphasis>Function_name</emphasis> in the program. It is possible to
 290     differentiate between them by providing the <emphasis>File</emphasis>, so the
 291     notation refers to the function <emphasis>Function_name</emphasis> in the
 292     file <emphasis>File</emphasis>.
 293    </para>
 294    <para>
 295     Two parameters can be associated with each breakpoint:
 296     <orderedlist>
 297      <listitem><para>Break condition</para></listitem>
 298      <listitem><para>Pass count</para></listitem>
 299     </orderedlist>
 300    </para>
 301    <para>
 302     The <emphasis>Break condition</emphasis> is a valid C
 303     expression which should evaluate to a Boolean value &mdash; that is, the
 304     evaluation of the expression should result in either TRUE(1) or FALSE(0).
 305     If the final evaluation value is not a Boolean value, then it will be
 306     appropriately type casted to a Boolean.
 307    </para>
 308    <para>
 309     Every time the breakpoint is encountered during the execution, the break
 310     condition will be evaluated. The debugger will break the execution only if
 311     the evaluation results in a TRUE value, otherwise it will continue the
 312     execution as though there had been no breakpoint.
 313    </para>
 314    <para>
 315     The default value of <emphasis>Break condition</emphasis> is always TRUE.
 316     The debugger will break the execution at the breakpoint location.
 317    </para>
 318    <para>
 319     The <emphasis>Pass count</emphasis> is an integer (unsigned) value which
 320     tells the debugger to skip the breakpoint that number of times before it
 321     is considered. <emphasis>Pass count</emphasis> has a higher priority than
 322     the <emphasis>Break condition</emphasis>. Only when the
 323     <emphasis>Pass count</emphasis> reaches zero will the debugger evaluate the
 324     <emphasis>Break condition</emphasis> (if any condition is present). If there
 325     is no condition, the debugger will break the execution once the
 326     <emphasis>Pass count</emphasis> counts down to zero.
 327    </para>
 328    <para>
 329     The default value of the <emphasis>Pass count</emphasis> is zero. The
 330     breakpoint will be considered when it is first encountered.
 331    </para>
 332    <note>
 333     <para>
 334      All breakpoints are kept across anjuta session even if they correspond to
 335      a non existing place. The interface try to set them each time the program
 336      is started or a new dynamic library is loaded.
 337     </para>
 338    </note>
 339   </sect2>
 340
 341   <sect2 id="breaks-set">
 342    <title>Adding or Setting Breakpoints</title>
 343    <para>
 344     Choose the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
 345     <guimenuitem>Add Breakpoint&hellip;</guimenuitem></menuchoice>
 346     or <menuchoice><guimenuitem>Add Breakpoint&hellip;</guimenuitem></menuchoice>
 347         in the breakpoint list popup menu to open the add breakpoint dialog.
 348    </para>
 349    <para>
 350     <figure>
 351       <title>Breakpoint add dialog</title>
 352       <screenshot>
 353            <screeninfo>Breakpoint add dialog</screeninfo>
 354        <graphic fileref="figures/brk_add.png" format="PNG" srccredit="mkv"></graphic>
 355       </screenshot>
 356     </figure>
 357    </para>
 358    <para>
 359     Enter the location at which to set the breakpoint. Optionally, enter
 360     the <emphasis>Break condition</emphasis> and the <emphasis>Pass count</emphasis>
 361     in the appropriate entry boxes. Click <guibutton>OK</guibutton> to set the
 362         breakpoint.
 363    </para>
 364    <para>
 365     A breakpoint may also be by selecting a line in the editor
 366     and choosing the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
 367         <guimenuitem>Toggle Breakpoint</guimenuitem></menuchoice>, the editor popup
 368         menu item
 369         <menuchoice><guimenuitem>Toggle Breakpoint</guimenuitem></menuchoice>
 370     or the <guibutton>Toggle Breakpoint</guibutton> icon in the
 371         <interface>Debug toolbar</interface>.
 372    </para>
 373    <tip>
 374     <para>
 375      Breakpoints can be added even if the debugger is not started or in dynamic
 376      library not loaded yet. But they cannot be added while a program is running
 377      under control of the debugger.
 378     </para>
 379    </tip>
 380   </sect2>
 381
 382   <sect2 id="breaks-edit">
 383    <title>Editing Breakpoints</title>
 384    <para>
 385     It is possible to change the condition of a breakpoint of the pass count by
 386     selecting the breakpoint to edit in the breakpoint list and click in the
 387     popup menu item <menuchoice><guimenuitem>Edit Breakpoint</guimenuitem></menuchoice>.
 388    </para>
 389    <para>
 390     Edit the entries as required and click on <guibutton>OK</guibutton> to
 391     commit the changes.
 392    </para>
 393   </sect2>
 394
 395   <sect2 id="breaks-del">
 396    <title>Deleting Breakpoints</title>
 397    <para>
 398     Select the breakpoint to delete in the breakpoint list view and click on
 399     <menuchoice><guimenuitem>Remove Breakpoint</guimenuitem></menuchoice>.
 400    </para>
 401    <para>
 402     A existing breakpoint may also be deleted by selecting the line in the editor
 403     and choosing the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
 404         <guimenuitem>Toggle Breakpoint</guimenuitem></menuchoice>,
 405     the editor popup menu item
 406         <menuchoice><guimenuitem>Toggle Breakpoint</guimenuitem></menuchoice>
 407     or the <guibutton>Toggle Breakpoint</guibutton> icon in the
 408         <interface>Debug toolbar</interface>.
 409    </para>
 410   </sect2>
 411
 412   <sect2 id="breaks-enbdis">
 413    <title>Enabling or Disabling Breakpoints</title>
 414    <para>
 415     Click on the Enable column of the <interface>Breakpoint list window</interface> or
 416     in the menu item <menuchoice><guimenuitem>Enable Breakpoint</guimenuitem></menuchoice>
 417     to enable or disable the selected breakpoint.
 418         The breakpoint will be enabled or disabled, depending on the current state.
 419    </para>
 420    <para>
 421     To disable all breakpoints, click on <menuchoice><guisubmenu>Debug</guisubmenu>
 422         <guimenuitem>Disable All Breakpoints</guimenuitem></menuchoice> or on
 423     <menuchoice><guimenuitem>Disable All Breakpoints</guimenuitem></menuchoice> in
 424     the breakpoint list popup menu.
 425    </para>
 426   </sect2>
 427  </sect1>
 428
 429 <!-- ============= Debugging: Expressions ====================== -->
 430  <sect1 id="debugging-expr">
 431   <title>Expressions</title>
 432
 433   <sect2 id="var-local">
 434    <title>Listing local variable</title>
 435    <para>
 436     When a program is running under the control of the debugger, the
 437     <interface>Locals list window</interface> can be opened by
 438     choosing <menuchoice><guisubmenu>View</guisubmenu>
 439     <guimenuitem>Locals</guimenuitem></menuchoice>
 440    </para>
 441    <para>
 442     Local variables of the current frame (the current funtion in which the program control
 443     is present) are displayed in the <interface>Locals list window</interface>.
 444     During execution of the program (eg. during single stepping), local
 445     variables will be updated. If any varialble value was changed in the last debugging step, its
 446     value will be highlight in red. The variables are presented in a tree form for easy
 447     view.
 448     <figure>
 449       <title>Local variables</title>
 450       <screenshot>
 451           <screeninfo>Local variables</screeninfo>
 452        <graphic fileref="figures/local_variables.png" format="PNG" srccredit="naba"></graphic>
 453       </screenshot>
 454     </figure>
 455    </para>
 456    <para>
 457     The value of a local variable can be modified by selecting it and clicking in
 458     the value column.
 459    </para>
 460    <note>
 461     <para>
 462      Gdb is more and more often used as a back end for a graphical front end. It
 463      has been improved recently in this area. It is recommanded to use the latest
 464      version (6.6) of gdb. On older version, gdb can crash when the front end
 465      ask for an pointer with an invalid (but not used) value.
 466     </para>
 467    </note>
 468   </sect2>
 469
 470   <sect2 id="var-watch">
 471    <title>Listing watched expressions</title>
 472    <para>
 473     Inspecting or evaluating an expression provides the result only once. To continuously
 474         monitor some variables or expressions, use <emphasis>expression watch</emphasis>.
 475    </para>
 476    <para>
 477      Choose the menu item <menuchoice><guisubmenu>View</guisubmenu><guimenuitem>Watch
 478          Window</guimenuitem></menuchoice> to display the <interface>expression watch window</interface>.
 479    </para>
 480   </sect2>
 481
 482   <sect2 id="watch-add">
 483    <title>Adding an expression to watch</title>
 484    <para>
 485     Right-click on the <interface>expression watch window</interface>
 486     to open the <interface>Operation menu</interface>. Choose the
 487         menu item <guimenuitem>Add Watch&hellip;</guimenuitem>. Alternatively, you can
 488     use <menuchoice><guisubmenu>Debug</guisubmenu>
 489         <guimenuitem>Add Watch&hellip;</guimenuitem></menuchoice>
 490     A dialog prompting for the expression will appear. Enter the expression and
 491     click <guibutton>OK</guibutton>.
 492    </para>
 493    <para>
 494     By default watch expression are updated automatically
 495     each time the program is stopped. This can be changed in the add watch dialog
 496     or later using the <guimenuitem>Automatic update</guimenuitem> menu item in the
 497     <interface>expression watch window</interface> popup menu. A watched expression
 498     can be update manually by choosing
 499     <guimenuitem>Update Watch</guimenuitem> or <guimenuitem>Update All</guimenuitem> in
 500     the previous menu.
 501    </para>
 502    <para>
 503     It is not necessary to have the debugger running to add a new watch expression.
 504     If the debugger is not running or the corresponding expression cannot be found,
 505     the front end will try to create the watch expression, each time the program
 506     is stopped.
 507    </para>
 508   </sect2>
 509
 510   <sect2 id="watch-remove">
 511    <title>Removing an expression from watch</title>
 512    <para>
 513     Select the watch expression that you want to remove in the <interface>expression watch
 514         window</interface>, then open the <interface>Operation menu</interface>, clicking
 515     with the right mouse button, and choose the
 516         menu item <guimenuitem>Remove</guimenuitem> to remove it.
 517    </para>
 518    <para>
 519     All watch can be removed by choosing <guimenuitem>Remove All</guimenuitem> in the
 520     popup menu of the <interface>expression watch window</interface>.
 521    </para>
 522   </sect2>
 523
 524   <sect2 id="expr-eval">
 525    <title>Evaluating expressions</title>
 526    <para>
 527     When control is returned from a program &mdash; possibly at a breakpoint &mdash;
 528         it is possible to evaluate expressions or inspect the values of variables in the
 529         program. Choose the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
 530     <guimenuitem>Inspect/Evaluate &hellip;</guimenuitem></menuchoice>,
 531     <menuchoice><guimenuitem>Inspect/Evaluate &hellip;</guimenuitem></menuchoice>
 532     in the popup menu of the editor or click
 533         the <guibutton>Inspect</guibutton> button on the <interface>Debug Toolbar</interface>.
 534    </para>
 535    <para>
 536     A window will appear showing the result of the evaluation.
 537    </para>
 538    <para>
 539     If an expression is highlighted in the editor, it is already displayed else
 540     the window is empty. In both cases, you an select a new expression by clicking
 541     on the name column and writing the new expression.
 542    </para>
 543    <para>
 544     The expression can be added directly in the list of watched expressions by
 545     clicking on <guibutton>Add</guibutton> button.
 546    </para>
 547   </sect2>
 548
 549  </sect1>
 550
 551 <!-- ============= Debugging: Program Stack ====================== -->
 552  <sect1 id="debugging-stack">
 553   <title>Stack Trace and Thread</title>
 554
 555   <sect2 id="stack-win">
 556    <title>Stack Window</title>
 557    <para>
 558     The <interface>Stack trace window</interface> shows the contents of the
 559         program stack. It lists all of the functions and their arguments in the
 560         sequence they were called. There is also a number representing each call.
 561         This number is called the <emphasis>Frame</emphasis>. Each call in the trace
 562         exists in a different frame. This starts from frame 0 (the last function
 563     called) and grows higher as the function nesting become deeper.
 564    </para>
 565    <para>
 566     Choose the menu item <menuchoice><guisubmenu>View</guisubmenu><guimenuitem>Program
 567         Stack</guimenuitem></menuchoice>, to open the stack trace for the program
 568         being debugged.
 569    </para>
 570    <para>
 571     <figure>
 572       <title>Stack trace window</title>
 573       <screenshot>
 574            <screeninfo>Stack trace window</screeninfo>
 575        <graphic fileref="figures/stack.png" format="PNG" srccredit="andyp"></graphic>
 576       </screenshot>
 577     </figure>
 578    </para>
 579    <para>
 580     A small arrow points to the currently selected frame in the stack trace. By
 581         default, this will be frame 0, the last function called. All of the evaluation
 582         and inspection of expressions or variables will be with reference to this selected
 583         frame. The scope of the variables or expressions being evaluated will be limited
 584         to the selected frame only. The same applies for new expressions only in the watch.
 585    </para>
 586   </sect2>
 587
 588   <sect2 id="stack-frame">
 589    <title>Setting the current frame</title>
 590    <para>
 591     Double-clicking on any frame in the stack trace will set that frame as the
 592         currently selected frame (the arrow will point to the frame, indicating that it
 593         has been selected as the current frame). Alternatively, open the
 594         <interface>Operation menu</interface> by right-clicking on the
 595         <interface>Stack trace window</interface>, and choose the menu item
 596         <guimenuitem>Set frame</guimenuitem> to set the frame.
 597    </para>
 598    <para>
 599     Changing the stack frame will change the <interface>Locals list window</interface>
 600     content, but not the <interface>expression watch window</interface> as each
 601     expression is evaluated in the frame used when it was defined.
 602    </para>
 603   </sect2>
 604
 605   <sect2 id="thread-win">
 606    <title>Thread Window</title>
 607    <para>
 608     The <interface>Thread window</interface> show all threads used by the program
 609     and display the current thread. Choose the menu item <menuchoice><guisubmenu>View</guisubmenu>
 610     <guimenuitem>Thread</guimenuitem></menuchoice>, to open this window.
 611    </para>
 612    <para>
 613     A small arrow points to the current thread. When the
 614     programm is stopped, it correspond to the thread which has been interrupted.
 615     Each thread has its own stack frame,so changing the current thread will change
 616     the current stack frame.
 617    </para>
 618   </sect2>
 619
 620   <sect2 id="set-thread">
 621    <title>Setting the current thread</title>
 622    <para>
 623     Double-clicking on any thread in the thread list will set that thread as the
 624         currently selected thread (the arrow will point to the thread, indicating that it
 625         has been selected as the current thread). Alternatively, open the
 626         <interface>Operation menu</interface> by right-clicking on the
 627         <interface>Thread list window</interface>, and choose the menu item
 628         <guimenuitem>Set thread</guimenuitem> to set the thread.
 629    </para>
 630    <para>
 631     Changing the thread will change the value of CPU registers and the current
 632     stack frame, so the <interface>Locals list window</interface> will change too.
 633    </para>
 634   </sect2>
 635  </sect1>
 636
 637 <!-- ============= Debugging: CPU ====================== -->
 638  <sect1 id="debugging-cpu">
 639   <title>CPU</title>
 640
 641   <sect2 id="cpu-regs">
 642    <title>Register window</title>
 643    <para>
 644     It is possible to examine the contents of the internal registers of the
 645         CPU (microprocessor). Choose the menu item <menuchoice><guisubmenu>View</guisubmenu>
 646         <guimenuitem>Registers</guimenuitem></menuchoice>. A window listing all
 647         of the available registers in the microprocessor and their corresponding contents
 648         will appear.
 649    </para>
 650    <para>
 651     If any register value was changed in the last debugging step, its
 652     value will be highlight in red. It is possible to change one register value
 653     by selecting it and clicking in the value column.
 654    </para>
 655   </sect2>
 656
 657   <sect2 id="cpu-memory">
 658    <title>Memory window</title>
 659    <para>
 660     Choose the menu item <menuchoice><guisubmenu>View</guisubmenu><guimenuitem>Memory
 661         </guimenuitem></menuchoice>, to open the <interface>memory window</interface>
 662     for the program being debugged. This window shows the contents of all memory.
 663    </para>
 664    <para>
 665     The first is the memory address in hexadecimal, the second is the memory content
 666     in hexadecimal too and the last column is the memory content in ascii.
 667    </para>
 668    <para>
 669     The addressing space of even a 32 bits microprocessor is quite big(4 Giga bytes),
 670     so it is very difficult to go to a particular address with the scrollbar. But
 671     you can click on the right mouse button, get a new menu and select
 672     <menuchoice><guimenuitem>Goto address</guimenuitem></menuchoice> to get
 673     a small edit box where you can enter an address in hexadecimal.
 674    </para>
 675   </sect2>
 676
 677   <sect2 id="cpu-disassembly">
 678    <title>Disassembly window</title>
 679    <para>
 680     Choose the menu item <menuchoice><guisubmenu>View</guisubmenu><guimenuitem>Disassembly
 681         </guimenuitem></menuchoice>, to open the <interface>disassembly window</interface>
 682     for the program being debugged.
 683         registers.
 684    </para>
 685    <para>
 686     The first column is the address in hexadecimal. In the second column, you can
 687     have a label starting at the beginning of the line and ended with a colon or
 688     a assembler instruction starting after 4 space characters.
 689    </para>
 690    <para>
 691     Again, as the addressing space is very big, the scrollbar is quite useless.
 692     You can click on the right mouse button, get a new menu and select
 693     <menuchoice><guimenuitem>Goto address</guimenuitem></menuchoice> to get
 694     a small edit box where you can enter an address in hexadecimal. The position
 695     in the disassembly window will be changed to the program counter value when
 696     the program is stopped.
 697    </para>
 698   </sect2>
 699  </sect1>
 700
 701 <!-- Debugger: Others-->
 702  <sect1 id="debugger-others">
 703   <title>Others</title>
 704
 705   <para>
 706    There are a number of other debugger features used less frequently and not
 707    very well integrated in the new front end but which are still working.
 708   </para>
 709
 710   <sect2 id="dbg-dyna-libs">
 711    <title>Dynamically loaded Libraries</title>
 712    <para>
 713     To obtain a list of the dynamic libraries used by the program, choose the
 714         menu item <menuchoice><guisubmenu>Debug</guisubmenu><guisubmenu>Info</guisubmenu>
 715         <guimenuitem>Shared Libraries</guimenuitem></menuchoice>. This will bring
 716         open a window which will list all the shared libraries the program has loaded
 717         and their locations in the memory. It also shows whether the symbol table is
 718         loaded or not (Yes/No).
 719    </para>
 720    <para>
 721     <figure>
 722       <title>Shared Libraries window</title>
 723       <screenshot>
 724            <screeninfo>Shared Libraries window</screeninfo>
 725        <graphic fileref="figures/sharedlibs.png" format="PNG" srccredit="andyp"></graphic>
 726       </screenshot>
 727     </figure>
 728    </para>
 729   </sect2>
 730
 731   <sect2 id="dbg-signal">
 732    <title>Kernel Signals</title>
 733    <para>
 734     Kernel signals are a way of signaling between processes in Linux. The list
 735         of signals available for a program can be displayed by choosing the menu item
 736     <menuchoice><guisubmenu>Debug</guisubmenu><guisubmenu>Info</guisubmenu><guimenuitem>Kernel Signals</guimenuitem></menuchoice>.
 737     A window will open which lists all of the signals available in the system along with
 738     a brief description of each signal.
 739    </para>
 740    <para>
 741     <figure>
 742       <title>Kernel Signals window</title>
 743       <screenshot>
 744            <screeninfo>Kernel Signals window</screeninfo>
 745        <graphic fileref="figures/signals.png" format="PNG" srccredit="andyp"></graphic>
 746       </screenshot>
 747     </figure>
 748    </para>
 749    <para>
 750     There are three columns which specify what to do when the signal is received:
 751    </para>
 752
 753    <orderedlist>
 754     <listitem>
 755      <para><emphasis>Stop</emphasis> &mdash; this tells the debugger whether to
 756          stop the program execution (and return control) when the program receives
 757          this signal.
 758      </para>
 759     </listitem>
 760     <listitem>
 761      <para><emphasis>Print</emphasis> &mdash; this tells the debugger whether to
 762          display the received signal.
 763      </para>
 764     </listitem>
 765     <listitem>
 766      <para><emphasis>Pass</emphasis> &mdash; this tells the debugger whether to pass
 767          the signal to the program.
 768      </para>
 769     </listitem>
 770    </orderedlist>
 771    <note>
 772     <para>
 773      The popup menu that is displayed when you click on the right mouse button has
 774      all its item disabled because the corresponding functions are not implemented
 775      yet.
 776     </para>
 777    </note>
 778   </sect2>
 779
 780   <sect2 id="dbg-files">
 781    <title>Information about used files</title>
 782    <para>
 783     It is possible to get some information about the files used by the debugged program.
 784         by choosing the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
 785         <guisubmenu>Information</guisubmenu><guimenuitem>Target files</guimenuitem></menuchoice>.
 786         A window will open displaying all informations.
 787    </para>
 788   </sect2>
 789
 790   <sect2 id="dbg-program">
 791    <title>Information about debugged program</title>
 792    <para>
 793     It is possible to get some information about the debugged program
 794         by choosing the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
 795         <guisubmenu>Information</guisubmenu><guimenuitem>Program</guimenuitem></menuchoice>.
 796         A window will open displaying all informations.
 797    </para>
 798   </sect2>
 799
 800   <sect2 id="dbg-kernel">
 801    <title>Information about kernel structure</title>
 802    <para>
 803     It is possible to get some information kernel data on the current process
 804         by choosing the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
 805         <guisubmenu>Information</guisubmenu><guimenuitem>Kernel user struct</guimenuitem></menuchoice>.
 806         A window will open displaying all informations.
 807    </para>
 808   </sect2>
 809
 810   <sect2 id="var-global">
 811    <title>Information about global variables</title>
 812    <para>
 813     It is possible to list all global variables
 814         by choosing the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
 815         <guisubmenu>Information</guisubmenu><guimenuitem>Info Global Variable</guimenuitem></menuchoice>.
 816         A window will open listing all global variables.
 817    </para>
 818   </sect2>
 819
 820   <sect2 id="stack-frame-info">
 821    <title>Information about the current frame</title>
 822    <para>
 823     It is possible to obtain information about the currently selected frame
 824         by choosing the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
 825         <guisubmenu>Information</guisubmenu><guimenuitem>Info Current Frame</guimenuitem></menuchoice>.
 826         A window will open describing the current frame.
 827    </para>
 828   </sect2>
 829
 830   <sect2 id="stack-arg-info">
 831    <title>Information about the current function arguments</title>
 832    <para>
 833     It is possible to obtain information about the arguments of the current function
 834         by choosing the menu item <menuchoice><guisubmenu>Debug</guisubmenu>
 835         <guisubmenu>Information</guisubmenu><guimenuitem>Arguments</guimenuitem></menuchoice>.
 836         A window will open describing the arguments.
 837    </para>
 838   </sect2>
 839
 840   <sect2 id="dbg-command">
 841    <title>User command</title>
 842    <para>
 843     To send directly a command to the back end choose the
 844         menu item <menuchoice><guimenu>Debug</guimenu>
 845         <guimenuitem>Debugger command</guimenuitem></menuchoice>. This will bring
 846     a small dialog where you can enter commands that will be send to the debugger
 847     when you press <keycap>Return</keycap>.
 848    </para>
 849    <note>
 850     <para>
 851      The front end sends this command directly to the back end without doing any check.
 852      By example if you set a breakpoint like this, it will not appear in the
 853      <interface>breakpoint list window</interface>. It is better to avoid using this
 854      command unless you know exactly what you are doing.
 855     </para>
 856    </note>
 857   </sect2>
 858  </sect1>
 859
 860  </chapter>