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 </sect2>
 221
 222 <sect2 id="debug.exceptions">
 223 <title>Tracking uncaught exceptions</title>
 224 <para>
 225   The <link linkend="support.termination.verbose">verbose
 226   termination handler</link> gives information about uncaught
 227   exceptions which are killing the program.  It is described in the
 228   linked-to page.
 229 </para>
 230 </sect2>
 231
 232 <sect2 id="debug.debug_mode">
 233 <title>Debug Mode</title>
 234   <para> The <link linkend="manual.ext.debug_mode">Debug Mode</link>
 235   has compile and run-time checks for many containers.
 236   </para>
 237 </sect2>
 238
 239 <sect2 id="debug.compile_time_checks">
 240 <title>Compile Time Checking</title>
 241   <para> The <link linkend="manual.ext.compile_checks">Compile-Time
 242   Checks</link> Extension has compile-time checks for many algorithms.
 243   </para>
 244 </sect2>
 245
 246 <sect2 id="debug.profile_mode" xreflabel="debug.profile_mode">
 247 <title>Profile-based Performance Analysis</title>
 248   <para> The <link linkend="manual.ext.profile_mode">Profile-based
 249   Performance Analysis</link> Extension has performance checks for many
 250   algorithms.
 251   </para>
 252 </sect2>
 253
 254 </sect1>