libstdc++-v3/doc/xml/manual/debug.xml

   1 <sect1 id="manual.intro.using.debug" xreflabel="Debugging Support">
   2 <?dbhtml filename="debug.html"?>
   3
   4 <sect1info>
   5   <keywordset>
   6     <keyword>
   7       C++
   8     </keyword>
   9     <keyword>
  10       debug
  11     </keyword>
  12   </keywordset>
  13 </sect1info>
  14
  15 <title>Debugging Support</title>
  16
  17 <para>
  18   There are numerous things that can be done to improve the ease with
  19   which C++ binaries are debugged when using the GNU tool chain. Here
  20   are some of them.
  21 </para>
  22
  23 <sect2 id="debug.compiler">
  24 <title>Using <command>g++</command></title>
  25   <para>
  26     Compiler flags determine how debug information is transmitted
  27     between compilation and debug or analysis tools.
  28   </para>
  29
  30   <para>
  31     The default optimizations and debug flags for a libstdc++ build
  32     are <code>-g -O2</code>. However, both debug and optimization
  33     flags can be varied to change debugging characteristics. For
  34     instance, turning off all optimization via the <code>-g -O0
  35     -fno-inline</code> flags will disable inlining and optimizations,
  36     and add debugging information, so that stepping through all functions,
  37     (including inlined constructors and destructors) is possible. In
  38     addition, <code>-fno-eliminate-unused-debug-types</code> can be
  39     used when additional debug information, such as nested class info,
  40     is desired.
  41 </para>
  42
  43 <para>
  44   Or, the debug format that the compiler and debugger use to
  45   communicate information about source constructs can be changed via
  46   <code>-gdwarf-2</code> or <code>-gstabs</code> flags: some debugging
  47   formats permit more expressive type and scope information to be
  48   shown in gdb. Expressiveness can be enhanced by flags like
  49   <code>-g3</code>. The default debug information for a particular
  50   platform can be identified via the value set by the
  51   PREFERRED_DEBUGGING_TYPE macro in the gcc sources.
  52 </para>
  53
  54 <para>
  55   Many other options are available: please see <ulink
  56   url="http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options">"Options
  57   for Debugging Your Program"</ulink> in Using the GNU Compiler
  58   Collection (GCC) for a complete list.
  59 </para>
  60 </sect2>
  61
  62 <sect2 id="debug.req">
  63 <title>Debug Versions of Library Binary Files</title>
  64
  65 <para>
  66   If you would like debug symbols in libstdc++, there are two ways to
  67   build libstdc++ with debug flags. The first is to run make from the
  68   toplevel in a freshly-configured tree with
  69 </para>
  70 <programlisting>
  71      --enable-libstdcxx-debug
  72 </programlisting>
  73 <para>and perhaps</para>
  74 <programlisting>
  75      --enable-libstdcxx-debug-flags='...'
  76 </programlisting>
  77 <para>
  78   to create a separate debug build. Both the normal build and the
  79   debug build will persist, without having to specify
  80   <code>CXXFLAGS</code>, and the debug library will be installed in a
  81   separate directory tree, in <code>(prefix)/lib/debug</code>. For
  82   more information, look at the <link
  83   linkend="manual.intro.setup.configure">configuration</link> section.
  84 </para>
  85
  86 <para>
  87   A second approach is to use the configuration flags
  88 </para>
  89 <programlisting>
  90      make CXXFLAGS='-g3 -fno-inline -O0' all
  91 </programlisting>
  92
  93 <para>
  94   This quick and dirty approach is often sufficient for quick
  95   debugging tasks, when you cannot or don't want to recompile your
  96   application to use the <link linkend="manual.ext.debug_mode">debug mode</link>.</para>
  97 </sect2>
  98
  99 <sect2 id="debug.memory">
 100 <title>Memory Leak Hunting</title>
 101
 102 <para>
 103   There are various third party memory tracing and debug utilities
 104   that can be used to provide detailed memory allocation information
 105   about C++ code. An exhaustive list of tools is not going to be
 106   attempted, but includes <code>mtrace</code>, <code>valgrind</code>,
 107   <code>mudflap</code>, and the non-free commercial product
 108   <code>purify</code>. In addition, <code>libcwd</code> has a
 109   replacement for the global new and delete operators that can track
 110   memory allocation and deallocation and provide useful memory
 111   statistics.
 112 </para>
 113
 114 <para>
 115   Regardless of the memory debugging tool being used, there is one
 116   thing of great importance to keep in mind when debugging C++ code
 117   that uses <code>new</code> and <code>delete</code>: there are
 118   different kinds of allocation schemes that can be used by <code>
 119   std::allocator </code>. For implementation details, see the <link
 120   linkend="manual.ext.allocator.mt">mt allocator</link> documentation and
 121   look specifically for <code>GLIBCXX_FORCE_NEW</code>.
 122 </para>
 123
 124 <para>
 125   In a nutshell, the default allocator used by <code>
 126   std::allocator</code> is a high-performance pool allocator, and can
 127   give the mistaken impression that in a suspect executable, memory is
 128   being leaked, when in reality the memory "leak" is a pool being used
 129   by the library's allocator and is reclaimed after program
 130   termination.
 131 </para>
 132
 133 <para>
 134   For valgrind, there are some specific items to keep in mind. First
 135   of all, use a version of valgrind that will work with current GNU
 136   C++ tools: the first that can do this is valgrind 1.0.4, but later
 137   versions should work at least as well. Second of all, use a
 138   completely unoptimized build to avoid confusing valgrind. Third, use
 139   GLIBCXX_FORCE_NEW to keep extraneous pool allocation noise from
 140   cluttering debug information.
 141 </para>
 142
 143 <para>
 144   Fourth, it may be necessary to force deallocation in other libraries
 145   as well, namely the "C" library. On linux, this can be accomplished
 146   with the appropriate use of the <code>__cxa_atexit</code> or
 147   <code>atexit</code> functions.
 148 </para>
 149
 150 <programlisting>
 151    #include &lt;cstdlib&gt;
 152
 153    extern "C" void __libc_freeres(void);
 154
 155    void do_something() { }
 156
 157    int main()
 158    {
 159      atexit(__libc_freeres);
 160      do_something();
 161      return 0;
 162    }
 163 </programlisting>
 164
 165
 166 <para>or, using <code>__cxa_atexit</code>:</para>
 167
 168 <programlisting>
 169    extern "C" void __libc_freeres(void);
 170    extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d);
 171
 172    void do_something() { }
 173
 174    int main()
 175    {
 176       extern void* __dso_handle __attribute__ ((__weak__));
 177       __cxa_atexit((void (*) (void *)) __libc_freeres, NULL,
 178                    &amp;__dso_handle ? __dso_handle : NULL);
 179       do_test();
 180       return 0;
 181    }
 182 </programlisting>
 183
 184 <para>
 185   Suggested valgrind flags, given the suggestions above about setting
 186   up the runtime environment, library, and test file, might be:
 187 </para>
 188 <programlisting>
 189    valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out
 190 </programlisting>
 191
 192 </sect2>
 193
 194 <sect2 id="debug.gdb">
 195 <title>Using <command>gdb</command></title>
 196   <para>
 197   </para>
 198
 199 <para>
 200   Many options are available for gdb itself: please see <ulink
 201   url="http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC125">
 202   "GDB features for C++" </ulink> in the gdb documentation. Also
 203   recommended: the other parts of this manual.
 204 </para>
 205
 206 <para>
 207   These settings can either be switched on in at the gdb command line,
 208   or put into a .gdbint file to establish default debugging
 209   characteristics, like so:
 210 </para>
 211
 212 <programlisting>
 213    set print pretty on
 214    set print object on
 215    set print static-members on
 216    set print vtbl on
 217    set print demangle on
 218    set demangle-style gnu-v3
 219 </programlisting>
 220
 221 <para>
 222   Starting with version 7.0, GDB includes support for writing
 223   pretty-printers in Python.  Pretty printers for STL classes are
 224   distributed with GCC from version 4.5.0.  The most recent version of
 225   these printers are always found in libstdc++ svn repository.
 226   To enable these printers, check-out the latest printers to a local
 227   directory:
 228 </para>
 229
 230 <programlisting>
 231   svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python
 232 </programlisting>
 233
 234 <para>
 235   Next, add the following section to your ~/.gdbinit  The path must
 236   match the location where the Python module above was checked-out.
 237   So if checked out to: /home/maude/gdb_printers/, the path would be as
 238   written in the example below.
 239 </para>
 240
 241 <programlisting>
 242   python
 243   import sys
 244   sys.path.insert(0, '/home/maude/gdb_printers/python')
 245   from libstdcxx.v6.printers import register_libstdcxx_printers
 246   register_libstdcxx_printers (None)
 247   end
 248 </programlisting>
 249
 250 <para>
 251   The path should be the only element that needs to be adjusted in the
 252   example.  Once loaded, STL classes that the printers support
 253   should print in a more human-readable format.  To print the classes
 254   in the old style, use the /r (raw) switch in the print command
 255   (i.e., print /r foo).  This will print the classes as if the Python
 256   pretty-printers were not loaded.
 257 </para>
 258
 259 <para>
 260   For additional information on STL support and GDB please visit:
 261   <ulink url="http://sourceware.org/gdb/wiki/STLSupport"> "GDB Support
 262   for STL" </ulink> in the GDB wiki.  Additionally, in-depth
 263   documentation and discussion of the pretty printing feature can be
 264   found in "Pretty Printing" node in the GDB manual.  You can find
 265   on-line versions of the GDB user manual in GDB's homepage, at
 266   <ulink url="http://sourceware.org/gdb/"> "GDB: The GNU Project
 267   Debugger" </ulink>.
 268 </para>
 269
 270 </sect2>
 271
 272 <sect2 id="debug.exceptions">
 273 <title>Tracking uncaught exceptions</title>
 274 <para>
 275   The <link linkend="support.termination.verbose">verbose
 276   termination handler</link> gives information about uncaught
 277   exceptions which are killing the program.  It is described in the
 278   linked-to page.
 279 </para>
 280 </sect2>
 281
 282 <sect2 id="debug.debug_mode">
 283 <title>Debug Mode</title>
 284   <para> The <link linkend="manual.ext.debug_mode">Debug Mode</link>
 285   has compile and run-time checks for many containers.
 286   </para>
 287 </sect2>
 288
 289 <sect2 id="debug.compile_time_checks">
 290 <title>Compile Time Checking</title>
 291   <para> The <link linkend="manual.ext.compile_checks">Compile-Time
 292   Checks</link> Extension has compile-time checks for many algorithms.
 293   </para>
 294 </sect2>
 295
 296 <sect2 id="debug.profile_mode" xreflabel="debug.profile_mode">
 297 <title>Profile-based Performance Analysis</title>
 298   <para> The <link linkend="manual.ext.profile_mode">Profile-based
 299   Performance Analysis</link> Extension has performance checks for many
 300   algorithms.
 301   </para>
 302 </sect2>
 303
 304 </sect1>