diff options
Diffstat (limited to 'libstdc++-v3/docs/html/debug.html')
| -rw-r--r-- | libstdc++-v3/docs/html/debug.html | 220 |
1 files changed, 220 insertions, 0 deletions
diff --git a/libstdc++-v3/docs/html/debug.html b/libstdc++-v3/docs/html/debug.html new file mode 100644 index 00000000000..0ca332c7346 --- /dev/null +++ b/libstdc++-v3/docs/html/debug.html @@ -0,0 +1,220 @@ +<?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> + 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>. +</em></p> + +<p><em> + To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>. +</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="gplusplus">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 +</p> +<pre> + make CXXFLAGS='-g3 -O0' all +</pre> + +<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> +<pre> + --enable-debug +</pre> +<p>and perhaps</p> +<pre> + --enable-debug-flags='...' +</pre> +<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 <a href="configopts.html">configuration + options</a> document. +</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 includes <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="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 still being used by the library and 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: +</p> +<pre> + valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out +</pre> + + +<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> |