kdbg/doc/en/index.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5    <meta name="Author" content="Johannes Sixt">
   6    <title>KDbg - User's Manual</title>
   7 </head>
   8 <body text="#000000" bgcolor="#FFFFFF">
   9
  10 <h1>
  11 KDbg - User's Manual</h1>
  12
  13 <h2>
  14 Contents</h2>
  15
  16 <ul>
  17 <li>
  18 <a href="#Introduction">Introduction</a></li>
  19
  20 <li>
  21 <a href="#UsingKDbg">Using KDbg</a></li>
  22
  23 <li>
  24 <a href="#InfoWindows">KDbg's information windows</a></li>
  25
  26 <li>
  27 <a href="#Tips">Tips and such</a></li>
  28
  29 <li>
  30 Advanced topic: <a href="types.html">Type tables</a></li>
  31
  32 <li>
  33 <a href="invocation.html">How to invoke KDbg from the command line</a></li>
  34
  35 <li>
  36 <a href="#Author">Author</a></li>
  37 </ul>
  38
  39 <hr>
  40 <h2>
  41 <a name="Introduction"></a>Introduction</h2>
  42 <p>KDbg is a front-end for <tt>gdb</tt>, the GNU debugger.</p>
  43 <p>This means that KDbg itself is not the debugger. Rather, it communicates
  44 with <tt>gdb</tt>, a command line debugger, by sending commands to it and
  45 receiving the output, such as variable values. The menu commands and mouse
  46 clicks are translated into <tt>gdb</tt> commands, and the output of <tt>gdb</tt>
  47 is translated into (more or less) visible information, such as structured
  48 variable contents.</p>
  49 <p>The upshot of all this is that KDbg completely relies on the capabilities
  50 of the underlying command line debugger, <tt>gdb</tt>. KDbg can do no more
  51 than <tt>gdb</tt> can. For example, if you have a <tt>gdb</tt> that does
  52 not supports debugging of threaded programs, KDbg cannot, either (even
  53 though it offers a threads window).</p>
  54 <h2>
  55 <a name="UsingKDbg"></a>Using KDbg</h2>
  56 <p>Before you start using KDbg, you may want to review the options in the
  57 <a href="globaloptions.html">Global Options</a> dialog that you invoke
  58 with <i>Settings|Global Options</i>.</p>
  59 <h4>
  60 Specifying a debugging target</h4>
  61 <p>To debug a program, choose <i>File|Load Executable</i> from the menu. If you
  62 have debugged the program earlier, you can choose it from <i>File|Recent
  63 Executables</i>. The program is loaded.</p>
  64 <p>If you want to debug a core dump, you must first load the executable
  65 that produced the core dump, then choose
  66 <i>File|Core Dump</i> from the
  67 menu. Now KDbg goes to the point in the program that caused the core dump.</p>
  68 <p>You can now set breakpoints, using the <i>Breakpoint</i> menu, the right
  69 mouse button menu, or the <a href="breakptlist.html">breakpoint window</a>.</p>
  70 <p>You can also choose program specific settings that apply only to the
  71 currently loaded executable using <i>Settings|This Program</i>, in the
  72 <a href="pgmsettings.html">Program Settings</a> dialog.</p>
  73 <p>Furthermore, it is possible to <a href="xslt.html">debug XSLT scripts</a>.</p>
  74 <h4>
  75 Running the program</h4>
  76 <p>Now run the program by selecting <i>Execution|Run</i>. The program now
  77 executes as usual until it either exits, hits a breakpoint or watchpoint,
  78 or receives a signal.</p>
  79 <p>You can run the program with arguments, set a working directory, or
  80 set environment variables. To do this, choose <i>Execution|Arguments</i>
  81 and specify your options in the <a href="argspwdenv.html">Program Arguments</a>
  82 dialog (before you start the program).</p>
  83 <p>You can also attach to a program that is currently running. To do this,
  84 first load the executable file like above. Then choose <i>Execution|Attach</i>.
  85 From the list processes specify the one you want to attach to
  86 and click <i>OK</i>. The running program is
  87 halted (not terminated), and the current point of execution is displayed
  88 in the source window.</p>
  89 <p><font size="-1">On some systems the list of processes may not be available.
  90 In this case a simple edit box is available where the process number can be
  91 specified.</font></p>
  92 <h4>
  93 The program stopped - now what?</h4>
  94 <p>When the program stops at a breakpoint, watchpoint, or due to a signal,
  95 the <a href="sourcecode.html">source code window</a> displays the line
  96 where the program stopped. It is very common that the program stops due
  97 to a signal (usually a <tt>SIGSEGV</tt>, segmentation violation) in a function
  98 that is not part of the program, that you have written. In this case you
  99 investigate the <a href="stack.html">stack window</a> and look for a function
 100 that you have written (start at the top of the list) and click on it. This
 101 will bring you to a location that you can start your search for the real
 102 bug.</p>
 103 <p>In the menu <i>Execution</i> you find the commands that you need to
 104 run
 105 the program, step through code, and to interrupt the program (<i>Break</i>)
 106 while it is running. The important commands (<i>Run</i> and all kinds of
 107 <i>Step</i>) are bound to function keys. For efficient debugging it is
 108 strongly recommend that you get used to using them. You can use
 109 <i>Settings|Configure Shortcuts</i> if you want to bind the functions
 110 to different keys.</p>
 111 <p>In the menu <i>Breakpoint</i> you find commands to set, clear, disable,
 112 and enable permanent and temporary breakpoints. You can display a list
 113 of breakpoints in the <a href="breakptlist.html">breakpoints window</a>.
 114 You can also set a breakpoint by clicking at the left end of the source
 115 line (using the left mouse button), and you can enable and disable a breakpoint
 116 by clicking it using the middle mouse button.</p>
 117 <p>The animation in the toolbar indicates whether the program
 118 is running. It stops when the program stopped in a breakpoint or for
 119 some other reason or when the program exited. This animated button is a shortcut
 120 for <i>Execution|Break</i>.</p>
 121 <h2>
 122 <a name="InfoWindows"></a>KDbg's information windows</h2>
 123 <p>KDbg displays information and accepts commands in number of different windows.
 124 In the menu <i>View</i> you find commands to show and hide these windows.
 125 They are docking windows, which means that you can drag them around and
 126 arrange them in any manner you like.</p>
 127 <ul>
 128 <li>
 129 <a href="sourcecode.html">The source code window</a></li>
 130
 131 <li>
 132 <a href="localvars.html">The local variables window</a></li>
 133
 134 <li>
 135 <a href="stack.html">The stack window</a></li>
 136
 137 <li>
 138 <a href="watches.html">The watched expressions window</a></li>
 139
 140 <li>
 141 <a href="breakptlist.html">The breakpoint list</a></li>
 142
 143 <li>
 144 <a href="pgmoutput.html">The output window</a></li>
 145
 146 <li>
 147 <a href="registers.html">The register dump window</a></li>
 148
 149 <li>
 150 <a href="memory.html">The memory dump window</a></li>
 151
 152 <li>
 153 <a href="threads.html">The threads window</a></li>
 154 </ul>
 155
 156 <h2>
 157 <a name="Tips"></a>Tips and such</h2>
 158 <p>The following topics give some useful hints on using KDbg.</p>
 159 <ul>
 160 <li>
 161 <a href="tips.html">Tips and Tricks</a></li>
 162
 163 <li>
 164 <a href="howdoi.html">How do I...?</a></li>
 165 </ul>
 166
 167 <h2>
 168 <a name="Author"></a>Author</h2>
 169 <p>KDbg is written by <a href="mailto:j6t@kdbg.org">Johannes Sixt</a>
 170 with contributions from many people, among others (in no particular order):</p>
 171 <ul>
 172 <li>Marc Font Freixa</li>
 173 <li>Michael Hansen</li>
 174 <li>Daniel Black</li>
 175 <li>Max Tomilov</li>
 176 <li>Charles Samuels</li>
 177 <li>David Edmundson</li>
 178 <li>Stefan Taferner</li>
 179 <li>Keith Isdale</li>
 180 <li>Daniel Thor Kristjansson</li>
 181 <li>Matthew Allen</li>
 182 </ul>
 183 <p>KDbg homepage is at <a href="http://www.kdbg.org/">http://www.kdbg.org/</a>.</p>
 184 </body>
 185 </html>