OSDN Git Service

ff20d249c36025fc0d27f1521792a22ff70b2b37
[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 <p>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 </p>
24
25 <p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
26 </p>
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="g++">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 <dd> <code> make
64    CXXFLAGS='-g3 -O0' all </code></dd>
65 </p>
66
67 <p>This quick and dirty approach is often sufficient for quick
68    debugging tasks, but the lack of state can be confusing in the long
69    term.
70 </p>
71
72 <p>A second approach is to use the configuration flags 
73 </p>
74
75    <dd><code>--enable-debug</code></dd>
76
77 <p>and perhaps</p>
78
79    <dd><code>--enable-debug-flags='...'</code></dd>
80
81 <p>to create a separate debug build. Both the normal build and the
82    debug build will persist, without having to specify
83    <code>CXXFLAGS</code>, and the debug library will be installed in a
84    separate directory tree, in <code>(prefix)/lib/debug</code>. For
85    more information, look at the configuration options document 
86 <a href=http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html>here</a>
87 </p>
88
89
90 <h3 class="left"><a name="mem">Tips for memory leak hunting</a></h3>
91
92 <p>There are various third party memory tracing and debug utilities
93    that can be used to provide detailed memory allocation information
94    about C++ code. An exhaustive list of tools is not going to be
95    attempted, but include <code>mtrace</code>, <code>valgrind</code>,
96    <code>mudflap</code>, and <code>purify</code>. Also highly
97    recommended are <code>libcwd</code> and some other one that I
98    forget right now.
99 </p>
100
101 <p>Regardless of the memory debugging tool being used, there is one
102    thing of great importance to keep in mind when debugging C++ code
103    that uses <code>new</code> and <code>delete</code>:
104    there are different kinds of allocation schemes that can be used by
105    <code> std::allocator </code>. For implementation details, see this
106    <a href=http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3>
107    document </a> and look specifically for <code>GLIBCPP_FORCE_NEW</code>. 
108 </p>
109
110 <p>In a nutshell, the default allocator used by <code>
111    std::allocator</code> is a high-performance pool allocator, and can
112    give the mistaken impression that memory is being leaked, when in
113    reality the memory is reclaimed after program termination.
114 </p>
115
116 <p>For valgrind, there are some specific items to keep in mind. First
117    of all, use a version of valgrind that will work with current GNU
118    C++ tools: the first that can do this is valgrind 1.0.4, but later
119    versions should work at least as well. Second of all, use a
120    completely unoptimized build to avoid confusing valgrind. Third,
121    use GLIBCPP_FORCE_NEW to keep extraneous pool allocation noise from
122    cluttering debug information. 
123 </p>
124
125 <p>Fourth, it may be necessary to force deallocation in other
126    libraries as well, namely the "C" library. On linux, this can be
127    accomplished with the appropriate use of the
128    <code>__cxa_atexit</code> or <code>atexit</code> functions.
129 </p>
130
131 <pre>
132    #include &lt;cstdlib&gt;
133
134    extern "C" void __libc_freeres(void);
135
136    void do_something() { }
137
138    int main()
139    {
140      atexit(__libc_freeres);
141      do_something();
142      return 0;
143    }
144 </pre>
145
146
147 <p>or, using <code>__cxa_atexit</code>:</p>
148
149 <pre>
150    extern "C" void __libc_freeres(void);
151    extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d);
152
153    void do_something() { }
154
155    int main()
156    {
157       extern void* __dso_handle __attribute__ ((__weak__));
158       __cxa_atexit((void (*) (void *)) __libc_freeres, NULL, 
159                    &amp;__dso_handle ? __dso_handle : NULL);
160       do_test();
161       return 0;
162    }
163 </pre>
164
165 <p>Suggested valgrind flags, given the suggestions above about setting
166    up the runtime environment, library, and test file, might be:
167  
168    <dd><code>valgrind -v --num-callers=20 --leak-check=yes
169    --leak-resolution=high --show-reachable=yes a.out</code></dd>
170 </p>
171
172
173 <h3 class="left"><a name="gdb">Some gdb strategies</a></h3>
174 <p>Many options are available for gdb itself: please see <a
175    href=http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC109>
176    "GDB features for C++" </a> in the gdb documentation. Also
177    recommended: the other parts of this manual.
178 </p>
179
180 <p>These settings can either be switched on in at the gdb command
181    line, or put into a .gdbint file to establish default debugging
182    characteristics, like so:
183 </p>
184
185 <pre>
186    set print pretty on
187    set print object on
188    set print static-members on
189    set print vtbl on
190    set print demangle on
191    set demangle-style gnu-v3
192 </pre>
193
194
195 <h3 class="left"><a name="verbterm">Tracking uncaught exceptions</a></h3>
196 <p>The <a href="19_diagnostics/howto.html#4">verbose termination handler</a>
197    gives information about uncaught exceptions which are killing the
198    program.  It is described in the linked-to page.
199 </p>
200
201
202 <p>Return <a href="#top">to the top of the page</a> or
203    <a href="http://gcc.gnu.org/libstdc++/">to the libstdc++ homepage</a>.
204 </p>
205
206
207 <!-- ####################################################### -->
208
209 <hr />
210 <p class="fineprint"><em>
211 See <a href="17_intro/license.html">license.html</a> for copying conditions.
212 Comments and suggestions are welcome, and may be sent to
213 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
214 </em></p>
215
216
217 </body>
218 </html>