+++ /dev/null
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<!DOCTYPE html
- PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
- <meta name="AUTHOR" content="bkoz@gcc.gnu.org (Benjamin Kosnik)" />
- <meta name="KEYWORDS" content="c++, libstdc++, gdb, g++, debug" />
- <meta name="DESCRIPTION" content="Debugging C++ binaries" />
- <meta name="GENERATOR" content="vi and ten fingers" />
- <title>Debugging schemes and strategies</title>
-<link rel="StyleSheet" href="lib3styles.css" />
-</head>
-<body>
-
-<h1 class="centered"><a name="top">Debugging schemes and strategies</a></h1>
-
-<p class="fineprint"><em>
-<p>The latest version of this document is always available at
- <a href="http://gcc.gnu.org/onlinedocs/libstdc++/debug.html">
- http://gcc.gnu.org/onlinedocs/libstdc++/debug.html</a>.
-</p>
-
-<p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
-</p>
-</em></p>
-
-<!-- ####################################################### -->
-<hr />
-<p>There are numerous things that can be done to improve the ease with
- which C++ binaries are debugged when using the GNU C++
- tool chain. Here are some things to keep in mind when debugging C++
- code with GNU tools.
-</p>
-
-<h3 class="left"><a name="g++">Compiler flags determine debug info</a></h3>
-<p>The default optimizations and debug flags for a libstdc++ build are
- <code>-g -O2</code>. However, both debug and optimization flags can
- be varied to change debugging characteristics. For instance,
- turning off all optimization via the <code>-g -O0</code> flag will
- disable inlining, so that stepping through all functions, including
- inlined constructors and destructors, is possible. Or, the debug
- format that the compiler and debugger use to communicate
- information about source constructs can be changed via <code>
- -gdwarf-2 </code> or <code> -gstabs </code> flags: some debugging
- formats permit more expressive type and scope information to be
- shown in gdb.
- The default debug information for a particular platform can be
- identified via the value set by the PREFERRED_DEBUGGING_TYPE macro
- in the gcc sources.
-</p>
-
-<p>Many other options are available: please see
-<a href=http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options> "Options for Debugging Your Program" </a>
- in Using the GNU Compiler Collection (GCC) for a complete list.
-</p>
-
-
-<h3 class="left"><a name="lib">Using special flags to make a debug binary</a></h3>
-<p>There are two ways to build libstdc++ with debug flags. The first
- is to run make from the toplevel in a freshly-configured tree with
- specialized debug <code>CXXFLAGS</code>, as in <dd> <code> make
- CXXFLAGS='-g3 -O0' all </code></dd>
-</p>
-
-<p>This quick and dirty approach is often sufficient for quick
- debugging tasks, but the lack of state can be confusing in the long
- term.
-</p>
-
-<p>A second approach is to use the configuration flags
-</p>
-
- <dd><code>--enable-debug</code></dd>
-
-<p>and perhaps</p>
-
- <dd><code>--enable-debug-flags='...'</code></dd>
-
-<p>to create a separate debug build. Both the normal build and the
- debug build will persist, without having to specify
- <code>CXXFLAGS</code>, and the debug library will be installed in a
- separate directory tree, in <code>(prefix)/lib/debug</code>. For
- more information, look at the configuration options document
-<a href=http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html>here</a>
-</p>
-
-
-<h3 class="left"><a name="mem">Tips for memory leak hunting</a></h3>
-
-<p>There are various third party memory tracing and debug utilities
- that can be used to provide detailed memory allocation information
- about C++ code. An exhaustive list of tools is not going to be
- attempted, but include <code>mtrace</code>, <code>valgrind</code>,
- <code>mudflap</code>, and <code>purify</code>. Also highly
- recommended are <code>libcwd</code> and some other one that I
- forget right now.
-</p>
-
-<p>Regardless of the memory debugging tool being used, there is one
- thing of great importance to keep in mind when debugging C++ code
- that uses <code>new</code> and <code>delete</code>:
- there are different kinds of allocation schemes that can be used by
- <code> std::allocator </code>. For implementation details, see this
- <a href=http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3>
- document </a> and look specifically for <code>GLIBCPP_FORCE_NEW</code>.
-</p>
-
-<p>In a nutshell, the default allocator used by <code>
- std::allocator</code> is a high-performance pool allocator, and can
- give the mistaken impression that memory is being leaked, when in
- reality the memory is reclaimed after program termination.
-</p>
-
-<p>For valgrind, there are some specific items to keep in mind. First
- of all, use a version of valgrind that will work with current GNU
- C++ tools: the first that can do this is valgrind 1.0.4, but later
- versions should work at least as well. Second of all, use a
- completely unoptimized build to avoid confusing valgrind. Third,
- use GLIBCPP_FORCE_NEW to keep extraneous pool allocation noise from
- cluttering debug information.
-</p>
-
-<p>Fourth, it may be necessary to force deallocation in other
- libraries as well, namely the "C" library. On linux, this can be
- accomplished with the appropriate use of the
- <code>__cxa_atexit</code> or <code>atexit</code> functions.
-</p>
-
-<pre>
- #include <cstdlib>
-
- extern "C" void __libc_freeres(void);
-
- void do_something() { }
-
- int main()
- {
- atexit(__libc_freeres);
- do_something();
- return 0;
- }
-</pre>
-
-
-<p>or, using <code>__cxa_atexit</code>:</p>
-
-<pre>
- extern "C" void __libc_freeres(void);
- extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d);
-
- void do_something() { }
-
- int main()
- {
- extern void* __dso_handle __attribute__ ((__weak__));
- __cxa_atexit((void (*) (void *)) __libc_freeres, NULL,
- &__dso_handle ? __dso_handle : NULL);
- do_test();
- return 0;
- }
-</pre>
-
-<p>Suggested valgrind flags, given the suggestions above about setting
- up the runtime environment, library, and test file, might be:
-
- <dd><code>valgrind -v --num-callers=20 --leak-check=yes
- --leak-resolution=high --show-reachable=yes a.out</code></dd>
-</p>
-
-
-<h3 class="left"><a name="gdb">Some gdb strategies</a></h3>
-<p>Many options are available for gdb itself: please see <a
- href=http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC109>
- "GDB features for C++" </a> in the gdb documentation. Also
- recommended: the other parts of this manual.
-</p>
-
-<p>These settings can either be switched on in at the gdb command
- line, or put into a .gdbint file to establish default debugging
- characteristics, like so:
-</p>
-
-<pre>
- set print pretty on
- set print object on
- set print static-members on
- set print vtbl on
- set print demangle on
- set demangle-style gnu-v3
-</pre>
-
-
-<h3 class="left"><a name="verbterm">Tracking uncaught exceptions</a></h3>
-<p>The <a href="19_diagnostics/howto.html#4">verbose termination handler</a>
- gives information about uncaught exceptions which are killing the
- program. It is described in the linked-to page.
-</p>
-
-
-<p>Return <a href="#top">to the top of the page</a> or
- <a href="http://gcc.gnu.org/libstdc++/">to the libstdc++ homepage</a>.
-</p>
-
-
-<!-- ####################################################### -->
-
-<hr />
-<p class="fineprint"><em>
-See <a href="17_intro/license.html">license.html</a> for copying conditions.
-Comments and suggestions are welcome, and may be sent to
-<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
-</em></p>
-
-
-</body>
-</html>