mirror of
https://github.com/autc04/Retro68.git
synced 2024-12-04 16:50:57 +00:00
348 lines
13 KiB
XML
348 lines
13 KiB
XML
<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 create a separate
|
|
debug build by running make from the top-level of a tree
|
|
freshly-configured with
|
|
</para>
|
|
<programlisting>
|
|
--enable-libstdcxx-debug
|
|
</programlisting>
|
|
<para>and perhaps</para>
|
|
<programlisting>
|
|
--enable-libstdcxx-debug-flags='...'
|
|
</programlisting>
|
|
<para>
|
|
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 optional <classname>mt_allocator</classname>
|
|
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. Code which is only instantiated in
|
|
the library needs to be recompiled with the annotation macros defined.
|
|
That can be done by rebuilding the entire
|
|
<filename class="libraryfile">libstdc++.so</filename> file but a simpler
|
|
alternative exists for ELF platforms such as GNU/Linux, because ELF
|
|
symbol interposition allows symbols defined in the shared library to be
|
|
overridden by symbols with the same name that appear earlier in the
|
|
runtime search path. This means you only need to recompile the functions
|
|
that are affected by the annotation macros, which can be done by
|
|
recompiling individual files.
|
|
Annotating <code>std::string</code> and <code>std::wstring</code>
|
|
reference counting can be done by disabling extern templates (by defining
|
|
<code>_GLIBCXX_EXTERN_TEMPLATE=-1</code>) or by rebuilding the
|
|
<filename>src/string-inst.cc</filename> file.
|
|
Annotating the remaining atomic operations (at the time of writing these
|
|
are in <code>ios_base::Init::~Init</code>, <code>locale::_Impl</code>,
|
|
<code>locale::facet</code> and <code>thread::_M_start_thread</code>)
|
|
requires rebuilding the relevant source files.
|
|
</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://sourceware.org/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 <filename>.gdbinit</filename> 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 containers and other
|
|
classes are distributed with GCC from version 4.5.0 and should be installed
|
|
alongside the libstdc++ shared library files and found automatically by
|
|
GDB.
|
|
</para>
|
|
|
|
<para>
|
|
Depending where libstdc++ is installed, GDB might refuse to auto-load
|
|
the python printers and print a warning instead.
|
|
If this happens the python printers can be enabled by following the
|
|
instructions GDB gives for setting your <code>auto-load safe-path</code>
|
|
in your <filename>.gdbinit</filename> configuration file.
|
|
</para>
|
|
|
|
<para>
|
|
Once loaded, standard library classes that the printers support
|
|
should print in a more human-readable format. To print the classes
|
|
in the old style, use the <userinput>/r</userinput> (raw) switch in the
|
|
print command (i.e., <userinput>print /r foo</userinput>). 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 kill the program.
|
|
</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>
|