-<sect1 id="manual.intro.using.debug" xreflabel="Debugging Support">
+<section xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xml:id="manual.intro.using.debug" xreflabel="Debugging Support">
<?dbhtml filename="debug.html"?>
-<sect1info>
+<info><title>Debugging Support</title>
<keywordset>
<keyword>
C++
debug
</keyword>
</keywordset>
-</sect1info>
+</info>
+
-<title>Debugging Support</title>
<para>
There are numerous things that can be done to improve the ease with
are some of them.
</para>
-<sect2 id="debug.compiler">
-<title>Using <command>g++</command></title>
+<section xml:id="debug.compiler"><info><title>Using <command>g++</command></title></info>
+
<para>
Compiler flags determine how debug information is transmitted
between compilation and debug or analysis tools.
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. Expressiveness can be enhanced by flags like
+ shown in GDB. Expressiveness can be enhanced by flags like
<code>-g3</code>. 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.
</para>
<para>
- Many other options are available: please see <ulink
- url="http://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging%20Options">"Options
- for Debugging Your Program"</ulink> in Using the GNU Compiler
+ 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
+ for Debugging Your Program"</link> in Using the GNU Compiler
Collection (GCC) for a complete list.
</para>
-</sect2>
+</section>
+
+<section xml:id="debug.req"><info><title>Debug Versions of Library Binary Files</title></info>
-<sect2 id="debug.req">
-<title>Debug Versions of Library Binary Files</title>
<para>
If you would like debug symbols in libstdc++, there are two ways to
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 <link
- linkend="manual.intro.setup.configure">configuration</link> section.
+ more information, look at the <link linkend="manual.intro.setup.configure">configuration</link> section.
</para>
<para>
This quick and dirty approach is often sufficient for quick
debugging tasks, when you cannot or don't want to recompile your
application to use the <link linkend="manual.ext.debug_mode">debug mode</link>.</para>
-</sect2>
+</section>
+
+<section xml:id="debug.memory"><info><title>Memory Leak Hunting</title></info>
-<sect2 id="debug.memory">
-<title>Memory Leak Hunting</title>
<para>
There are various third party memory tracing and debug utilities
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 the <link
- linkend="manual.ext.allocator.mt">mt allocator</link> documentation and
+ std::allocator </code>. For implementation details, see the <link linkend="manual.ext.allocator.mt">mt allocator</link> documentation and
look specifically for <code>GLIBCXX_FORCE_NEW</code>.
</para>
valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out
</programlisting>
-</sect2>
+</section>
+
+<section xml:id="debug.races"><info><title>Data Race Hunting</title></info>
+<para>
+ All synchronization primitives used in the library internals should be
+ understood by race detectors so that they do not produce false reports.
+</para>
+
+<para>
+ We use two annotations (macros) to explain low-level synchronization
+ to race detectors:
+ <code>_GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE()</code> and
+ <code> _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER()</code>.
+ By default, these two macros are defined empty -- anyone who wants
+ to use a race detector will need to redefine these macros to call an
+ appropriate API.
+ Since these macros are empty by default, redefining them in the user code
+ will affect only the inline template code, e.g. <code>shared_ptr</code>.
+ In order to redefine the macros in <code>basic_string</code> one will
+ need to disable extern templates (by defining
+ <code>_GLIBCXX_EXTERN_TEMPLATE=-1</code>) or rebuild the
+ <code>.so</code> file.
+ The rest of the cases (currently, <code>ios_base::Init::~Init</code>,
+ <code>locale::_Impl</code> and <code>locale::facet</code>) will require
+ to rebuild the <code>.so</code> file.
+</para>
+
+<para>
+ The approach described above works at least with the following race
+ detection tools:
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="http://valgrind.org/docs/manual/drd-manual.html">
+ DRD </link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="http://valgrind.org/docs/manual/hg-manual.html">
+ Helgrind </link>,
+ <link xmlns:xlink="http://www.w3.org/1999/xlink"
+ xlink:href="http://code.google.com/p/data-race-test">
+ ThreadSanitizer </link>.
+</para>
+
+<para>
+ With DRD, Helgrind and ThreadSanitizer you will need to define
+ the macros like this:
+<programlisting>
+ #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE(A) ANNOTATE_HAPPENS_BEFORE(A)
+ #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER(A) ANNOTATE_HAPPENS_AFTER(A)
+</programlisting>
+ Refer to the documentation of each particular tool for the details.
+</para>
+
+</section>
+
+<section xml:id="debug.gdb"><info><title>Using <command>gdb</command></title></info>
-<sect2 id="debug.gdb">
-<title>Using <command>gdb</command></title>
<para>
</para>
<para>
- Many options are available for gdb itself: please see <ulink
- url="http://sources.redhat.com/gdb/current/onlinedocs/gdb_13.html#SEC125">
- "GDB features for C++" </ulink> in the gdb documentation. Also
+ 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/">
+ "GDB features for C++" </link> in the GDB documentation. Also
recommended: the other parts of this manual.
</para>
<para>
- These settings can either be switched on in at the gdb command line,
+ 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:
</para>
<para>
For additional information on STL support and GDB please visit:
- <ulink url="http://sourceware.org/gdb/wiki/STLSupport"> "GDB Support
- for STL" </ulink> in the GDB wiki. Additionally, in-depth
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://sourceware.org/gdb/wiki/STLSupport"> "GDB Support
+ for STL" </link> in the GDB wiki. Additionally, in-depth
documentation and discussion of the pretty printing feature can be
found in "Pretty Printing" node in the GDB manual. You can find
on-line versions of the GDB user manual in GDB's homepage, at
- <ulink url="http://sourceware.org/gdb/"> "GDB: The GNU Project
- Debugger" </ulink>.
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://sourceware.org/gdb/"> "GDB: The GNU Project
+ Debugger" </link>.
</para>
-</sect2>
+</section>
+
+<section xml:id="debug.exceptions"><info><title>Tracking uncaught exceptions</title></info>
-<sect2 id="debug.exceptions">
-<title>Tracking uncaught exceptions</title>
<para>
The <link linkend="support.termination.verbose">verbose
termination handler</link> gives information about uncaught
exceptions which are killing the program. It is described in the
linked-to page.
</para>
-</sect2>
+</section>
+
+<section xml:id="debug.debug_mode"><info><title>Debug Mode</title></info>
-<sect2 id="debug.debug_mode">
-<title>Debug Mode</title>
<para> The <link linkend="manual.ext.debug_mode">Debug Mode</link>
has compile and run-time checks for many containers.
</para>
-</sect2>
+</section>
+
+<section xml:id="debug.compile_time_checks"><info><title>Compile Time Checking</title></info>
-<sect2 id="debug.compile_time_checks">
-<title>Compile Time Checking</title>
<para> The <link linkend="manual.ext.compile_checks">Compile-Time
Checks</link> Extension has compile-time checks for many algorithms.
</para>
-</sect2>
+</section>
+
+<section xml:id="debug.profile_mode" xreflabel="debug.profile_mode"><info><title>Profile-based Performance Analysis</title></info>
-<sect2 id="debug.profile_mode" xreflabel="debug.profile_mode">
-<title>Profile-based Performance Analysis</title>
<para> The <link linkend="manual.ext.profile_mode">Profile-based
Performance Analysis</link> Extension has performance checks for many
algorithms.
</para>
-</sect2>
+</section>
-</sect1>
+</section>
OSDN Git Service
