OSDN Git Service

2003-03-12 Jonathan Wakely <redi@gcc.gnu.org>
[pf3gnuchains/gcc-fork.git] / libstdc++-v3 / docs / html / debug.html
1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html
3           PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4           "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
5
6 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
7 <head>
8    <meta name="AUTHOR" content="bkoz@gcc.gnu.org (Benjamin Kosnik)" />
9    <meta name="KEYWORDS" content="c++, libstdc++, gdb, g++, debug" />
10    <meta name="DESCRIPTION" content="Debugging C++ binaries" />
11    <meta name="GENERATOR" content="vi and ten fingers" />
12    <title>Debugging schemes and strategies</title>
13 <link rel="StyleSheet" href="lib3styles.css" />
14 </head>
15 <body>
16
17 <h1 class="centered"><a name="top">Debugging schemes and strategies</a></h1>
18
19 <p class="fineprint"><em>
20    The latest version of this document is always available at
21    <a href="http://gcc.gnu.org/onlinedocs/libstdc++/debug.html">
22    http://gcc.gnu.org/onlinedocs/libstdc++/debug.html</a>.
23 </em></p>
24
25 <p><em>
26    To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
27 </em></p>
28
29 <!-- ####################################################### -->
30 <hr />
31 <p>There are numerous things that can be done to improve the ease with
32    which C++ binaries are debugged when using the GNU C++
33    tool chain. Here are some things to keep in mind when debugging C++
34    code with GNU tools.
35 </p>
36
37 <h3 class="left"><a name="gplusplus">Compiler flags determine debug info</a></h3>
38 <p>The default optimizations and debug flags for a libstdc++ build are
39    <code>-g -O2</code>. However, both debug and optimization flags can
40    be varied to change debugging characteristics. For instance,
41    turning off all optimization via the <code>-g -O0</code> flag will
42    disable inlining, so that stepping through all functions, including
43    inlined constructors and destructors, is possible. Or, the debug
44    format that the compiler and debugger use to communicate
45    information about source constructs can be changed via <code>
46    -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.
49    The default debug information for a particular platform can be
50    identified via the value set by the PREFERRED_DEBUGGING_TYPE macro
51    in the gcc sources.
52 </p>
53
54 <p>Many other options are available: please see
55 <a href="http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options">"Options for Debugging Your Program"</a>
56    in Using the GNU Compiler Collection (GCC) for a complete list.
57 </p>
58
59
60 <h3 class="left"><a name="lib">Using special flags to make a debug binary</a></h3>
61 <p>There are two ways to build libstdc++ with debug flags. The first
62    is to run make from the toplevel in a freshly-configured tree with
63    specialized debug <code>CXXFLAGS</code>, as in
64 </p>
65 <pre>
66      make CXXFLAGS='-g3 -O0' all
67 </pre>
68
69 <p>This quick and dirty approach is often sufficient for quick
70    debugging tasks, but the lack of state can be confusing in the long
71    term.
72 </p>
73 <p>A second approach is to use the configuration flags 
74 </p>
75 <pre>
76      --enable-debug
77 </pre>
78 <p>and perhaps</p>
79 <pre>
80      --enable-debug-flags='...'
81 </pre>
82 <p>to create a separate debug build. Both the normal build and the
83    debug build will persist, without having to specify
84    <code>CXXFLAGS</code>, and the debug library will be installed in a
85    separate directory tree, in <code>(prefix)/lib/debug</code>. For
86    more information, look at the <a href="configopts.html">configuration
87    options</a> document.
88 </p>
89
90
91 <h3 class="left"><a name="mem">Tips for memory leak hunting</a></h3>
92
93 <p>There are various third party memory tracing and debug utilities
94    that can be used to provide detailed memory allocation information
95    about C++ code. An exhaustive list of tools is not going to be
96    attempted, but includes <code>mtrace</code>, <code>valgrind</code>,
97    <code>mudflap</code>, and <code>purify</code>. Also highly
98    recommended are <code>libcwd</code> and some other one that I
99    forget right now.
100 </p>
101
102 <p>Regardless of the memory debugging tool being used, there is one
103    thing of great importance to keep in mind when debugging C++ code
104    that uses <code>new</code> and <code>delete</code>:
105    there are different kinds of allocation schemes that can be used by
106    <code> std::allocator </code>. For implementation details, see this
107    <a href="ext/howto.html#3"> document</a> and look specifically for
108    <code>GLIBCPP_FORCE_NEW</code>. 
109 </p>
110
111 <p>In a nutshell, the default allocator used by <code>
112    std::allocator</code> is a high-performance pool allocator, and can
113    give the mistaken impression that memory is being leaked, when in
114    reality the memory is still being used by the library and is reclaimed
115    after program termination.
116 </p>
117
118 <p>For valgrind, there are some specific items to keep in mind. First
119    of all, use a version of valgrind that will work with current GNU
120    C++ tools: the first that can do this is valgrind 1.0.4, but later
121    versions should work at least as well. Second of all, use a
122    completely unoptimized build to avoid confusing valgrind. Third,
123    use GLIBCPP_FORCE_NEW to keep extraneous pool allocation noise from
124    cluttering debug information. 
125 </p>
126
127 <p>Fourth, it may be necessary to force deallocation in other
128    libraries as well, namely the "C" library. On linux, this can be
129    accomplished with the appropriate use of the
130    <code>__cxa_atexit</code> or <code>atexit</code> functions.
131 </p>
132
133 <pre>
134    #include &lt;cstdlib&gt;
135
136    extern "C" void __libc_freeres(void);
137
138    void do_something() { }
139
140    int main()
141    {
142      atexit(__libc_freeres);
143      do_something();
144      return 0;
145    }
146 </pre>
147
148
149 <p>or, using <code>__cxa_atexit</code>:</p>
150
151 <pre>
152    extern "C" void __libc_freeres(void);
153    extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d);
154
155    void do_something() { }
156
157    int main()
158    {
159       extern void* __dso_handle __attribute__ ((__weak__));
160       __cxa_atexit((void (*) (void *)) __libc_freeres, NULL, 
161                    &amp;__dso_handle ? __dso_handle : NULL);
162       do_test();
163       return 0;
164    }
165 </pre>
166
167 <p>Suggested valgrind flags, given the suggestions above about setting
168    up the runtime environment, library, and test file, might be:
169 </p>
170 <pre> 
171    valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out
172 </pre>
173
174
175 <h3 class="left"><a name="gdb">Some gdb strategies</a></h3>
176 <p>Many options are available for gdb itself: please see <a
177    href="http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC109">
178    "GDB features for C++" </a> in the gdb documentation. Also
179    recommended: the other parts of this manual.
180 </p>
181
182 <p>These settings can either be switched on in at the gdb command
183    line, or put into a .gdbint file to establish default debugging
184    characteristics, like so:
185 </p>
186
187 <pre>
188    set print pretty on
189    set print object on
190    set print static-members on
191    set print vtbl on
192    set print demangle on
193    set demangle-style gnu-v3
194 </pre>
195
196
197 <h3 class="left"><a name="verbterm">Tracking uncaught exceptions</a></h3>
198 <p>The <a href="19_diagnostics/howto.html#4">verbose termination handler</a>
199    gives information about uncaught exceptions which are killing the
200    program.  It is described in the linked-to page.
201 </p>
202
203
204 <p>Return <a href="#top">to the top of the page</a> or
205    <a href="http://gcc.gnu.org/libstdc++/">to the libstdc++ homepage</a>.
206 </p>
207
208
209 <!-- ####################################################### -->
210
211 <hr />
212 <p class="fineprint"><em>
213 See <a href="17_intro/license.html">license.html</a> for copying conditions.
214 Comments and suggestions are welcome, and may be sent to
215 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
216 </em></p>
217
218
219 </body>
220 </html>