fox2mike 05/07/13 05:55:39 Added: xml/htdocs/doc/en/draft debugging-howto.xml Log: Initial Version of the debugging-guide, originally part of the bugzilla-howto.
Revision Changes Path 1.1 xml/htdocs/doc/en/draft/debugging-howto.xml file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/debugging-howto.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/draft/debugging-howto.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo Index: debugging-howto.xml =================================================================== <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/debugging-howto.xml,v 1.1 2005/07/13 05:55:39 fox2mike Exp $ --> <guide link="/doc/en/debugging-howto.xml"> <title>Gentoo Linux Debugging Guide</title> <author title="Author"> <mail link="[EMAIL PROTECTED]">Chris White</mail> </author> <author title="Editor"> <mail link="[EMAIL PROTECTED]">Shyam Mani</mail> </author> <abstract> This document aims at helping the user debug various errors they may encounter during day to day usage of Gentoo. </abstract> <!-- The content of this document is licensed under the CC-BY-SA license --> <!-- See http://creativecommons.org/licenses/by-sa/2.5 --> <license/> <version>1.0</version> <date>2005-07-13</date> <chapter> <title>Introduction</title> <section> <title>Preface</title> <body> <p> One of the factors that delay a bug being fixed is the way it is reported. By creating this guide, we hope to help improve the communication between developers and users in bug resolution. Getting bugs fixed is an important, if not crucial part of the quality assurance for any project and hopefully this guide will help make that a success. </p> </body> </section> <section> <title>Bugs!!!!</title> <body> <p> You're emerge-ing a package or working with a program and suddenly the worst happens -- you find a bug. Bugs come in many forms like emerge failures or segmentation faults. Whatever the cause, the fact still remains that such a bug must be fixed. Here is a few examples of such bugs. </p> <pre caption="A run time error"> $ <i>./bad_code `perl -e 'print Ax100'`</i> Segmentation fault </pre> <pre caption="An emerge failure"> /usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.2/include/g++-v3/backward/backward_warning.h:32:2: warning: #warning This file includes at least one deprecated or antiquated header. Please consider using one of the 32 headers found in section 17.4.1.2 of the C++ standard. Examples include substituting the <X> header for the <X.h> header for C++ includes, or <sstream> instead of the deprecated header <strstream.h>. To disable this warning use -Wno-deprecated. In file included from main.cc:40: menudef.h:55: error: brace-enclosed initializer used to initialize ` OXPopupMenu*' menudef.h:62: error: brace-enclosed initializer used to initialize ` OXPopupMenu*' menudef.h:70: error: brace-enclosed initializer used to initialize ` OXPopupMenu*' menudef.h:78: error: brace-enclosed initializer used to initialize ` OXPopupMenu*' main.cc: In member function `void OXMain::DoOpen()': main.cc:323: warning: unused variable `FILE*fp' main.cc: In member function `void OXMain::DoSave(char*)': main.cc:337: warning: unused variable `FILE*fp' make[1]: *** [main.o] Error 1 make[1]: Leaving directory `/var/tmp/portage/xclass-0.7.4/work/xclass-0.7.4/example-app' make: *** [shared] Error 2 !!! ERROR: x11-libs/xclass-0.7.4 failed. !!! Function src_compile, Line 29, Exitcode 2 !!! 'emake shared' failed </pre> <p> These errors can be quite troublesome. However, once you find them, what do you do? The following sections will look at two important tools for handling run time errors. After that, we'll take a look at compile errors, and how to handle them. Let's start out with the first tool for debugging run time errors -- <c>gdb</c>. </p> </body> </section> </chapter> <chapter> <title>Debugging using GDB</title> <section> <title>Introduction</title> <body> <p> GDB, or the (G)NU (D)e(B)ugger, is a program used to find run time errors that normally involve memory corruption. First off, let's take a look at what debugging entails. One of the main things you must do in order to debug a program is to <c>emerge</c> the program with <c>FEATURES="nostrip"</c>. This prevents the stripping of debug symbols. Why are programs stripped by default? The reason is the same as that for having gzipped man pages -- saving space. Here's how the size of a program varies with and without debug symbol stripping. </p> <pre caption="Filesize Comparison"> <comment>(debug symbols stripped)</comment> -rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code <comment>(debug symbols intact)</comment> -rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code </pre> <p> Just for reference, <e>bad_code</e> is the program we'll be debugging with <c>gdb</c> later on. As you can see, the program without debugging symbols is 3140 bytes, while the program with them is 6374 bytes. That's close to double the size! Two more things can be done for debugging. The first is adding ggdb3 to your CFLAGS and CXXFLAGS. This flag adds more debugging information than is generally included. We'll see what that means later on. This is how <path>/etc/make.conf</path> <e>might</e> look with the newly added flags. </p> <pre caption="make.conf settings"> CFLAGS="-O2 -pipe -ggdb3" CXXFLAGS="${CFLAGS}" </pre> <p> Lastly, you can also add debug to the package's USE flags. This can be done with the <path>package.use</path> file. </p> <pre caption="Using package.use to add debug USE flag"> # <i>echo "category/package debug" >> /etc/portage/package.use</i> </pre> <note> The directory <path>/etc/portage</path> does not exist by default and you may have to create it, if you have not already done so. If the package already has USE flags set in <path>package.use</path>, you will need to manually modify them in your favorite editor. </note> <p> Then we re-emerge the package with the modifications we've done so far as shown below. </p> <pre caption="Re-emergeing a package with debugging"> # <i>FEATURES="nostrip" emerge package</i> </pre> <p> Now that debug symbols are setup, we can continue with debugging the program. </p> </body> </section> <section> <title>Running the program with GDB</title> <body> <p> Let's say we have a program here called "bad_code". Some person claims that the program crashes and provides an example. You go ahead and test it out: </p> <pre caption="Breaking The Program"> $ <i>./bad_code `perl -e 'print Ax100'`</i> Segmentation fault </pre> <p> It seems this person was right. Since the program is obviously broken, we have a bug at hand. Now, it's time to use <c>gdb</c> to help solve this matter. First we run <c>gdb</c> with <c>--args</c>, then give it the full program with arguments like shown: </p> <pre caption="Running Our Program Through GDB"> $ <i>gdb --args ./bad_code `perl -e 'print Ax100'`</i> GNU gdb 6.3 Copyright 2004 Free Software Foundation, Inc. GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. -- [email protected] mailing list
