1 files changed, 242 insertions, 0 deletions
diff --git a/doc/kdevelop/debugger.docbook b/doc/kdevelop/debugger.docbook
new file mode 100644
index 00000000..a06f2c83
--- /dev/null
+++ b/doc/kdevelop/debugger.docbook
@@ -0,0 +1,242 @@
+<chapter id="debugger">
+<title>The Debugger Interface</title>
+<indexterm zone="debugger"><primary>debugger</primary></indexterm>
+
+<para>
+For C and C++, &kdevelop; 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
+&kdevelop; uses <application>GDB</application>, so to fully understand the
+&kdevelop; 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>kdevelop/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, &kdevelop; 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, &kdevelop; 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 -->