This is the mail archive of the
gcc-patches@gcc.gnu.org
mailing list for the GCC project.
[v3] docs on debugging
- From: Benjamin Kosnik <bkoz at redhat dot com>
- To: gcc-patches at gcc dot gnu dot org
- Date: Thu, 19 Dec 2002 03:10:54 -0500 (EST)
- Subject: [v3] docs on debugging
This adds some preliminary information about debugging C++ code. Most
of this stuff has been discussed on the libstdc++ list, and represents
current thinking on optimal debugging. It needed to be presented in
one place.
This is an early form of this node, so I expect the information to
expand and evolve.
2002-12-18 Benjamin Kosnik <bkoz@redhat.com>
* docs/html/documentation.html: Add link for debug.html.
* docs/html/debug.html: New.
Index: docs/html/debug.html
===================================================================
RCS file: docs/html/debug.html
diff -N docs/html/debug.html
*** /dev/null 1 Jan 1970 00:00:00 -0000
--- docs/html/debug.html 19 Dec 2002 08:13:22 -0000
***************
*** 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>
Index: docs/html/documentation.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/documentation.html,v
retrieving revision 1.25
diff -c -p -r1.25 documentation.html
*** docs/html/documentation.html 21 Nov 2002 08:28:34 -0000 1.25
--- docs/html/documentation.html 19 Dec 2002 08:13:22 -0000
***************
*** 47,52 ****
--- 47,53 ----
<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>