From b5ff3a9077ae7a23608c437885938de027bb28f0 Mon Sep 17 00:00:00 2001 From: Benjamin Kosnik Date: Thu, 19 Dec 2002 08:18:14 +0000 Subject: [PATCH] documentation.html: Add link for debug.html. 2002-12-18 Benjamin Kosnik * docs/html/documentation.html: Add link for debug.html. * docs/html/debug.html: New. From-SVN: r60302 --- libstdc++-v3/ChangeLog | 18 +- libstdc++-v3/docs/html/debug.html | 228 ++++++++++++++++++++++ libstdc++-v3/docs/html/documentation.html | 1 + 3 files changed, 242 insertions(+), 5 deletions(-) create mode 100644 libstdc++-v3/docs/html/debug.html diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 34d072e0950..9378d5e7120 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,8 @@ +2002-12-18 Benjamin Kosnik + + * docs/html/documentation.html: Add link for debug.html. + * docs/html/debug.html: New. + 2002-12-18 Kaveh R. Ghazi * testsuite/23_containers/vector_capacity.cc (test03): Move ... @@ -189,14 +194,17 @@ const unsigned char*)): Fully qualify min() with std::. * include/bits/stl_bvector.h (_M_insert_range(iterator, _ForwardIterator, _ForwardIterator, forward_iterator_tag), - _M_assign_aux(_ForwardIterator, _ForwardIterator, forward_iterator_tag), + _M_assign_aux(_ForwardIterator, _ForwardIterator, + forward_iterator_tag), _M_initialize_range(_ForwardIterator, _ForwardIterator, forward_iterator_tag), _M_fill_insert(iterator, size_type, bool)): Fully qualify distance() and max() with std::. - * include/bits/stl_deque.h (_Deque_base::_M_initialize_map(size_t), - _M_assign_aux(_ForwardIterator, _ForwardIterator, forward_iterator_tag)): - Ditto. - * include/bits/stl_list.h (size()): Fully qualify distance() with std::. + * include/bits/stl_deque.h + (_Deque_base::_M_initialize_map(size_t), + _M_assign_aux(_ForwardIterator, _ForwardIterator, + forward_iterator_tag)): + Ditto. * include/bits/stl_list.h (size()): Fully qualify + distance() with std::. * include/bits/stl_tempbuf.h (_Temporary_buffer::_Temporary_buffer (_ForwardIterator, _ForwardIterator)): Ditto. * include/bits/stl_tree.h (_Rb_tree::erase(const _Key&), diff --git a/libstdc++-v3/docs/html/debug.html b/libstdc++-v3/docs/html/debug.html new file mode 100644 index 00000000000..73d592ffc25 --- /dev/null +++ b/libstdc++-v3/docs/html/debug.html @@ -0,0 +1,228 @@ + + + + + + + + + + Debugging schemes and strategies + + + + +

Debugging schemes and strategies

+ +

+

The latest version of this document is always available at + + http://gcc.gnu.org/onlinedocs/libstdc++/debug.html. +

+ +

To the libstdc++-v3 homepage. +

+

+ + +
+

+ There are numerous things that can be done to improve the ease with + which C++ binaries are debugged when using the GNU C++ + tool chain. Here are some things to keep in mind when debugging C++ + code with GNU tools. +

+ +

Compiler flags determine debug info

+

+ 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 flag will + disable inlining, so that stepping through all functions, including + inlined constructors and destructors, is possible. 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. + 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. +

+ + +

Using special flags to make a debug binary

+

+ 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 + specialized debug CXXFLAGS, as in

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

+ +

+ This quick and dirty approach is often sufficient for quick + debugging tasks, but the lack of state can be confusing in the long + term. +

+ +

+ A second approach is to use the configuration flags +

+ +
--enable-debug
+ +

+ and perhaps +

+ +
--enable-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 options document + here +

+ + +

Tips for 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 include mtrace, valgrind, + mudflap, and purify. Also highly + recommended are libcwd and some other one that I + forget right now. +

+ +

+ 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 this + + document and look specifically for GLIBCPP_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 memory is being leaked, when in + reality the memory 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 GLIBCPP_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 
+
+   extern "C" void __libc_freeres(void);
+
+   void do_something() { }
+
+   int main()
+   {
+     atexit(__libc_freeres);
+     do_test();
+     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
+

+ + +

Some gdb strategies

+

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

Return to the top of the page or + to the libstdc++ homepage. +

+ + + + +
+

+See license.html for copying conditions. +Comments and suggestions are welcome, and may be sent to +the libstdc++ mailing list. +

+ + + + diff --git a/libstdc++-v3/docs/html/documentation.html b/libstdc++-v3/docs/html/documentation.html index 0dc25bedfa0..d805c66ea9e 100644 --- a/libstdc++-v3/docs/html/documentation.html +++ b/libstdc++-v3/docs/html/documentation.html @@ -47,6 +47,7 @@