X-Git-Url: https://oss.titaniummirror.com/gitweb?a=blobdiff_plain;f=libstdc%2B%2B-v3%2Fdoc%2Fxml%2Fmanual%2Fdebug.xml;fp=libstdc%2B%2B-v3%2Fdoc%2Fxml%2Fmanual%2Fdebug.xml;h=2ad542b97b15400e4bc38513d1ca29a4d2170582;hb=6fed43773c9b0ce596dca5686f37ac3fc0fa11c0;hp=0000000000000000000000000000000000000000;hpb=27b11d56b743098deb193d510b337ba22dc52e5c;p=msp430-gcc.git diff --git a/libstdc++-v3/doc/xml/manual/debug.xml b/libstdc++-v3/doc/xml/manual/debug.xml new file mode 100644 index 00000000..2ad542b9 --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/debug.xml @@ -0,0 +1,246 @@ + + + + + + + C++ + + + debug + + + + +Debugging Support + + + 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 <command>g++</command> + + 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 + + + + + +Using <command>gdb</command> + + + + + 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 + + + + +Tracking uncaught exceptions + + The verbose + termination handler gives information about uncaught + exceptions which are killing the program. It is described in the + linked-to page. + + + + +Debug Mode + The Debug Mode + has compile and run-time checks for many containers. + + + + +Compile Time Checking + The Compile-Time + Checks Extension has compile-time checks for many algorithms. + + + + \ No newline at end of file