diff options
Diffstat (limited to 'libstdc++-v3/doc/xml/manual/debug.xml')
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/debug.xml | 355 |
1 files changed, 355 insertions, 0 deletions
diff --git a/libstdc++-v3/doc/xml/manual/debug.xml b/libstdc++-v3/doc/xml/manual/debug.xml new file mode 100644 index 000000000..05994ec17 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/debug.xml @@ -0,0 +1,355 @@ +<section xmlns="http://docbook.org/ns/docbook" version="5.0" + xml:id="manual.intro.using.debug" xreflabel="Debugging Support"> +<?dbhtml filename="debug.html"?> + +<info><title>Debugging Support</title> + <keywordset> + <keyword> + C++ + </keyword> + <keyword> + debug + </keyword> + </keywordset> +</info> + + + +<para> + There are numerous things that can be done to improve the ease with + which C++ binaries are debugged when using the GNU tool chain. Here + are some of them. +</para> + +<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. + </para> + + <para> + The default optimizations and debug flags for a libstdc++ build + are <code>-g -O2</code>. However, both debug and optimization + flags can be varied to change debugging characteristics. For + instance, turning off all optimization via the <code>-g -O0 + -fno-inline</code> flags will disable inlining and optimizations, + and add debugging information, so that stepping through all functions, + (including inlined constructors and destructors) is possible. In + addition, <code>-fno-eliminate-unused-debug-types</code> can be + used when additional debug information, such as nested class info, + is desired. +</para> + +<para> + Or, the debug format that the compiler and debugger use to + 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 + <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 <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> +</section> + +<section xml:id="debug.req"><info><title>Debug Versions of Library Binary Files</title></info> + + +<para> + If you would like debug symbols in libstdc++, there are two ways to + build libstdc++ with debug flags. The first is to run make from the + toplevel in a freshly-configured tree with +</para> +<programlisting> + --enable-libstdcxx-debug +</programlisting> +<para>and perhaps</para> +<programlisting> + --enable-libstdcxx-debug-flags='...' +</programlisting> +<para> + to create a separate debug build. Both the normal build and the + 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. +</para> + +<para> + A second approach is to use the configuration flags +</para> +<programlisting> + make CXXFLAGS='-g3 -fno-inline -O0' all +</programlisting> + +<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> +</section> + +<section xml:id="debug.memory"><info><title>Memory Leak Hunting</title></info> + + +<para> + There are various third party memory tracing and debug utilities + that can be used to provide detailed memory allocation information + about C++ code. An exhaustive list of tools is not going to be + attempted, but includes <code>mtrace</code>, <code>valgrind</code>, + <code>mudflap</code>, and the non-free commercial product + <code>purify</code>. In addition, <code>libcwd</code> has a + replacement for the global new and delete operators that can track + memory allocation and deallocation and provide useful memory + statistics. +</para> + +<para> + Regardless of the memory debugging tool being used, there is one + 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 + look specifically for <code>GLIBCXX_FORCE_NEW</code>. +</para> + +<para> + In a nutshell, the default allocator used by <code> + std::allocator</code> is a high-performance pool allocator, and can + give the mistaken impression that in a suspect executable, memory is + being leaked, when in reality the memory "leak" is a pool being used + by the library's allocator and is reclaimed after program + termination. +</para> + +<para> + For valgrind, there are some specific items to keep in mind. First + of all, use a version of valgrind that will work with current GNU + C++ tools: the first that can do this is valgrind 1.0.4, but later + versions should work at least as well. Second of all, use a + completely unoptimized build to avoid confusing valgrind. Third, use + GLIBCXX_FORCE_NEW to keep extraneous pool allocation noise from + cluttering debug information. +</para> + +<para> + Fourth, it may be necessary to force deallocation in other libraries + as well, namely the "C" library. On linux, this can be accomplished + with the appropriate use of the <code>__cxa_atexit</code> or + <code>atexit</code> functions. +</para> + +<programlisting> + #include <cstdlib> + + extern "C" void __libc_freeres(void); + + void do_something() { } + + int main() + { + atexit(__libc_freeres); + do_something(); + return 0; + } +</programlisting> + + +<para>or, using <code>__cxa_atexit</code>:</para> + +<programlisting> + extern "C" void __libc_freeres(void); + extern "C" int __cxa_atexit(void (*func) (void *), void *arg, void *d); + + void do_something() { } + + int main() + { + extern void* __dso_handle __attribute__ ((__weak__)); + __cxa_atexit((void (*) (void *)) __libc_freeres, NULL, + &__dso_handle ? __dso_handle : NULL); + do_test(); + return 0; + } +</programlisting> + +<para> + Suggested valgrind flags, given the suggestions above about setting + up the runtime environment, library, and test file, might be: +</para> +<programlisting> + valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out +</programlisting> + +</section> + +<section xml:id="debug.races"><info><title>Data Race Hunting</title></info> +<para> + All synchronization primitives used in the library internals need to be + understood by race detectors so that they do not produce false reports. +</para> + +<para> + Two annotation macros are used to explain low-level synchronization + to race detectors: + <code>_GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE()</code> and + <code> _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER()</code>. + By default, these macros are defined empty -- anyone who wants + to use a race detector needs to redefine them to call an + appropriate API. + Since these macros are empty by default when the library is built, + redefining them will only affect inline functions and template + instantiations which are compiled in user code. This allows annotation + of templates such as <code>shared_ptr</code>, but not code which is + only instantiated in the library. + In order to annotate <code>basic_string</code> reference counting it + is necessary to disable extern templates (by defining + <code>_GLIBCXX_EXTERN_TEMPLATE=-1</code>) or to rebuild the + <code>.so</code> file. + Annotating the remaining atomic operations (at the time of writing these + are in <code>ios_base::Init::~Init</code>, <code>locale::_Impl</code> and + <code>locale::facet</code>) requires rebuilding the <code>.so</code> file. +</para> + +<para> + The approach described above is known to work 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>, and + <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 details. +</para> + +</section> + +<section xml:id="debug.gdb"><info><title>Using <command>gdb</command></title></info> + + <para> + </para> + +<para> + 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, + or put into a .gdbint file to establish default debugging + characteristics, like so: +</para> + +<programlisting> + set print pretty on + set print object on + set print static-members on + set print vtbl on + set print demangle on + set demangle-style gnu-v3 +</programlisting> + +<para> + Starting with version 7.0, GDB includes support for writing + pretty-printers in Python. Pretty printers for STL classes are + distributed with GCC from version 4.5.0. The most recent version of + these printers are always found in libstdc++ svn repository. + To enable these printers, check-out the latest printers to a local + directory: +</para> + +<programlisting> + svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python +</programlisting> + +<para> + Next, add the following section to your ~/.gdbinit The path must + match the location where the Python module above was checked-out. + So if checked out to: /home/maude/gdb_printers/, the path would be as + written in the example below. +</para> + +<programlisting> + python + import sys + sys.path.insert(0, '/home/maude/gdb_printers/python') + from libstdcxx.v6.printers import register_libstdcxx_printers + register_libstdcxx_printers (None) + end +</programlisting> + +<para> + The path should be the only element that needs to be adjusted in the + example. Once loaded, STL classes that the printers support + should print in a more human-readable format. To print the classes + in the old style, use the /r (raw) switch in the print command + (i.e., print /r foo). This will print the classes as if the Python + pretty-printers were not loaded. +</para> + +<para> + For additional information on STL support and GDB please visit: + <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 + <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://sourceware.org/gdb/"> "GDB: The GNU Project + Debugger" </link>. +</para> + +</section> + +<section xml:id="debug.exceptions"><info><title>Tracking uncaught exceptions</title></info> + +<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> +</section> + +<section xml:id="debug.debug_mode"><info><title>Debug Mode</title></info> + + <para> The <link linkend="manual.ext.debug_mode">Debug Mode</link> + has compile and run-time checks for many containers. + </para> +</section> + +<section xml:id="debug.compile_time_checks"><info><title>Compile Time Checking</title></info> + + <para> The <link linkend="manual.ext.compile_checks">Compile-Time + Checks</link> Extension has compile-time checks for many algorithms. + </para> +</section> + +<section xml:id="debug.profile_mode" xreflabel="debug.profile_mode"><info><title>Profile-based Performance Analysis</title></info> + + <para> The <link linkend="manual.ext.profile_mode">Profile-based + Performance Analysis</link> Extension has performance checks for many + algorithms. + </para> +</section> + +</section> |