| 1 |
fox2mike 05/07/09 22:31:57 |
| 2 |
|
| 3 |
Modified: xml/htdocs/doc/en bugzilla-howto.xml |
| 4 |
Log: |
| 5 |
Major updates to the guide. GuideXML corrections, content and grammer changes along with a few section additions. IMPORTANT : Translators, Please do not commence work on this guide for the next couple of days as the guide may see drastic changes. See gentoo-doc ML for details. Thanks. |
| 6 |
|
| 7 |
Revision Changes Path |
| 8 |
1.3 +539 -210 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.3&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.3&content-type=text/plain&cvsroot=gentoo |
| 12 |
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml.diff?r1=1.2&r2=1.3&cvsroot=gentoo |
| 13 |
|
| 14 |
Index: bugzilla-howto.xml |
| 15 |
=================================================================== |
| 16 |
RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v |
| 17 |
retrieving revision 1.2 |
| 18 |
retrieving revision 1.3 |
| 19 |
diff -u -r1.2 -r1.3 |
| 20 |
--- bugzilla-howto.xml 7 Jul 2005 18:19:23 -0000 1.2 |
| 21 |
+++ bugzilla-howto.xml 9 Jul 2005 22:31:57 -0000 1.3 |
| 22 |
@@ -1,6 +1,6 @@ |
| 23 |
<?xml version="1.0" encoding="UTF-8"?> |
| 24 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
| 25 |
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.2 2005/07/07 18:19:23 fox2mike Exp $ --> |
| 26 |
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.3 2005/07/09 22:31:57 fox2mike Exp $ --> |
| 27 |
|
| 28 |
<guide link="/doc/en/bugzilla-howto.xml"> |
| 29 |
<title>Gentoo Bug Reporting Guide</title> |
| 30 |
@@ -20,8 +20,8 @@ |
| 31 |
<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> |
| 32 |
<license/> |
| 33 |
|
| 34 |
-<version>1.1</version> |
| 35 |
-<date>2005-07-07</date> |
| 36 |
+<version>1.2</version> |
| 37 |
+<date>2005-07-10</date> |
| 38 |
|
| 39 |
<chapter> |
| 40 |
<title>Introduction</title> |
| 41 |
@@ -30,24 +30,24 @@ |
| 42 |
<body> |
| 43 |
|
| 44 |
<p> |
| 45 |
-Often one of the factors that delay a bug being fixed is how it is reported. By |
| 46 |
-creating this guide, I hope to help improve the communication between |
| 47 |
+One of the factors that delay a bug being fixed is the way it is reported. By |
| 48 |
+creating this guide, we 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 |
+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>Initial Finding</title> |
| 59 |
+<title>Bugs!!!!</title> |
| 60 |
<body> |
| 61 |
|
| 62 |
<p> |
| 63 |
-You're emerge-ing a package or working with a program, then suddenly the worst |
| 64 |
-happens -- you find a bug. Bugs come in many forms, whether it be emerge |
| 65 |
-failures or segmentation faults. Whatever the cause, the fact still remains that |
| 66 |
-such a bug must be fixed. Here is a few examples of such bugs. |
| 67 |
+You're emerge-ing a package or working with a program and suddenly the worst |
| 68 |
+happens -- you find a bug. Bugs come in many forms like emerge failures or |
| 69 |
+segmentation faults. Whatever the cause, the fact still remains that such a bug |
| 70 |
+must be fixed. Here is a few examples of such bugs. |
| 71 |
</p> |
| 72 |
|
| 73 |
<pre caption="A run time error"> |
| 74 |
@@ -87,10 +87,10 @@ |
| 75 |
|
| 76 |
<p> |
| 77 |
These errors can be quite troublesome. However, once you find them, what do |
| 78 |
-you do? The following sections will look at 2 important tools for handling |
| 79 |
+you do? The following sections will look at two important tools for handling |
| 80 |
run time errors. After that, we'll take a look at compile errors, and how to |
| 81 |
handle them. Let's start out with the first tool for debugging run time |
| 82 |
-errors -- <c>gdb</c> |
| 83 |
+errors -- <c>gdb</c>. |
| 84 |
</p> |
| 85 |
|
| 86 |
</body> |
| 87 |
@@ -108,10 +108,10 @@ |
| 88 |
GDB, or the (G)NU (D)e(B)ugger, is a program used to find run time errors that |
| 89 |
normally involve memory corruption. First off, let's take a look at what |
| 90 |
debugging entails. One of the main things you must do in order to debug a |
| 91 |
-program is to <c>emerge</c> the program with FEATURES="nostrip". This prevents |
| 92 |
-the stripping of debug symbols. Why are programs stripped by default? The reason |
| 93 |
-is the same as that for having gzipped man pages -- saving space. Here's how the |
| 94 |
-size of a program varies with and without debug symbol stripping. |
| 95 |
+program is to <c>emerge</c> the program with <c>FEATURES="nostrip"</c>. This |
| 96 |
+prevents the stripping of debug symbols. Why are programs stripped by default? |
| 97 |
+The reason is the same as that for having gzipped man pages -- saving space. |
| 98 |
+Here's how the size of a program varies with and without debug symbol stripping. |
| 99 |
</p> |
| 100 |
|
| 101 |
<pre caption="Filesize Comparison"> |
| 102 |
@@ -125,10 +125,19 @@ |
| 103 |
Just for reference, <e>bad_code</e> is the program we'll be debugging with |
| 104 |
<c>gdb</c> later on. As you can see, the program without debugging symbols is |
| 105 |
3140 bytes, while the program with them is 6374 bytes. That's close to double |
| 106 |
-the size! Two more things can be done for debugging. The first is adding -g to |
| 107 |
-your CFLAGS and CXXFLAGS. This flag adds more debugging information than is |
| 108 |
-generally included. We'll see what that means later on. Lastly, you can also add |
| 109 |
-debug to the package's USE flags. This can be done with the |
| 110 |
+the size! Two more things can be done for debugging. The first is adding ggdb3 |
| 111 |
+to your CFLAGS and CXXFLAGS. This flag adds more debugging information than is |
| 112 |
+generally included. We'll see what that means later on. This is how |
| 113 |
+<path>/etc/make.conf</path> <e>might</e> look with the newly added flags. |
| 114 |
+</p> |
| 115 |
+ |
| 116 |
+<pre caption="make.conf settings"> |
| 117 |
+CFLAGS="-O2 -pipe -gddb3" |
| 118 |
+CXXFLAGS="${CFLAGS}" |
| 119 |
+</pre> |
| 120 |
+ |
| 121 |
+<p> |
| 122 |
+Lastly, you can also add debug to the package's USE flags. This can be done with the |
| 123 |
<path>package.use</path> file. |
| 124 |
</p> |
| 125 |
|
| 126 |
@@ -144,8 +153,8 @@ |
| 127 |
</note> |
| 128 |
|
| 129 |
<p> |
| 130 |
-Now that that's done, you will need to re-emerge your package to set the |
| 131 |
-new debug settings into place. This can be done as follows: |
| 132 |
+Then we re-emerge the package with the modifications we've done so far as shown |
| 133 |
+below. |
| 134 |
</p> |
| 135 |
|
| 136 |
<pre caption="Re-emergeing a package with debugging"> |
| 137 |
@@ -163,9 +172,8 @@ |
| 138 |
<body> |
| 139 |
|
| 140 |
<p> |
| 141 |
-Let's say we have a program here called "bad_code" (I know, it's sort of cheesy |
| 142 |
-but..). Some person claims he can break the code and provides an example. You go |
| 143 |
-ahead and test it out: |
| 144 |
+Let's say we have a program here called "bad_code". Some person claims that the |
| 145 |
+program crashes and provides an example. You go ahead and test it out: |
| 146 |
</p> |
| 147 |
|
| 148 |
<pre caption="Breaking The Program"> |
| 149 |
@@ -191,14 +199,20 @@ |
| 150 |
This GDB was configured as "i686-pc-linux-gnu"...Using host libthread_db library "/lib/libthread_db.so.1". |
| 151 |
</pre> |
| 152 |
|
| 153 |
+<note> |
| 154 |
+One can also debug with core dumps. These core files contain the same |
| 155 |
+information that the program would produce when run with gdb. In order to debug |
| 156 |
+with a core file with bad_code, you would run <c>gdb ./bad_code core</c> where |
| 157 |
+core is the name of the core file. |
| 158 |
+</note> |
| 159 |
+ |
| 160 |
<p> |
| 161 |
-You should see a small terminal like setup after that which says "(gdb)" and |
| 162 |
-waits for input. First, we have to run the program. We type in <c>run</c> at the |
| 163 |
-command and receive a notice like: |
| 164 |
+You should see a prompt that says "(gdb)" and waits for input. First, we have to |
| 165 |
+run the program. We type in <c>run</c> at the command and receive a notice like: |
| 166 |
</p> |
| 167 |
|
| 168 |
<pre caption="Running the program in GDB"> |
| 169 |
-(gdb) run |
| 170 |
+(gdb) <i>run</i> |
| 171 |
Starting program: /home/chris/bad_code |
| 172 |
|
| 173 |
Program received signal SIGSEGV, Segmentation fault. |
| 174 |
@@ -219,22 +233,23 @@ |
| 175 |
</p> |
| 176 |
|
| 177 |
<pre caption="Program backtrace"> |
| 178 |
-(gdb) bt |
| 179 |
+(gdb) <i>bt</i> |
| 180 |
#0 0xb7ec6dc0 in strcpy () from /lib/libc.so.6 |
| 181 |
#1 0x0804838c in run_it () |
| 182 |
#2 0x080483ba in main () |
| 183 |
</pre> |
| 184 |
|
| 185 |
<p> |
| 186 |
-So as we see here, first main() was run, then run_it(), and somewhere in run_it |
| 187 |
-lies the strcpy() at fault. Things such as this help developers narrow things |
| 188 |
-down. Now, there are a few exceptions to the output. First off is forgetting |
| 189 |
-to disable debug symbols with FEATURES="nostrip". With debug symbols stripped, |
| 190 |
-output looks something like this: |
| 191 |
+You can notice the trace pattern clearly. main() is called first, followed by |
| 192 |
+run_it(), and somewhere in run_it() lies the strcpy() at fault. Things such as |
| 193 |
+this help developers narrow down problems. There are a few exceptions to the |
| 194 |
+output. First off is forgetting to enable debug symbols with |
| 195 |
+<c>FEATURES="nostrip"</c>. With debug symbols stripped, the output looks something |
| 196 |
+like this: |
| 197 |
</p> |
| 198 |
|
| 199 |
<pre caption="Program backtrace With debug symbols stripped"> |
| 200 |
-(gdb) bt |
| 201 |
+(gdb) <i>bt</i> |
| 202 |
#0 0xb7e2cdc0 in strcpy () from /lib/libc.so.6 |
| 203 |
#1 0x0804838c in ?? () |
| 204 |
#2 0xbfd19510 in ?? () |
| 205 |
@@ -264,13 +279,14 @@ |
| 206 |
|
| 207 |
<p> |
| 208 |
This backtrace contains a large number of ?? marks. This is because without |
| 209 |
-debug symbols, <c>gdb</c> doesn't know how the program was ran. Hence, it is |
| 210 |
-crucial that debug symbols are <e>not</e> stripped. Now remember a while ago I |
| 211 |
-told you about the -g flag. Let's see what the output looks like with that: |
| 212 |
+debug symbols, <c>gdb</c> doesn't know how the program was run. Hence, it is |
| 213 |
|
| 214 |
|
| 215 |
|
| 216 |
-- |
| 217 |
gentoo-doc-cvs@g.o mailing list |
Archives