OSDN Git Service

2011-02-10 Jonathan Wakely <jwakely.gcc@gmail.com>
[pf3gnuchains/gcc-fork.git] / libstdc++-v3 / doc / xml / manual / debug.xml
1 <section xmlns="http://docbook.org/ns/docbook" version="5.0" 
2          xml:id="manual.intro.using.debug" xreflabel="Debugging Support">
3 <?dbhtml filename="debug.html"?>
4
5 <info><title>Debugging Support</title>
6   <keywordset>
7     <keyword>
8       C++
9     </keyword>
10     <keyword>
11       debug
12     </keyword>
13   </keywordset>
14 </info>
15
16
17
18 <para>
19   There are numerous things that can be done to improve the ease with
20   which C++ binaries are debugged when using the GNU tool chain. Here
21   are some of them.
22 </para>
23
24 <section xml:id="debug.compiler"><info><title>Using <command>g++</command></title></info>
25
26   <para>
27     Compiler flags determine how debug information is transmitted
28     between compilation and debug or analysis tools.
29   </para>
30
31   <para>
32     The default optimizations and debug flags for a libstdc++ build
33     are <code>-g -O2</code>. However, both debug and optimization
34     flags can be varied to change debugging characteristics. For
35     instance, turning off all optimization via the <code>-g -O0
36     -fno-inline</code> flags will disable inlining and optimizations,
37     and add debugging information, so that stepping through all functions,
38     (including inlined constructors and destructors) is possible. In
39     addition, <code>-fno-eliminate-unused-debug-types</code> can be
40     used when additional debug information, such as nested class info,
41     is desired.
42 </para>
43
44 <para>
45   Or, the debug format that the compiler and debugger use to
46   communicate information about source constructs can be changed via
47   <code>-gdwarf-2</code> or <code>-gstabs</code> flags: some debugging
48   formats permit more expressive type and scope information to be
49   shown in GDB. Expressiveness can be enhanced by flags like
50   <code>-g3</code>. The default debug information for a particular
51   platform can be identified via the value set by the
52   PREFERRED_DEBUGGING_TYPE macro in the gcc sources.
53 </para>
54
55 <para>
56   Many other options are available: please see <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options">"Options
57   for Debugging Your Program"</link> in Using the GNU Compiler
58   Collection (GCC) for a complete list.
59 </para>
60 </section>
61
62 <section xml:id="debug.req"><info><title>Debug Versions of Library Binary Files</title></info>
63
64
65 <para>
66   If you would like debug symbols in libstdc++, there are two ways to
67   build libstdc++ with debug flags. The first is to run make from the
68   toplevel in a freshly-configured tree with
69 </para>
70 <programlisting>
71      --enable-libstdcxx-debug
72 </programlisting>
73 <para>and perhaps</para>
74 <programlisting>
75      --enable-libstdcxx-debug-flags='...'
76 </programlisting>
77 <para>
78   to create a separate debug build. Both the normal build and the
79   debug build will persist, without having to specify
80   <code>CXXFLAGS</code>, and the debug library will be installed in a
81   separate directory tree, in <code>(prefix)/lib/debug</code>. For
82   more information, look at the <link linkend="manual.intro.setup.configure">configuration</link> section.
83 </para>
84
85 <para>
86   A second approach is to use the configuration flags
87 </para>
88 <programlisting>
89      make CXXFLAGS='-g3 -fno-inline -O0' all
90 </programlisting>
91
92 <para>
93   This quick and dirty approach is often sufficient for quick
94   debugging tasks, when you cannot or don't want to recompile your
95   application to use the <link linkend="manual.ext.debug_mode">debug mode</link>.</para>
96 </section>
97
98 <section xml:id="debug.memory"><info><title>Memory Leak Hunting</title></info>
99
100
101 <para>
102   There are various third party memory tracing and debug utilities
103   that can be used to provide detailed memory allocation information
104   about C++ code. An exhaustive list of tools is not going to be
105   attempted, but includes <code>mtrace</code>, <code>valgrind</code>,
106   <code>mudflap</code>, and the non-free commercial product
107   <code>purify</code>. In addition, <code>libcwd</code> has a
108   replacement for the global new and delete operators that can track
109   memory allocation and deallocation and provide useful memory
110   statistics.
111 </para>
112
113 <para>
114   Regardless of the memory debugging tool being used, there is one
115   thing of great importance to keep in mind when debugging C++ code
116   that uses <code>new</code> and <code>delete</code>: there are
117   different kinds of allocation schemes that can be used by <code>
118   std::allocator </code>. For implementation details, see the <link linkend="manual.ext.allocator.mt">mt allocator</link> documentation and
119   look specifically for <code>GLIBCXX_FORCE_NEW</code>.
120 </para>
121
122 <para>
123   In a nutshell, the default allocator used by <code>
124   std::allocator</code> is a high-performance pool allocator, and can
125   give the mistaken impression that in a suspect executable, memory is
126   being leaked, when in reality the memory "leak" is a pool being used
127   by the library's allocator and is reclaimed after program
128   termination.
129 </para>
130
131 <para>
132   For valgrind, there are some specific items to keep in mind. First
133   of all, use a version of valgrind that will work with current GNU
134   C++ tools: the first that can do this is valgrind 1.0.4, but later
135   versions should work at least as well. Second of all, use a
136   completely unoptimized build to avoid confusing valgrind. Third, use
137   GLIBCXX_FORCE_NEW to keep extraneous pool allocation noise from
138   cluttering debug information.
139 </para>
140
141 <para>
142   Fourth, it may be necessary to force deallocation in other libraries
143   as well, namely the "C" library. On linux, this can be accomplished
144   with the appropriate use of the <code>__cxa_atexit</code> or
145   <code>atexit</code> functions.
146 </para>
147
148 <programlisting>
149    #include &lt;cstdlib&gt;
150
151    extern "C" void __libc_freeres(void);
152
153    void do_something() { }
154
155    int main()
156    {
157      atexit(__libc_freeres);
158      do_something();
159      return 0;
160    }
161 </programlisting>
162
163
164 <para>or, using <code>__cxa_atexit</code>:</para>
165
166 <programlisting>
167    extern "C" void __libc_freeres(void);
168    extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d);
169
170    void do_something() { }
171
172    int main()
173    {
174       extern void* __dso_handle __attribute__ ((__weak__));
175       __cxa_atexit((void (*) (void *)) __libc_freeres, NULL,
176                    &amp;__dso_handle ? __dso_handle : NULL);
177       do_test();
178       return 0;
179    }
180 </programlisting>
181
182 <para>
183   Suggested valgrind flags, given the suggestions above about setting
184   up the runtime environment, library, and test file, might be:
185 </para>
186 <programlisting>
187    valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out
188 </programlisting>
189
190 </section>
191
192 <section xml:id="debug.races"><info><title>Data Race Hunting</title></info>
193 <para>
194   All synchronization primitives used in the library internals need to be
195   understood by race detectors so that they do not produce false reports.
196 </para>
197
198 <para>
199   Two annotation macros are used to explain low-level synchronization 
200   to race detectors:
201   <code>_GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE()</code> and
202   <code> _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER()</code>.
203   By default, these macros are defined empty -- anyone who wants
204   to use a race detector needs to redefine them to call an
205   appropriate API.
206   Since these macros are empty by default when the library is built,
207   redefining them will only affect inline functions and template
208   instantiations which are compiled in user code. This allows annotation
209   of templates such as <code>shared_ptr</code>, but not code which is
210   only instantiated in the library.
211   In order to annotate <code>basic_string</code> reference counting it
212   is necessary to disable extern templates (by defining 
213   <code>_GLIBCXX_EXTERN_TEMPLATE=-1</code>) or to rebuild the 
214   <code>.so</code> file.
215   Annotating the remaining atomic operations (at the time of writing these
216   are in <code>ios_base::Init::~Init</code>, <code>locale::_Impl</code> and
217   <code>locale::facet</code>) requires rebuilding the <code>.so</code> file.
218 </para>
219
220 <para>
221   The approach described above is known to work with the following race
222   detection tools:
223   <link xmlns:xlink="http://www.w3.org/1999/xlink" 
224   xlink:href="http://valgrind.org/docs/manual/drd-manual.html">
225   DRD</link>,
226   <link xmlns:xlink="http://www.w3.org/1999/xlink" 
227   xlink:href="http://valgrind.org/docs/manual/hg-manual.html"> 
228   Helgrind</link>, and
229   <link xmlns:xlink="http://www.w3.org/1999/xlink" 
230   xlink:href="http://code.google.com/p/data-race-test"> 
231   ThreadSanitizer</link>.
232 </para>
233
234 <para>
235   With DRD, Helgrind and ThreadSanitizer you will need to define
236   the macros like this:
237 <programlisting>
238   #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE(A) ANNOTATE_HAPPENS_BEFORE(A)
239   #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER(A)  ANNOTATE_HAPPENS_AFTER(A)
240 </programlisting>
241   Refer to the documentation of each particular tool for details.
242 </para>
243
244 </section>
245
246 <section xml:id="debug.gdb"><info><title>Using <command>gdb</command></title></info>
247
248   <para>
249   </para>
250
251 <para>
252   Many options are available for GDB itself: please see <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://sources.redhat.com/gdb/current/onlinedocs/gdb/">
253   "GDB features for C++" </link> in the GDB documentation. Also
254   recommended: the other parts of this manual.
255 </para>
256
257 <para>
258   These settings can either be switched on in at the GDB command line,
259   or put into a .gdbint file to establish default debugging
260   characteristics, like so:
261 </para>
262
263 <programlisting>
264    set print pretty on
265    set print object on
266    set print static-members on
267    set print vtbl on
268    set print demangle on
269    set demangle-style gnu-v3
270 </programlisting>
271
272 <para>
273   Starting with version 7.0, GDB includes support for writing
274   pretty-printers in Python.  Pretty printers for STL classes are
275   distributed with GCC from version 4.5.0.  The most recent version of
276   these printers are always found in libstdc++ svn repository.
277   To enable these printers, check-out the latest printers to a local
278   directory:
279 </para>
280
281 <programlisting>
282   svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python
283 </programlisting>
284
285 <para>
286   Next, add the following section to your ~/.gdbinit  The path must
287   match the location where the Python module above was checked-out.
288   So if checked out to: /home/maude/gdb_printers/, the path would be as
289   written in the example below.
290 </para>
291
292 <programlisting>
293   python
294   import sys
295   sys.path.insert(0, '/home/maude/gdb_printers/python')
296   from libstdcxx.v6.printers import register_libstdcxx_printers
297   register_libstdcxx_printers (None)
298   end
299 </programlisting>
300
301 <para>
302   The path should be the only element that needs to be adjusted in the
303   example.  Once loaded, STL classes that the printers support
304   should print in a more human-readable format.  To print the classes
305   in the old style, use the /r (raw) switch in the print command
306   (i.e., print /r foo).  This will print the classes as if the Python
307   pretty-printers were not loaded.
308 </para>
309
310 <para>
311   For additional information on STL support and GDB please visit:
312   <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://sourceware.org/gdb/wiki/STLSupport"> "GDB Support
313   for STL" </link> in the GDB wiki.  Additionally, in-depth
314   documentation and discussion of the pretty printing feature can be
315   found in "Pretty Printing" node in the GDB manual.  You can find
316   on-line versions of the GDB user manual in GDB's homepage, at
317   <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://sourceware.org/gdb/"> "GDB: The GNU Project
318   Debugger" </link>.
319 </para>
320
321 </section>
322
323 <section xml:id="debug.exceptions"><info><title>Tracking uncaught exceptions</title></info>
324
325 <para>
326   The <link linkend="support.termination.verbose">verbose
327   termination handler</link> gives information about uncaught
328   exceptions which are killing the program.  It is described in the
329   linked-to page.
330 </para>
331 </section>
332
333 <section xml:id="debug.debug_mode"><info><title>Debug Mode</title></info>
334
335   <para> The <link linkend="manual.ext.debug_mode">Debug Mode</link>
336   has compile and run-time checks for many containers.
337   </para>
338 </section>
339
340 <section xml:id="debug.compile_time_checks"><info><title>Compile Time Checking</title></info>
341
342   <para> The <link linkend="manual.ext.compile_checks">Compile-Time
343   Checks</link> Extension has compile-time checks for many algorithms.
344   </para>
345 </section>
346
347 <section xml:id="debug.profile_mode" xreflabel="debug.profile_mode"><info><title>Profile-based Performance Analysis</title></info>
348
349   <para> The <link linkend="manual.ext.profile_mode">Profile-based
350   Performance Analysis</link> Extension has performance checks for many
351   algorithms.
352   </para>
353 </section>
354
355 </section>