path: root/doc/kdevelop/debugger.docbook

<chapter id="debugger">
<title>The Debugger Interface</title>
<indexterm zone="debugger"><primary>debugger</primary></indexterm>

<para>
For C and C++, &tdevelop; contains an internal debugger that is directly
integrated with the editor. Technically, it is implemented as a frontend
that uses the portable &GNU; debugger <application>gdb</application> through
a pipe. The debugger can be started in several ways:
</para>

<itemizedlist>
<listitem>
<para>
With <menuchoice><guimenu>Debug</guimenu><guimenuitem>Start</guimenuitem></menuchoice>,
the main program of your project is loaded into the debugger.
</para>
</listitem>

<listitem>
<para>
Using <menuchoice><guimenu>Debug</guimenu>
<guimenuitem>Start (other)</guimenuitem>
<guimenuitem>Examine core file</guimenuitem></menuchoice> you load a core file
into memory, which is generated by the operating system kernel when the
program has crashed (The generation of core files may be switched off on your
system, see <application>ulimit(1)</application>). This is useful for a
post-mortem analysis of a program.
</para>
</listitem>

<listitem>
<para>
With <menuchoice><guimenu>Debug</guimenu>
<guimenuitem>Start (other)</guimenuitem>
<guimenuitem>Attach to process</guimenuitem></menuchoice> you invoke the
debugger on an already running program. You will be shown a
process list where you can select the process which the debugger
should take over.
</para>
</listitem>

<listitem>
<para>
Note that debugging is only possible if your project has been compiled with
debugging information enabled. It can be activated in the
<guibutton>Compiler options</guibutton> dialog. When this option is switched
on, the compiler generates additional data which allows the debugger to
associate file names and line numbers with addresses in the executable.
</para>
</listitem>
</itemizedlist>

<para>
The debugger frontend offers several views <quote>into</quote> the process:
</para>

<para>If you try to debug a project without debugging information, you get
the message <computeroutput>No source...</computeroutput> in the status
bar.If you try to set a breakpoint, it is shown as <computeroutput>Pending
(add)</computeroutput> in the breakpoint window (see below).
</para>

<variablelist>
<varlistentry>
<term>Variables</term>
<listitem>
<indexterm zone="debugger"><primary>watch variables</primary></indexterm>
<para>
This window lists the values of all local variables at the current execution
point of the program. It covers the variables in the complete call stack,
&ie;  the function where the process was interrupted, the function that called
this function, and so on up to <function>main()</function> function.
</para>

<para>
Another branch in the variables contains watch variables. You can configure
yourself which variables are shown here. Both local and global variables can
be watched. You can add variables either by clicking on the
<guibutton>Add</guibutton> button or pressing <keycap>Return</keycap> while
the <guilabel>Watch</guilabel> item is selected. They can be removed again
via the context menu.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Frame Stack</term>
<listitem>
<indexterm zone="debugger"><primary>frame stack</primary></indexterm>
<para>
(... to be written ...)
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Breakpoints</term>
<listitem>
<indexterm zone="debugger"><primary>breakpoints</primary></indexterm>
<para>
This window allows you to see and manipulate the breakpoints.  Remember that
&tdevelop; uses <application>GDB</application>, so to fully understand the
&tdevelop; debugging features, you should know a little bit about the <ulink
url="http://www.gnu.org/software/gdb">GDB</ulink>.
</para>

<para>If you want to look at the source code, breakpoints are defined in
<filename>tdevelop/languages/cpp/debugger/breakpoint.h</filename>.
</para>

<para>At the left edge, the window has buttons to:</para>

<itemizedlist>
<listitem><para>Add an empty breakpoint</para></listitem>
<listitem><para>Edit the selected breakpoint</para></listitem>
 <listitem><para>Delete the selected breakpoint</para></listitem>
<listitem><para>Remove all breakpoints</para></listitem>
</itemizedlist>

<para>The main part of the window is a table with 7 columns.  Each line in
the table is a breakpoint.  The columns are:</para>

<orderedlist>
<listitem><para>Selection checkbox</para></listitem>
<listitem><para>Type: one of: Invalid, File:Line, Watchpoint, Address, Function</para></listitem>
<listitem><para>Status. Values are:</para>
<itemizedlist>
  <listitem><para>Active</para></listitem>
  <listitem><para>Disabled: Each breakpoint may be <quote>enabled</quote> or
  <quote>disabled</quote>; if disabled, it has no effect on your program until
  you enable it again.</para></listitem>
  <listitem><para>Pending (add): a breakpoint is marked like this if no
  debugging information is available. From GDB Info page:
  <blockquote><para>If a specified breakpoint location cannot be found, it may be due to
  the fact that the location is in a shared library that is yet to be
  loaded.  In such a case, you may want GDB to create a special
  breakpoint (known as a <quote>pending breakpoint</quote>) that attempts to resolve
  itself in the future when an appropriate shared library gets loaded.</para>
  </blockquote>
  </para></listitem>
</itemizedlist>
</listitem>
<listitem><para>Pending (clear)</para></listitem>
<listitem><para>Pending (modify)</para></listitem>
<listitem><para>Location in the format filename:linenumber</para></listitem>
<listitem><para>Condition</para></listitem>
<listitem><para>Ignore Count: If this is a number <varname>COUNT</varname>
greater than zero, the next <varname>COUNT</varname> times the breakpoint is
reached, your program's execution does not stop; other than to decrement the
ignore count, <application>gdb</application> takes no action.</para></listitem>
<listitem><para>Hits: counts how many times a breakopint has been hit.</para></listitem>
</orderedlist>


</listitem>
</varlistentry>

<varlistentry>
<term>Disassemble</term>
<listitem>
<indexterm zone="debugger"><primary>disassemble</primary></indexterm>
<para>(... to be written ...)</para>

</listitem>
</varlistentry>
</variablelist>


<sect1 id="settingbreakpoints">
<title>Setting Breakpoints</title>

<para>
(... to be written ...)
</para>

</sect1> <!-- settingbreakpoints -->

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<sect1 id ="debuggeroptions">
<title>Options</title>

<variablelist>
<varlistentry>
<term>Display Mangled Names</term>
<listitem>
<indexterm zone="debugger"><primary>name mangling</primary></indexterm>
<indexterm zone="debugger"><primary>mangling</primary><secondary>name</secondary></indexterm>

<para>
In C++, function names in the executable are <quote>mangled</quote>, &ie;
the function names include information about the argument types. This is
necessary in order to support overloading of functions. The mangling
algorithm is not standardized and differs even between different versions of
the &GNU; C++ compiler.
</para>

<para>
In the disassembling window, normally unmangled names are displayed, so
function signatures appear in the similar way as in the source code, so
they are easily readable. Alternatively, you can decide to see mangled names.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Try Setting Breakpoints on Lib Load</term>
<listitem>
<indexterm zone="debugger"><primary>lazy breakpoints</primary></indexterm>
<indexterm zone="debugger"><primary>breakpoints</primary><secondary>lazy</secondary></indexterm>

<para>
The debugger backend <application>gdb</application> does not allow to set
breakpoints within code that is not currently loaded. In a highly modular
application, where often code is only loaded on demand as a plugin (using
the libc function <function>dlopen(3)</function>), this can be inconvenient.
Therefore, &tdevelop; rolls its own support for breakpoints in shared
libraries. If you set this option, it allows you to set breakpoints in
libraries which are not loaded. Then, whenever <application>gdb</application>
notifies that a library is loaded, &tdevelop; tries to set the pending
breakpoints.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>Enable Floating Toolbar</term>
<listitem>
<indexterm zone="debugger"><primary>debugger toolbar</primary></indexterm>
<indexterm zone="debugger"><primary>toolbar</primary><secondary>debugger</secondary></indexterm>

<para>
(... to be written ...)
</para>
</listitem>
</varlistentry>
</variablelist>

</sect1> <!-- debuggeroptions -->

</chapter> <!-- debugger -->