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