1 |
fox2mike 05/07/13 05:55:39 |
2 |
|
3 |
Added: xml/htdocs/doc/en/draft debugging-howto.xml |
4 |
Log: |
5 |
Initial Version of the debugging-guide, originally part of the bugzilla-howto. |
6 |
|
7 |
Revision Changes Path |
8 |
1.1 xml/htdocs/doc/en/draft/debugging-howto.xml |
9 |
|
10 |
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 |
11 |
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 |
12 |
|
13 |
Index: debugging-howto.xml |
14 |
=================================================================== |
15 |
<?xml version="1.0" encoding="UTF-8"?> |
16 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
17 |
<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/debugging-howto.xml,v 1.1 2005/07/13 05:55:39 fox2mike Exp $ --> |
18 |
|
19 |
<guide link="/doc/en/debugging-howto.xml"> |
20 |
<title>Gentoo Linux Debugging Guide</title> |
21 |
|
22 |
<author title="Author"> |
23 |
<mail link="chriswhite@g.o">Chris White</mail> |
24 |
</author> |
25 |
<author title="Editor"> |
26 |
<mail link="fox2mike@g.o">Shyam Mani</mail> |
27 |
</author> |
28 |
|
29 |
<abstract> |
30 |
This document aims at helping the user debug various errors they may encounter |
31 |
during day to day usage of Gentoo. |
32 |
</abstract> |
33 |
|
34 |
<!-- The content of this document is licensed under the CC-BY-SA license --> |
35 |
<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
36 |
<license/> |
37 |
|
38 |
<version>1.0</version> |
39 |
<date>2005-07-13</date> |
40 |
|
41 |
<chapter> |
42 |
<title>Introduction</title> |
43 |
<section> |
44 |
<title>Preface</title> |
45 |
<body> |
46 |
|
47 |
<p> |
48 |
One of the factors that delay a bug being fixed is the way it is reported. By |
49 |
creating this guide, we hope to help improve the communication between |
50 |
developers and users in bug resolution. Getting bugs fixed is an important, if |
51 |
not crucial part of the quality assurance for any project and hopefully this |
52 |
guide will help make that a success. |
53 |
</p> |
54 |
|
55 |
</body> |
56 |
</section> |
57 |
<section> |
58 |
<title>Bugs!!!!</title> |
59 |
<body> |
60 |
|
61 |
<p> |
62 |
You're emerge-ing a package or working with a program and suddenly the worst |
63 |
happens -- you find a bug. Bugs come in many forms like emerge failures or |
64 |
segmentation faults. Whatever the cause, the fact still remains that such a bug |
65 |
must be fixed. Here is a few examples of such bugs. |
66 |
</p> |
67 |
|
68 |
<pre caption="A run time error"> |
69 |
$ <i>./bad_code `perl -e 'print Ax100'`</i> |
70 |
Segmentation fault |
71 |
</pre> |
72 |
|
73 |
<pre caption="An emerge failure"> |
74 |
/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.2/include/g++-v3/backward/backward_warning.h:32:2: |
75 |
warning: #warning This file includes at least one deprecated or antiquated |
76 |
header. Please consider using one of the 32 headers found in section 17.4.1.2 of |
77 |
the C++ standard. Examples include substituting the <X> header for the <X.h> |
78 |
header for C++ includes, or <sstream> instead of the deprecated header |
79 |
<strstream.h>. To disable this warning use -Wno-deprecated. |
80 |
In file included from main.cc:40: |
81 |
menudef.h:55: error: brace-enclosed initializer used to initialize ` |
82 |
OXPopupMenu*' |
83 |
menudef.h:62: error: brace-enclosed initializer used to initialize ` |
84 |
OXPopupMenu*' |
85 |
menudef.h:70: error: brace-enclosed initializer used to initialize ` |
86 |
OXPopupMenu*' |
87 |
menudef.h:78: error: brace-enclosed initializer used to initialize ` |
88 |
OXPopupMenu*' |
89 |
main.cc: In member function `void OXMain::DoOpen()': |
90 |
main.cc:323: warning: unused variable `FILE*fp' |
91 |
main.cc: In member function `void OXMain::DoSave(char*)': |
92 |
main.cc:337: warning: unused variable `FILE*fp' |
93 |
make[1]: *** [main.o] Error 1 |
94 |
make[1]: Leaving directory |
95 |
`/var/tmp/portage/xclass-0.7.4/work/xclass-0.7.4/example-app' |
96 |
make: *** [shared] Error 2 |
97 |
|
98 |
!!! ERROR: x11-libs/xclass-0.7.4 failed. |
99 |
!!! Function src_compile, Line 29, Exitcode 2 |
100 |
!!! 'emake shared' failed |
101 |
</pre> |
102 |
|
103 |
<p> |
104 |
These errors can be quite troublesome. However, once you find them, what do |
105 |
you do? The following sections will look at two important tools for handling |
106 |
run time errors. After that, we'll take a look at compile errors, and how to |
107 |
handle them. Let's start out with the first tool for debugging run time |
108 |
errors -- <c>gdb</c>. |
109 |
</p> |
110 |
|
111 |
</body> |
112 |
</section> |
113 |
</chapter> |
114 |
|
115 |
|
116 |
<chapter> |
117 |
<title>Debugging using GDB</title> |
118 |
<section> |
119 |
<title>Introduction</title> |
120 |
<body> |
121 |
|
122 |
<p> |
123 |
GDB, or the (G)NU (D)e(B)ugger, is a program used to find run time errors that |
124 |
normally involve memory corruption. First off, let's take a look at what |
125 |
debugging entails. One of the main things you must do in order to debug a |
126 |
program is to <c>emerge</c> the program with <c>FEATURES="nostrip"</c>. This |
127 |
prevents the stripping of debug symbols. Why are programs stripped by default? |
128 |
The reason is the same as that for having gzipped man pages -- saving space. |
129 |
Here's how the size of a program varies with and without debug symbol stripping. |
130 |
</p> |
131 |
|
132 |
<pre caption="Filesize Comparison"> |
133 |
<comment>(debug symbols stripped)</comment> |
134 |
-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code |
135 |
<comment>(debug symbols intact)</comment> |
136 |
-rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code |
137 |
</pre> |
138 |
|
139 |
<p> |
140 |
Just for reference, <e>bad_code</e> is the program we'll be debugging with |
141 |
<c>gdb</c> later on. As you can see, the program without debugging symbols is |
142 |
3140 bytes, while the program with them is 6374 bytes. That's close to double |
143 |
the size! Two more things can be done for debugging. The first is adding ggdb3 |
144 |
to your CFLAGS and CXXFLAGS. This flag adds more debugging information than is |
145 |
generally included. We'll see what that means later on. This is how |
146 |
<path>/etc/make.conf</path> <e>might</e> look with the newly added flags. |
147 |
</p> |
148 |
|
149 |
<pre caption="make.conf settings"> |
150 |
CFLAGS="-O2 -pipe -ggdb3" |
151 |
CXXFLAGS="${CFLAGS}" |
152 |
</pre> |
153 |
|
154 |
<p> |
155 |
Lastly, you can also add debug to the package's USE flags. This can be done with the |
156 |
<path>package.use</path> file. |
157 |
</p> |
158 |
|
159 |
<pre caption="Using package.use to add debug USE flag"> |
160 |
# <i>echo "category/package debug" >> /etc/portage/package.use</i> |
161 |
</pre> |
162 |
|
163 |
<note> |
164 |
The directory <path>/etc/portage</path> does not exist by default and you may |
165 |
have to create it, if you have not already done so. If the package already has |
166 |
USE flags set in <path>package.use</path>, you will need to manually modify them |
167 |
in your favorite editor. |
168 |
</note> |
169 |
|
170 |
<p> |
171 |
Then we re-emerge the package with the modifications we've done so far as shown |
172 |
below. |
173 |
</p> |
174 |
|
175 |
<pre caption="Re-emergeing a package with debugging"> |
176 |
# <i>FEATURES="nostrip" emerge package</i> |
177 |
</pre> |
178 |
|
179 |
<p> |
180 |
Now that debug symbols are setup, we can continue with debugging the program. |
181 |
</p> |
182 |
|
183 |
</body> |
184 |
</section> |
185 |
<section> |
186 |
<title>Running the program with GDB</title> |
187 |
<body> |
188 |
|
189 |
<p> |
190 |
Let's say we have a program here called "bad_code". Some person claims that the |
191 |
program crashes and provides an example. You go ahead and test it out: |
192 |
</p> |
193 |
|
194 |
<pre caption="Breaking The Program"> |
195 |
$ <i>./bad_code `perl -e 'print Ax100'`</i> |
196 |
Segmentation fault |
197 |
</pre> |
198 |
|
199 |
<p> |
200 |
It seems this person was right. Since the program is obviously broken, we have |
201 |
a bug at hand. Now, it's time to use <c>gdb</c> to help solve this matter. First |
202 |
we run <c>gdb</c> with <c>--args</c>, then give it the full program with |
203 |
arguments like shown: |
204 |
</p> |
205 |
|
206 |
<pre caption="Running Our Program Through GDB"> |
207 |
$ <i>gdb --args ./bad_code `perl -e 'print Ax100'`</i> |
208 |
GNU gdb 6.3 |
209 |
Copyright 2004 Free Software Foundation, Inc. |
210 |
GDB is free software, covered by the GNU General Public License, and you are |
211 |
welcome to change it and/or distribute copies of it under certain conditions. |
212 |
Type "show copying" to see the conditions. |
213 |
There is absolutely no warranty for GDB. Type "show warranty" for details. |
214 |
|
215 |
|
216 |
|
217 |
-- |
218 |
gentoo-doc-cvs@g.o mailing list |