DEBUG

   1 Introduction
   2 ============
   3
   4 This is a short tutorial on debugging KDE applications. Throughout this
   5 tutorial I will use "kedit" as example application.
   6
   7
   8 Configuring for debugging
   9 =========================
  10
  11 You can use --enable-debug with the configure script, if you want to have
  12 debug code in your KDE libs. If you have the space and can stand code that's
  13 somewhat slower, this is worth it. The extra information really
  14 helps debugging and thus bugfixing.
  15
  16 On the other hand, --disable-debug removes all debug messages, leading
  17 to a faster and cleaner desktop.
  18
  19
  20 Debugging with GDB
  21 ==================
  22
  23 The recommended version of gdb to use is version 4.95 or higher, older
  24 versions have problems generating proper backtraces.
  25
  26 There are three ways to debug an application with gdb:
  27
  28 1) You can start the application from within gdb.
  29 2) You can attach gdb to an already running application.
  30 3) You can run gdb after an application has crashed using a core file.
  31
  32
  33 Starting applications from within gdb
  34 =====================================
  35
  36 To start an application with gdb you can start gdb as follows:
  37
  38 > gdb kedit
  39 GNU gdb 4.95.0
  40 Copyright 2000 Free Software Foundation, Inc.
  41 GDB is free software, covered by the GNU General Public License, and you are
  42 welcome to change it and/or distribute copies of it under certain conditions.
  43 Type "show copying" to see the conditions.
  44 There is absolutely no warranty for GDB.  Type "show warranty" for details.
  45 This GDB was configured as "i686-pc-linux-gnu"...
  46 (gdb)
  47
  48 You can now set the command line arguments that you want to pass to kedit with
  49 the gdb command "set args":
  50
  51 (gdb) set args myfile.txt
  52 (gdb)
  53
  54 gdb has loaded the kedit executable on startup but it hasn't loaded any of
  55 the libraries yet. This means that you can set any breakpoints in the
  56 libraries yet. The easiest way to do that is to set a breakpoint in the
  57 first line of main and then start the program:
  58
  59 (gdb) break main
  60 Breakpoint 1 at 0x804855c
  61 (gdb) run
  62 Starting program: /opt/kde/bin/kedit myfile.txt
  63 Breakpoint 1 at 0x4002cf18: file kedit.cpp, line 1595.
  64
  65 Breakpoint 1, main (argc=2, argv=0xbffff814) at kedit.cpp:1595
  66 1595            bool have_top_window = false;
  67 Current language:  auto; currently c++
  68 (gdb)
  69
  70 You can now set breakpoints everywhere. For example lets set a breakpoint
  71 in the KApplication constructor. Unfortunately gdb is not very good in
  72 handling C++ names, so it is not really possible to specify the constructor
  73 directly after the break command. Instead we look up a line of source
  74 code where we want to place the breakpoint. An external editor is of great
  75 use at this point. With the list command we can select the source file we
  76 are interested in and verify that we have found the correct source line:
  77
  78 (gdb) list kapp.cpp:220
  79 215         parseCommandLine( argc, argv );
  80 216     }
  81 217
  82 218     KApplication::KApplication( bool allowStyles, bool GUIenabled ) :
  83 219       QApplication( *KCmdLineArgs::qt_argc(), *KCmdLineArgs::qt_argv(),
  84 220                     GUIenabled ),
  85 221       KInstance( KCmdLineArgs::about),
  86 222       d (new KApplicationPrivate)
  87 223     {
  88 224         if (!GUIenabled)
  89 (gdb) break 224
  90 Breakpoint 2 at 0x4048aa7e: file kapp.cpp, line 224.
  91 (gdb)
  92
  93 We can now continue the execution of kedit. Execution will stop when it hits
  94 a breakpoint of when the program exits. In this case execution will stop
  95 in the first line of the KApplication constructor:
  96
  97 (gdb) continue
  98 Continuing.
  99 Qt: gdb: -nograb added to command-line options.
 100          Use the -dograb option to enforce grabbing.
 101
 102 Breakpoint 2, KApplication::KApplication (this=0xbffff6a8, allowStyles=true,
 103     GUIenabled=true) at kapp.cpp:224
 104 224         if (!GUIenabled)
 105 (gdb)
 106
 107
 108 Attaching gdb to already running applications
 109 =============================================
 110
 111 Sometimes it is not practical to start an application from within gdb.
 112 E.g. in those cases where you didn't know the application was about to
 113 crash :-) When you get the friendly DrKonqi dialog informing you about
 114 a crash you are just in time to start your debugger.
 115
 116 First lets attach gdb to an application that hasn't crashed (yet).
 117
 118 You start with finding the process of the application with e.g. "ps -aux":
 119
 120 > ps -aux | grep kedit
 121 bastian  21570 15.1  6.8 13740 8800 pts/6    S    15:34   0:01 kedit
 122 bastian  21582  0.0  0.3  1132  412 pts/6    R    15:34   0:00 grep kedit
 123
 124 From this you learn that kedit has process id 21570. Now you can start gdb as
 125 follows:
 126
 127 > gdb kedit 21570
 128 GNU gdb 4.95.0
 129 Copyright 2000 Free Software Foundation, Inc.
 130 GDB is free software, covered by the GNU General Public License, and you are
 131 welcome to change it and/or distribute copies of it under certain conditions.
 132 Type "show copying" to see the conditions.
 133 There is absolutely no warranty for GDB.  Type "show warranty" for details.
 134 This GDB was configured as "i686-pc-linux-gnu"...
 135 /home1/bastian/21570: No such file or directory.
 136 Attaching to program: /opt/kde/bin/kedit, Pid 21570
 137 Reading symbols from /opt/kde/lib/kedit.so.0...done.
 138 Loaded symbols for /opt/kde/lib/kedit.so.0
 139 ....
 140 Reading symbols from /lib/ld-linux.so.2...done.
 141 Loaded symbols for /lib/ld-linux.so.2
 142 Reading symbols from /lib/libnss_compat.so.2...done.
 143 Loaded symbols for /lib/libnss_compat.so.2
 144 Reading symbols from /lib/libnsl.so.1...done.
 145 Loaded symbols for /lib/libnsl.so.1
 146 0x40c3d88e in __select () from /lib/libc.so.6
 147 (gdb)
 148
 149 You will usually end up in the middle of a select() call from the event-loop.
 150 This is the place where a KDE application spends most of its time, waiting
 151 for things to happen.
 152
 153 A backtrace will typically look something like this:
 154
 155 (gdb) bt
 156 #0  0x40c3d88e in __select () from /lib/libc.so.6
 157 #1  0x40a22844 in __DTOR_END__ () at fam.c++:356
 158 #2  0x407293bf in QApplication::enter_loop (this=0xbffff6e8)
 159     at kernel/qapplication.cpp:2552
 160 #3  0x406b1d7b in QApplication::exec (this=0xbffff6e8)
 161     at kernel/qapplication_x11.cpp:2217
 162 #4  0x4002d500 in main (argc=1, argv=0xbffff854) at kedit.cpp:1662
 163 #5  0x40bbba5e in __libc_start_main (main=0x8048568 <main>, argc=1,
 164     argv=0xbffff854, init=0x8048514 <_init>, fini=0x80486cc <_fini>,
 165     rtld_fini=0x4000aa20 <_dl_fini>, stack_end=0xbffff84c)
 166     at ../sysdeps/generic/libc-start.c:92
 167 (gdb)
 168
 169
 170 Getting core dumps
 171 ==================
 172
 173 If you want to have a core dump after your application crashes you need to
 174 do two things:
 175
 176 1) Disable the KDE crash handler. This can be done either by using the
 177 --nocrashhandler command line option or by setting the KDE_DEBUG environment
 178 variable to some value e.g. KDE_DEBUG=true.
 179
 180 2) Enable core dump generation by changing the so called 'ulimits' with the
 181 following command:
 182         ulimit -c unlimited
 183
 184