1 |
742 |
jeremybenn |
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
2 |
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
3 |
|
|
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Debugging Support</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"/><meta name="keywords" content=" C++ , debug "/><meta name="keywords" content=" ISO C++ , library "/><meta name="keywords" content=" ISO C++ , runtime , library "/><link rel="home" href="../index.html" title="The GNU C++ Library"/><link rel="up" href="using.html" title="Chapter 3. Using"/><link rel="prev" href="using_exceptions.html" title="Exceptions"/><link rel="next" href="bk01pt02.html" title="Part II. Standard Contents"/></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Debugging Support</th></tr><tr><td align="left"><a accesskey="p" href="using_exceptions.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td align="right"> <a accesskey="n" href="bk01pt02.html">Next</a></td></tr></table><hr/></div><div class="section" title="Debugging Support"><div class="titlepage"><div><div><h2 class="title"><a id="manual.intro.using.debug"/>Debugging Support</h2></div></div></div><p>
|
4 |
|
|
There are numerous things that can be done to improve the ease with
|
5 |
|
|
which C++ binaries are debugged when using the GNU tool chain. Here
|
6 |
|
|
are some of them.
|
7 |
|
|
</p><div class="section" title="Using g++"><div class="titlepage"><div><div><h3 class="title"><a id="debug.compiler"/>Using <span class="command"><strong>g++</strong></span></h3></div></div></div><p>
|
8 |
|
|
Compiler flags determine how debug information is transmitted
|
9 |
|
|
between compilation and debug or analysis tools.
|
10 |
|
|
</p><p>
|
11 |
|
|
The default optimizations and debug flags for a libstdc++ build
|
12 |
|
|
are <code class="code">-g -O2</code>. However, both debug and optimization
|
13 |
|
|
flags can be varied to change debugging characteristics. For
|
14 |
|
|
instance, turning off all optimization via the <code class="code">-g -O0
|
15 |
|
|
-fno-inline</code> flags will disable inlining and optimizations,
|
16 |
|
|
and add debugging information, so that stepping through all functions,
|
17 |
|
|
(including inlined constructors and destructors) is possible. In
|
18 |
|
|
addition, <code class="code">-fno-eliminate-unused-debug-types</code> can be
|
19 |
|
|
used when additional debug information, such as nested class info,
|
20 |
|
|
is desired.
|
21 |
|
|
</p><p>
|
22 |
|
|
Or, the debug format that the compiler and debugger use to
|
23 |
|
|
communicate information about source constructs can be changed via
|
24 |
|
|
<code class="code">-gdwarf-2</code> or <code class="code">-gstabs</code> flags: some debugging
|
25 |
|
|
formats permit more expressive type and scope information to be
|
26 |
|
|
shown in GDB. Expressiveness can be enhanced by flags like
|
27 |
|
|
<code class="code">-g3</code>. The default debug information for a particular
|
28 |
|
|
platform can be identified via the value set by the
|
29 |
|
|
PREFERRED_DEBUGGING_TYPE macro in the gcc sources.
|
30 |
|
|
</p><p>
|
31 |
|
|
Many other options are available: please see <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options">"Options
|
32 |
|
|
for Debugging Your Program"</a> in Using the GNU Compiler
|
33 |
|
|
Collection (GCC) for a complete list.
|
34 |
|
|
</p></div><div class="section" title="Debug Versions of Library Binary Files"><div class="titlepage"><div><div><h3 class="title"><a id="debug.req"/>Debug Versions of Library Binary Files</h3></div></div></div><p>
|
35 |
|
|
If you would like debug symbols in libstdc++, there are two ways to
|
36 |
|
|
build libstdc++ with debug flags. The first is to run make from the
|
37 |
|
|
toplevel in a freshly-configured tree with
|
38 |
|
|
</p><pre class="programlisting">
|
39 |
|
|
--enable-libstdcxx-debug
|
40 |
|
|
</pre><p>and perhaps</p><pre class="programlisting">
|
41 |
|
|
--enable-libstdcxx-debug-flags='...'
|
42 |
|
|
</pre><p>
|
43 |
|
|
to create a separate debug build. Both the normal build and the
|
44 |
|
|
debug build will persist, without having to specify
|
45 |
|
|
<code class="code">CXXFLAGS</code>, and the debug library will be installed in a
|
46 |
|
|
separate directory tree, in <code class="code">(prefix)/lib/debug</code>. For
|
47 |
|
|
more information, look at the <a class="link" href="configure.html" title="Configure">configuration</a> section.
|
48 |
|
|
</p><p>
|
49 |
|
|
A second approach is to use the configuration flags
|
50 |
|
|
</p><pre class="programlisting">
|
51 |
|
|
make CXXFLAGS='-g3 -fno-inline -O0' all
|
52 |
|
|
</pre><p>
|
53 |
|
|
This quick and dirty approach is often sufficient for quick
|
54 |
|
|
debugging tasks, when you cannot or don't want to recompile your
|
55 |
|
|
application to use the <a class="link" href="debug_mode.html" title="Chapter 17. Debug Mode">debug mode</a>.</p></div><div class="section" title="Memory Leak Hunting"><div class="titlepage"><div><div><h3 class="title"><a id="debug.memory"/>Memory Leak Hunting</h3></div></div></div><p>
|
56 |
|
|
There are various third party memory tracing and debug utilities
|
57 |
|
|
that can be used to provide detailed memory allocation information
|
58 |
|
|
about C++ code. An exhaustive list of tools is not going to be
|
59 |
|
|
attempted, but includes <code class="code">mtrace</code>, <code class="code">valgrind</code>,
|
60 |
|
|
<code class="code">mudflap</code>, and the non-free commercial product
|
61 |
|
|
<code class="code">purify</code>. In addition, <code class="code">libcwd</code> has a
|
62 |
|
|
replacement for the global new and delete operators that can track
|
63 |
|
|
memory allocation and deallocation and provide useful memory
|
64 |
|
|
statistics.
|
65 |
|
|
</p><p>
|
66 |
|
|
Regardless of the memory debugging tool being used, there is one
|
67 |
|
|
thing of great importance to keep in mind when debugging C++ code
|
68 |
|
|
that uses <code class="code">new</code> and <code class="code">delete</code>: there are
|
69 |
|
|
different kinds of allocation schemes that can be used by <code class="code">
|
70 |
|
|
std::allocator </code>. For implementation details, see the <a class="link" href="mt_allocator.html" title="Chapter 20. The mt_allocator">mt allocator</a> documentation and
|
71 |
|
|
look specifically for <code class="code">GLIBCXX_FORCE_NEW</code>.
|
72 |
|
|
</p><p>
|
73 |
|
|
In a nutshell, the default allocator used by <code class="code">
|
74 |
|
|
std::allocator</code> is a high-performance pool allocator, and can
|
75 |
|
|
give the mistaken impression that in a suspect executable, memory is
|
76 |
|
|
being leaked, when in reality the memory "leak" is a pool being used
|
77 |
|
|
by the library's allocator and is reclaimed after program
|
78 |
|
|
termination.
|
79 |
|
|
</p><p>
|
80 |
|
|
For valgrind, there are some specific items to keep in mind. First
|
81 |
|
|
of all, use a version of valgrind that will work with current GNU
|
82 |
|
|
C++ tools: the first that can do this is valgrind 1.0.4, but later
|
83 |
|
|
versions should work at least as well. Second of all, use a
|
84 |
|
|
completely unoptimized build to avoid confusing valgrind. Third, use
|
85 |
|
|
GLIBCXX_FORCE_NEW to keep extraneous pool allocation noise from
|
86 |
|
|
cluttering debug information.
|
87 |
|
|
</p><p>
|
88 |
|
|
Fourth, it may be necessary to force deallocation in other libraries
|
89 |
|
|
as well, namely the "C" library. On linux, this can be accomplished
|
90 |
|
|
with the appropriate use of the <code class="code">__cxa_atexit</code> or
|
91 |
|
|
<code class="code">atexit</code> functions.
|
92 |
|
|
</p><pre class="programlisting">
|
93 |
|
|
#include <cstdlib>
|
94 |
|
|
|
95 |
|
|
extern "C" void __libc_freeres(void);
|
96 |
|
|
|
97 |
|
|
void do_something() { }
|
98 |
|
|
|
99 |
|
|
int main()
|
100 |
|
|
{
|
101 |
|
|
atexit(__libc_freeres);
|
102 |
|
|
do_something();
|
103 |
|
|
return 0;
|
104 |
|
|
}
|
105 |
|
|
</pre><p>or, using <code class="code">__cxa_atexit</code>:</p><pre class="programlisting">
|
106 |
|
|
extern "C" void __libc_freeres(void);
|
107 |
|
|
extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d);
|
108 |
|
|
|
109 |
|
|
void do_something() { }
|
110 |
|
|
|
111 |
|
|
int main()
|
112 |
|
|
{
|
113 |
|
|
extern void* __dso_handle __attribute__ ((__weak__));
|
114 |
|
|
__cxa_atexit((void (*) (void *)) __libc_freeres, NULL,
|
115 |
|
|
&__dso_handle ? __dso_handle : NULL);
|
116 |
|
|
do_test();
|
117 |
|
|
return 0;
|
118 |
|
|
}
|
119 |
|
|
</pre><p>
|
120 |
|
|
Suggested valgrind flags, given the suggestions above about setting
|
121 |
|
|
up the runtime environment, library, and test file, might be:
|
122 |
|
|
</p><pre class="programlisting">
|
123 |
|
|
valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out
|
124 |
|
|
</pre></div><div class="section" title="Data Race Hunting"><div class="titlepage"><div><div><h3 class="title"><a id="debug.races"/>Data Race Hunting</h3></div></div></div><p>
|
125 |
|
|
All synchronization primitives used in the library internals need to be
|
126 |
|
|
understood by race detectors so that they do not produce false reports.
|
127 |
|
|
</p><p>
|
128 |
|
|
Two annotation macros are used to explain low-level synchronization
|
129 |
|
|
to race detectors:
|
130 |
|
|
<code class="code">_GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE()</code> and
|
131 |
|
|
<code class="code"> _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER()</code>.
|
132 |
|
|
By default, these macros are defined empty -- anyone who wants
|
133 |
|
|
to use a race detector needs to redefine them to call an
|
134 |
|
|
appropriate API.
|
135 |
|
|
Since these macros are empty by default when the library is built,
|
136 |
|
|
redefining them will only affect inline functions and template
|
137 |
|
|
instantiations which are compiled in user code. This allows annotation
|
138 |
|
|
of templates such as <code class="code">shared_ptr</code>, but not code which is
|
139 |
|
|
only instantiated in the library. Code which is only instantiated in
|
140 |
|
|
the library needs to be recompiled with the annotation macros defined.
|
141 |
|
|
That can be done by rebuilding the entire
|
142 |
|
|
<code class="filename">libstdc++.so</code> file but a simpler
|
143 |
|
|
alternative exists for ELF platforms such as GNU/Linux, because ELF
|
144 |
|
|
symbol interposition allows symbols defined in the shared library to be
|
145 |
|
|
overridden by symbols with the same name that appear earlier in the
|
146 |
|
|
runtime search path. This means you only need to recompile the functions
|
147 |
|
|
that are affected by the annotation macros, which can be done by
|
148 |
|
|
recompiling individual files.
|
149 |
|
|
Annotating <code class="code">std::string</code> and <code class="code">std::wstring</code>
|
150 |
|
|
reference counting can be done by disabling extern templates (by defining
|
151 |
|
|
<code class="code">_GLIBCXX_EXTERN_TEMPLATE=-1</code>) or by rebuilding the
|
152 |
|
|
<code class="filename">src/string-inst.cc</code> file.
|
153 |
|
|
Annotating the remaining atomic operations (at the time of writing these
|
154 |
|
|
are in <code class="code">ios_base::Init::~Init</code>, <code class="code">locale::_Impl</code>,
|
155 |
|
|
<code class="code">locale::facet</code> and <code class="code">thread::_M_start_thread</code>)
|
156 |
|
|
requires rebuilding the relevant source files.
|
157 |
|
|
</p><p>
|
158 |
|
|
The approach described above is known to work with the following race
|
159 |
|
|
detection tools:
|
160 |
|
|
<a class="link" href="http://valgrind.org/docs/manual/drd-manual.html">
|
161 |
|
|
DRD</a>,
|
162 |
|
|
<a class="link" href="http://valgrind.org/docs/manual/hg-manual.html">
|
163 |
|
|
Helgrind</a>, and
|
164 |
|
|
<a class="link" href="http://code.google.com/p/data-race-test">
|
165 |
|
|
ThreadSanitizer</a>.
|
166 |
|
|
</p><p>
|
167 |
|
|
With DRD, Helgrind and ThreadSanitizer you will need to define
|
168 |
|
|
the macros like this:
|
169 |
|
|
</p><pre class="programlisting">
|
170 |
|
|
#define _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE(A) ANNOTATE_HAPPENS_BEFORE(A)
|
171 |
|
|
#define _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER(A) ANNOTATE_HAPPENS_AFTER(A)
|
172 |
|
|
</pre><p>
|
173 |
|
|
Refer to the documentation of each particular tool for details.
|
174 |
|
|
</p></div><div class="section" title="Using gdb"><div class="titlepage"><div><div><h3 class="title"><a id="debug.gdb"/>Using <span class="command"><strong>gdb</strong></span></h3></div></div></div><p>
|
175 |
|
|
</p><p>
|
176 |
|
|
Many options are available for GDB itself: please see <a class="link" href="http://sources.redhat.com/gdb/current/onlinedocs/gdb/">
|
177 |
|
|
"GDB features for C++" </a> in the GDB documentation. Also
|
178 |
|
|
recommended: the other parts of this manual.
|
179 |
|
|
</p><p>
|
180 |
|
|
These settings can either be switched on in at the GDB command line,
|
181 |
|
|
or put into a .gdbint file to establish default debugging
|
182 |
|
|
characteristics, like so:
|
183 |
|
|
</p><pre class="programlisting">
|
184 |
|
|
set print pretty on
|
185 |
|
|
set print object on
|
186 |
|
|
set print static-members on
|
187 |
|
|
set print vtbl on
|
188 |
|
|
set print demangle on
|
189 |
|
|
set demangle-style gnu-v3
|
190 |
|
|
</pre><p>
|
191 |
|
|
Starting with version 7.0, GDB includes support for writing
|
192 |
|
|
pretty-printers in Python. Pretty printers for STL classes are
|
193 |
|
|
distributed with GCC from version 4.5.0. The most recent version of
|
194 |
|
|
these printers are always found in libstdc++ svn repository.
|
195 |
|
|
To enable these printers, check-out the latest printers to a local
|
196 |
|
|
directory:
|
197 |
|
|
</p><pre class="programlisting">
|
198 |
|
|
svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python
|
199 |
|
|
</pre><p>
|
200 |
|
|
Next, add the following section to your ~/.gdbinit The path must
|
201 |
|
|
match the location where the Python module above was checked-out.
|
202 |
|
|
So if checked out to: /home/maude/gdb_printers/, the path would be as
|
203 |
|
|
written in the example below.
|
204 |
|
|
</p><pre class="programlisting">
|
205 |
|
|
python
|
206 |
|
|
import sys
|
207 |
|
|
sys.path.insert(0, '/home/maude/gdb_printers/python')
|
208 |
|
|
from libstdcxx.v6.printers import register_libstdcxx_printers
|
209 |
|
|
register_libstdcxx_printers (None)
|
210 |
|
|
end
|
211 |
|
|
</pre><p>
|
212 |
|
|
The path should be the only element that needs to be adjusted in the
|
213 |
|
|
example. Once loaded, STL classes that the printers support
|
214 |
|
|
should print in a more human-readable format. To print the classes
|
215 |
|
|
in the old style, use the /r (raw) switch in the print command
|
216 |
|
|
(i.e., print /r foo). This will print the classes as if the Python
|
217 |
|
|
pretty-printers were not loaded.
|
218 |
|
|
</p><p>
|
219 |
|
|
For additional information on STL support and GDB please visit:
|
220 |
|
|
<a class="link" href="http://sourceware.org/gdb/wiki/STLSupport"> "GDB Support
|
221 |
|
|
for STL" </a> in the GDB wiki. Additionally, in-depth
|
222 |
|
|
documentation and discussion of the pretty printing feature can be
|
223 |
|
|
found in "Pretty Printing" node in the GDB manual. You can find
|
224 |
|
|
on-line versions of the GDB user manual in GDB's homepage, at
|
225 |
|
|
<a class="link" href="http://sourceware.org/gdb/"> "GDB: The GNU Project
|
226 |
|
|
Debugger" </a>.
|
227 |
|
|
</p></div><div class="section" title="Tracking uncaught exceptions"><div class="titlepage"><div><div><h3 class="title"><a id="debug.exceptions"/>Tracking uncaught exceptions</h3></div></div></div><p>
|
228 |
|
|
The <a class="link" href="termination.html#support.termination.verbose" title="Verbose Terminate Handler">verbose
|
229 |
|
|
termination handler</a> gives information about uncaught
|
230 |
|
|
exceptions which are killing the program. It is described in the
|
231 |
|
|
linked-to page.
|
232 |
|
|
</p></div><div class="section" title="Debug Mode"><div class="titlepage"><div><div><h3 class="title"><a id="debug.debug_mode"/>Debug Mode</h3></div></div></div><p> The <a class="link" href="debug_mode.html" title="Chapter 17. Debug Mode">Debug Mode</a>
|
233 |
|
|
has compile and run-time checks for many containers.
|
234 |
|
|
</p></div><div class="section" title="Compile Time Checking"><div class="titlepage"><div><div><h3 class="title"><a id="debug.compile_time_checks"/>Compile Time Checking</h3></div></div></div><p> The <a class="link" href="ext_compile_checks.html" title="Chapter 16. Compile Time Checks">Compile-Time
|
235 |
|
|
Checks</a> Extension has compile-time checks for many algorithms.
|
236 |
|
|
</p></div><div class="section" title="Profile-based Performance Analysis"><div class="titlepage"><div><div><h3 class="title"><a id="debug.profile_mode"/>Profile-based Performance Analysis</h3></div></div></div><p> The <a class="link" href="profile_mode.html" title="Chapter 19. Profile Mode">Profile-based
|
237 |
|
|
Performance Analysis</a> Extension has performance checks for many
|
238 |
|
|
algorithms.
|
239 |
|
|
</p></div></div><div class="navfooter"><hr/><table width="100%" summary="Navigation footer"><tr><td align="left"><a accesskey="p" href="using_exceptions.html">Prev</a> </td><td align="center"><a accesskey="u" href="using.html">Up</a></td><td align="right"> <a accesskey="n" href="bk01pt02.html">Next</a></td></tr><tr><td align="left" valign="top">Exceptions </td><td align="center"><a accesskey="h" href="../index.html">Home</a></td><td align="right" valign="top"> Part II.
|
240 |
|
|
Standard Contents
|
241 |
|
|
</td></tr></table></div></body></html>
|