From: "Shyam Mani" <fox2mike@lark.gentoo.org>
To: gentoo-doc-cvs@lists.gentoo.org
Subject: [gentoo-doc-cvs] cvs commit: debugging-howto.xml
Date: Wed, 13 Jul 2005 05:55:39 +0000 [thread overview]
Message-ID: <200507130554.j6D5slch008476@robin.gentoo.org> (raw)
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="chriswhite@gentoo.org">Chris White</mail>
</author>
<author title="Editor">
<mail link="fox2mike@gentoo.org">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.
--
gentoo-doc-cvs@gentoo.org mailing list
next reply other threads:[~2005-07-13 5:55 UTC|newest]
Thread overview: 4+ messages / expand[flat|nested] mbox.gz Atom feed top
2005-07-13 5:55 Shyam Mani [this message]
-- strict thread matches above, loose matches on Subject: below --
2005-07-13 18:58 [gentoo-doc-cvs] cvs commit: debugging-howto.xml Shyam Mani
2005-07-14 9:42 Sven Vermeulen
2005-07-14 9:54 Shyam Mani
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=200507130554.j6D5slch008476@robin.gentoo.org \
--to=fox2mike@lark.gentoo.org \
--cc=docs-team@lists.gentoo.org \
--cc=gentoo-doc-cvs@lists.gentoo.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox