diff options
| -rw-r--r-- | libstdc++-v3/ChangeLog | 18 | ||||
| -rw-r--r-- | libstdc++-v3/docs/html/debug.html | 228 | ||||
| -rw-r--r-- | libstdc++-v3/docs/html/documentation.html | 1 |
3 files changed, 242 insertions, 5 deletions
diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 34d072e0950..9378d5e7120 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,8 @@ +2002-12-18 Benjamin Kosnik <bkoz@redhat.com> + + * docs/html/documentation.html: Add link for debug.html. + * docs/html/debug.html: New. + 2002-12-18 Kaveh R. Ghazi <ghazi@caip.rutgers.edu> * testsuite/23_containers/vector_capacity.cc (test03): Move ... @@ -189,14 +194,17 @@ const unsigned char*)): Fully qualify min() with std::. * include/bits/stl_bvector.h (_M_insert_range(iterator, _ForwardIterator, _ForwardIterator, forward_iterator_tag), - _M_assign_aux(_ForwardIterator, _ForwardIterator, forward_iterator_tag), + _M_assign_aux(_ForwardIterator, _ForwardIterator, + forward_iterator_tag), _M_initialize_range(_ForwardIterator, _ForwardIterator, forward_iterator_tag), _M_fill_insert(iterator, size_type, bool)): Fully qualify distance() and max() with std::. - * include/bits/stl_deque.h (_Deque_base::_M_initialize_map(size_t), - _M_assign_aux(_ForwardIterator, _ForwardIterator, forward_iterator_tag)): - Ditto. - * include/bits/stl_list.h (size()): Fully qualify distance() with std::. + * include/bits/stl_deque.h + (_Deque_base::_M_initialize_map(size_t), + _M_assign_aux(_ForwardIterator, _ForwardIterator, + forward_iterator_tag)): + Ditto. * include/bits/stl_list.h (size()): Fully qualify + distance() with std::. * include/bits/stl_tempbuf.h (_Temporary_buffer::_Temporary_buffer (_ForwardIterator, _ForwardIterator)): Ditto. * include/bits/stl_tree.h (_Rb_tree::erase(const _Key&), diff --git a/libstdc++-v3/docs/html/debug.html b/libstdc++-v3/docs/html/debug.html new file mode 100644 index 00000000000..73d592ffc25 --- /dev/null +++ b/libstdc++-v3/docs/html/debug.html @@ -0,0 +1,228 @@ +<?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_test(); + 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> + + +<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> diff --git a/libstdc++-v3/docs/html/documentation.html b/libstdc++-v3/docs/html/documentation.html index 0dc25bedfa0..d805c66ea9e 100644 --- a/libstdc++-v3/docs/html/documentation.html +++ b/libstdc++-v3/docs/html/documentation.html @@ -47,6 +47,7 @@ <ul> <li><a href="configopts.html">Configure options</a></li> <li><a href="install.html">Getting started: configure, build, install</a> + <li><a href="debug.html">Debugging schemes and strategies</a> </li> </ul> |