Debugging Support

Debugging Support
Prev	Chapter 3. Using	Next

+ 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. +

Using g++

+ Compiler flags determine how debug information is transmitted + between compilation and debug or analysis tools. +

+ The default optimizations and debug flags for a libstdc++ build + are -g -O2. However, both debug and optimization + flags can be varied to change debugging characteristics. For + instance, turning off all optimization via the -g -O0 + -fno-inline 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, -fno-eliminate-unused-debug-types can be + used when additional debug information, such as nested class info, + is desired. +

+ Or, the debug format that the compiler and debugger use to + communicate information about source constructs can be changed via + -gdwarf-2 or -gstabs flags: some debugging + formats permit more expressive type and scope information to be + shown in GDB. Expressiveness can be enhanced by flags like + -g3. 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. +

+ Many other options are available: please see "Options + for Debugging Your Program" in Using the GNU Compiler + Collection (GCC) for a complete list. +

Debug Versions of Library Binary Files

+ 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 +

+     --enable-libstdcxx-debug
+

and perhaps

+     --enable-libstdcxx-debug-flags='...'
+

+ to create a separate debug build. Both the normal build and the + debug build will persist, without having to specify + CXXFLAGS, and the debug library will be installed in a + separate directory tree, in (prefix)/lib/debug. For + more information, look at the configuration section. +

+ A second approach is to use the configuration flags +

+     make CXXFLAGS='-g3 -fno-inline -O0' all
+

+ 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 debug mode.

Memory Leak Hunting

+ 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 mtrace, valgrind, + mudflap, and the non-free commercial product + purify. In addition, libcwd has a + replacement for the global new and delete operators that can track + memory allocation and deallocation and provide useful memory + statistics. +

+ 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 new and delete: there are + different kinds of allocation schemes that can be used by + std::allocator. For implementation details, see the mt allocator documentation and + look specifically for GLIBCXX_FORCE_NEW. +

+ In a nutshell, the default allocator used by + std::allocator 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. +

+ 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. +

+ 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 __cxa_atexit or + atexit functions. +

+   #include <cstdlib>
+
+   extern "C" void __libc_freeres(void);
+
+   void do_something() { }
+
+   int main()
+   {
+     atexit(__libc_freeres);
+     do_something();
+     return 0;
+   }
+

or, using __cxa_atexit:

+   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;
+   }
+

+ Suggested valgrind flags, given the suggestions above about setting + up the runtime environment, library, and test file, might be: +

+   valgrind -v --num-callers=20 --leak-check=yes --leak-resolution=high --show-reachable=yes a.out
+

Data Race Hunting

+ All synchronization primitives used in the library internals need to be + understood by race detectors so that they do not produce false reports. +

+ Two annotation macros are used to explain low-level synchronization + to race detectors: + _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE() and + _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER(). + 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 shared_ptr, but not code which is + only instantiated in the library. + In order to annotate basic_string reference counting it + is necessary to disable extern templates (by defining + _GLIBCXX_EXTERN_TEMPLATE=-1) or to rebuild the + .so file. + Annotating the remaining atomic operations (at the time of writing these + are in ios_base::Init::~Init, locale::_Impl and + locale::facet) requires rebuilding the .so file. +

+ The approach described above is known to work with the following race + detection tools: + + DRD, + + Helgrind, and + + ThreadSanitizer. +

+ With DRD, Helgrind and ThreadSanitizer you will need to define + the macros like this: +

+  #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_BEFORE(A) ANNOTATE_HAPPENS_BEFORE(A)
+  #define _GLIBCXX_SYNCHRONIZATION_HAPPENS_AFTER(A)  ANNOTATE_HAPPENS_AFTER(A)
+

+ Refer to the documentation of each particular tool for details. +

Using gdb

+ Many options are available for GDB itself: please see + "GDB features for C++" in the GDB documentation. Also + recommended: the other parts of this manual. +

+ 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: +

+   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
+

+ 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: +

+  svn co svn://gcc.gnu.org/svn/gcc/trunk/libstdc++-v3/python
+

+ 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. +

+  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
+

+ 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. +

+ For additional information on STL support and GDB please visit: + "GDB Support + for STL" 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 + "GDB: The GNU Project + Debugger" . +

Prev	Up	Next
Exceptions	Home	Part II. + Standard Contents +