/[gentoo]/xml/htdocs/doc/en/bugzilla-howto.xml
Gentoo

Diff of /xml/htdocs/doc/en/bugzilla-howto.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.2 Revision 1.3
1<?xml version="1.0" encoding="UTF-8"?> 1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.2 2005/07/07 18:19:23 fox2mike Exp $ --> 3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.3 2005/07/09 22:31:57 fox2mike Exp $ -->
4 4
5<guide link="/doc/en/bugzilla-howto.xml"> 5<guide link="/doc/en/bugzilla-howto.xml">
6<title>Gentoo Bug Reporting Guide</title> 6<title>Gentoo Bug Reporting Guide</title>
7 7
8<author title="Author"> 8<author title="Author">
9 <mail link="chriswhite@gentoo.org">Chris White</mail> 9 <mail link="chriswhite@gentoo.org">Chris White</mail>
10</author> 10</author>
11<author title="Editor"> 11<author title="Editor">
12 <mail link="fox2mike@gentoo.org">Shyam Mani</mail> 12 <mail link="fox2mike@gentoo.org">Shyam Mani</mail>
13</author> 13</author>
14 14
15<abstract> 15<abstract>
16This document shows the proper method of reporting bugs using Bugzilla. 16This document shows the proper method of reporting bugs using Bugzilla.
17</abstract> 17</abstract>
18 18
19<!-- The content of this document is licensed under the CC-BY-SA license --> 19<!-- The content of this document is licensed under the CC-BY-SA license -->
20<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> 20<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
21<license/> 21<license/>
22 22
23<version>1.1</version> 23<version>1.2</version>
24<date>2005-07-07</date> 24<date>2005-07-10</date>
25 25
26<chapter> 26<chapter>
27<title>Introduction</title> 27<title>Introduction</title>
28<section> 28<section>
29<title>Preface</title> 29<title>Preface</title>
30<body> 30<body>
31 31
32<p> 32<p>
33Often one of the factors that delay a bug being fixed is how it is reported. By 33One of the factors that delay a bug being fixed is the way it is reported. By
34creating this guide, I hope to help improve the communication between 34creating this guide, we hope to help improve the communication between
35developers and users in bug resolution. Getting bugs fixed is an important, if 35developers and users in bug resolution. Getting bugs fixed is an important, if
36not crucial part of the quality assurance of any project and hopefully this 36not crucial part of the quality assurance for any project and hopefully this
37guide will help make that a success. 37guide will help make that a success.
38</p> 38</p>
39 39
40</body> 40</body>
41</section> 41</section>
42<section> 42<section>
43<title>Initial Finding</title> 43<title>Bugs!!!!</title>
44<body> 44<body>
45 45
46<p> 46<p>
47You're emerge-ing a package or working with a program, then suddenly the worst 47You're emerge-ing a package or working with a program and suddenly the worst
48happens -- you find a bug. Bugs come in many forms, whether it be emerge 48happens -- you find a bug. Bugs come in many forms like emerge failures or
49failures or segmentation faults. Whatever the cause, the fact still remains that 49segmentation faults. Whatever the cause, the fact still remains that such a bug
50such a bug must be fixed. Here is a few examples of such bugs. 50must be fixed. Here is a few examples of such bugs.
51</p> 51</p>
52 52
53<pre caption="A run time error"> 53<pre caption="A run time error">
54$ <i>./bad_code `perl -e 'print Ax100'`</i> 54$ <i>./bad_code `perl -e 'print Ax100'`</i>
55Segmentation fault 55Segmentation fault
56</pre> 56</pre>
57 57
58<pre caption="An emerge failure"> 58<pre caption="An emerge failure">
59/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.2/include/g++-v3/backward/backward_warning.h:32:2: 59/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.2/include/g++-v3/backward/backward_warning.h:32:2:
60warning: #warning This file includes at least one deprecated or antiquated 60warning: #warning This file includes at least one deprecated or antiquated
61header. Please consider using one of the 32 headers found in section 17.4.1.2 of 61header. Please consider using one of the 32 headers found in section 17.4.1.2 of
62the C++ standard. Examples include substituting the &lt;X&gt; header for the &lt;X.h&gt; 62the C++ standard. Examples include substituting the &lt;X&gt; header for the &lt;X.h&gt;
63header for C++ includes, or &lt;sstream&gt; instead of the deprecated header 63header for C++ includes, or &lt;sstream&gt; instead of the deprecated header
64&lt;strstream.h&gt;. To disable this warning use -Wno-deprecated. 64&lt;strstream.h&gt;. To disable this warning use -Wno-deprecated.
65In file included from main.cc:40: 65In file included from main.cc:40:
75main.cc:323: warning: unused variable `FILE*fp' 75main.cc:323: warning: unused variable `FILE*fp'
76main.cc: In member function `void OXMain::DoSave(char*)': 76main.cc: In member function `void OXMain::DoSave(char*)':
77main.cc:337: warning: unused variable `FILE*fp' 77main.cc:337: warning: unused variable `FILE*fp'
78make[1]: *** [main.o] Error 1 78make[1]: *** [main.o] Error 1
79make[1]: Leaving directory 79make[1]: Leaving directory
80`/var/tmp/portage/xclass-0.7.4/work/xclass-0.7.4/example-app' 80`/var/tmp/portage/xclass-0.7.4/work/xclass-0.7.4/example-app'
81make: *** [shared] Error 2 81make: *** [shared] Error 2
82 82
83!!! ERROR: x11-libs/xclass-0.7.4 failed. 83!!! ERROR: x11-libs/xclass-0.7.4 failed.
84!!! Function src_compile, Line 29, Exitcode 2 84!!! Function src_compile, Line 29, Exitcode 2
85!!! 'emake shared' failed 85!!! 'emake shared' failed
86</pre> 86</pre>
87 87
88<p> 88<p>
89These errors can be quite troublesome. However, once you find them, what do 89These errors can be quite troublesome. However, once you find them, what do
90you do? The following sections will look at 2 important tools for handling 90you do? The following sections will look at two important tools for handling
91run time errors. After that, we'll take a look at compile errors, and how to 91run time errors. After that, we'll take a look at compile errors, and how to
92handle them. Let's start out with the first tool for debugging run time 92handle them. Let's start out with the first tool for debugging run time
93errors -- <c>gdb</c> 93errors -- <c>gdb</c>.
94</p> 94</p>
95 95
96</body> 96</body>
97</section> 97</section>
98</chapter> 98</chapter>
99 99
100 100
101<chapter> 101<chapter>
102<title>Debugging using GDB</title> 102<title>Debugging using GDB</title>
103<section> 103<section>
104<title>Introduction</title> 104<title>Introduction</title>
105<body> 105<body>
106 106
107<p> 107<p>
108GDB, or the (G)NU (D)e(B)ugger, is a program used to find run time errors that 108GDB, or the (G)NU (D)e(B)ugger, is a program used to find run time errors that
109normally involve memory corruption. First off, let's take a look at what 109normally involve memory corruption. First off, let's take a look at what
110debugging entails. One of the main things you must do in order to debug a 110debugging entails. One of the main things you must do in order to debug a
111program is to <c>emerge</c> the program with FEATURES="nostrip". This prevents 111program is to <c>emerge</c> the program with <c>FEATURES="nostrip"</c>. This
112the stripping of debug symbols. Why are programs stripped by default? The reason 112prevents the stripping of debug symbols. Why are programs stripped by default?
113is the same as that for having gzipped man pages -- saving space. Here's how the 113The reason is the same as that for having gzipped man pages -- saving space.
114size of a program varies with and without debug symbol stripping. 114Here's how the size of a program varies with and without debug symbol stripping.
115</p> 115</p>
116 116
117<pre caption="Filesize Comparison"> 117<pre caption="Filesize Comparison">
118<comment>(debug symbols stripped)</comment> 118<comment>(debug symbols stripped)</comment>
119-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code 119-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code
120<comment>(debug symbols intact)</comment> 120<comment>(debug symbols intact)</comment>
121-rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code 121-rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code
122</pre> 122</pre>
123 123
124<p> 124<p>
125Just for reference, <e>bad_code</e> is the program we'll be debugging with 125Just for reference, <e>bad_code</e> is the program we'll be debugging with
126<c>gdb</c> later on. As you can see, the program without debugging symbols is 126<c>gdb</c> later on. As you can see, the program without debugging symbols is
1273140 bytes, while the program with them is 6374 bytes. That's close to double 1273140 bytes, while the program with them is 6374 bytes. That's close to double
128the size! Two more things can be done for debugging. The first is adding -g to 128the size! Two more things can be done for debugging. The first is adding ggdb3
129your CFLAGS and CXXFLAGS. This flag adds more debugging information than is 129to your CFLAGS and CXXFLAGS. This flag adds more debugging information than is
130generally included. We'll see what that means later on. Lastly, you can also add 130generally included. We'll see what that means later on. This is how
131<path>/etc/make.conf</path> <e>might</e> look with the newly added flags.
132</p>
133
134<pre caption="make.conf settings">
135CFLAGS="-O2 -pipe -gddb3"
136CXXFLAGS="${CFLAGS}"
137</pre>
138
139<p>
131debug to the package's USE flags. This can be done with the 140Lastly, you can also add debug to the package's USE flags. This can be done with the
132<path>package.use</path> file. 141<path>package.use</path> file.
133</p> 142</p>
134 143
135<pre caption="Using package.use to add debug USE flag"> 144<pre caption="Using package.use to add debug USE flag">
136# <i>echo "category/package debug" >> /etc/portage/package.use</i> 145# <i>echo "category/package debug" >> /etc/portage/package.use</i>
137</pre> 146</pre>
138 147
139<note> 148<note>
140The directory <path>/etc/portage</path> does not exist by default and you may 149The directory <path>/etc/portage</path> does not exist by default and you may
141have to create it, if you have not already done so. If the package already has 150have to create it, if you have not already done so. If the package already has
142USE flags set in <path>package.use</path>, you will need to manually modify them 151USE flags set in <path>package.use</path>, you will need to manually modify them
143in your favorite editor. 152in your favorite editor.
144</note> 153</note>
145 154
146<p> 155<p>
147Now that that's done, you will need to re-emerge your package to set the 156Then we re-emerge the package with the modifications we've done so far as shown
148new debug settings into place. This can be done as follows: 157below.
149</p> 158</p>
150 159
151<pre caption="Re-emergeing a package with debugging"> 160<pre caption="Re-emergeing a package with debugging">
152# <i>FEATURES="nostrip" emerge package</i> 161# <i>FEATURES="nostrip" emerge package</i>
153</pre> 162</pre>
154 163
155<p> 164<p>
156Now that debug symbols are setup, we can continue with debugging the program. 165Now that debug symbols are setup, we can continue with debugging the program.
157</p> 166</p>
158 167
159</body> 168</body>
160</section> 169</section>
161<section> 170<section>
162<title>Running the program with GDB</title> 171<title>Running the program with GDB</title>
163<body> 172<body>
164 173
165<p> 174<p>
166Let's say we have a program here called "bad_code" (I know, it's sort of cheesy 175Let's say we have a program here called "bad_code". Some person claims that the
167but..). Some person claims he can break the code and provides an example. You go 176program crashes and provides an example. You go ahead and test it out:
168ahead and test it out:
169</p> 177</p>
170 178
171<pre caption="Breaking The Program"> 179<pre caption="Breaking The Program">
172$ <i>./bad_code `perl -e 'print Ax100'`</i> 180$ <i>./bad_code `perl -e 'print Ax100'`</i>
173Segmentation fault 181Segmentation fault
174</pre> 182</pre>
175 183
176<p> 184<p>
177It seems this person was right. Since the program is obviously broken, we have 185It seems this person was right. Since the program is obviously broken, we have
178a bug at hand. Now, it's time to use <c>gdb</c> to help solve this matter. First 186a bug at hand. Now, it's time to use <c>gdb</c> to help solve this matter. First
179we run <c>gdb</c> with <c>--args</c>, then give it the full program with 187we run <c>gdb</c> with <c>--args</c>, then give it the full program with
180arguments like shown: 188arguments like shown:
181</p> 189</p>
182 190
183<pre caption="Running Our Program Through GDB"> 191<pre caption="Running Our Program Through GDB">
184$ <i>gdb --args ./bad_code `perl -e 'print Ax100'`</i> 192$ <i>gdb --args ./bad_code `perl -e 'print Ax100'`</i>
185GNU gdb 6.3 193GNU gdb 6.3
186Copyright 2004 Free Software Foundation, Inc. 194Copyright 2004 Free Software Foundation, Inc.
187GDB is free software, covered by the GNU General Public License, and you are 195GDB is free software, covered by the GNU General Public License, and you are
188welcome to change it and/or distribute copies of it under certain conditions. 196welcome to change it and/or distribute copies of it under certain conditions.
189Type "show copying" to see the conditions. 197Type "show copying" to see the conditions.
190There is absolutely no warranty for GDB. Type "show warranty" for details. 198There is absolutely no warranty for GDB. Type "show warranty" for details.
191This GDB was configured as "i686-pc-linux-gnu"...Using host libthread_db library "/lib/libthread_db.so.1". 199This GDB was configured as "i686-pc-linux-gnu"...Using host libthread_db library "/lib/libthread_db.so.1".
192</pre> 200</pre>
193 201
202<note>
203One can also debug with core dumps. These core files contain the same
204information that the program would produce when run with gdb. In order to debug
205with a core file with bad_code, you would run <c>gdb ./bad_code core</c> where
206core is the name of the core file.
207</note>
208
194<p> 209<p>
195You should see a small terminal like setup after that which says "(gdb)" and 210You should see a prompt that says "(gdb)" and waits for input. First, we have to
196waits for input. First, we have to run the program. We type in <c>run</c> at the 211run the program. We type in <c>run</c> at the command and receive a notice like:
197command and receive a notice like:
198</p> 212</p>
199 213
200<pre caption="Running the program in GDB"> 214<pre caption="Running the program in GDB">
201(gdb) run 215(gdb) <i>run</i>
202Starting program: /home/chris/bad_code 216Starting program: /home/chris/bad_code
203 217
204Program received signal SIGSEGV, Segmentation fault. 218Program received signal SIGSEGV, Segmentation fault.
2050xb7ec6dc0 in strcpy () from /lib/libc.so.6 2190xb7ec6dc0 in strcpy () from /lib/libc.so.6
206</pre> 220</pre>
207 221
208<p> 222<p>
209Here we see the program starting, as well as a notification of SIGSEGV, or 223Here we see the program starting, as well as a notification of SIGSEGV, or
210Segmentation Fault. This is GDB telling us that our program has crashed. It 224Segmentation Fault. This is GDB telling us that our program has crashed. It
211also gives the last run function it could trace when the program crashes. 225also gives the last run function it could trace when the program crashes.
212However, this isn't too useful, as there could be multiple strcpy's in the 226However, this isn't too useful, as there could be multiple strcpy's in the
213program, making it hard for developers to find which one is causing the issue. 227program, making it hard for developers to find which one is causing the issue.
214In order to help them out, we do what's called a backtrace. A backtrace runs 228In order to help them out, we do what's called a backtrace. A backtrace runs
215backwards through all the functions that occurred upon program execution, to the 229backwards through all the functions that occurred upon program execution, to the
216function at fault. Functions that return (without causing a crash) will not show 230function at fault. Functions that return (without causing a crash) will not show
217up on the backtrace. To get a backtrace, at the (gdb) prompt, type in <c>bt</c>. 231up on the backtrace. To get a backtrace, at the (gdb) prompt, type in <c>bt</c>.
218You will get something like this: 232You will get something like this:
219</p> 233</p>
220 234
221<pre caption="Program backtrace"> 235<pre caption="Program backtrace">
222(gdb) bt 236(gdb) <i>bt</i>
223#0 0xb7ec6dc0 in strcpy () from /lib/libc.so.6 237#0 0xb7ec6dc0 in strcpy () from /lib/libc.so.6
224#1 0x0804838c in run_it () 238#1 0x0804838c in run_it ()
225#2 0x080483ba in main () 239#2 0x080483ba in main ()
226</pre> 240</pre>
227 241
228<p> 242<p>
229So as we see here, first main() was run, then run_it(), and somewhere in run_it 243You can notice the trace pattern clearly. main() is called first, followed by
230lies the strcpy() at fault. Things such as this help developers narrow things 244run_it(), and somewhere in run_it() lies the strcpy() at fault. Things such as
231down. Now, there are a few exceptions to the output. First off is forgetting 245this help developers narrow down problems. There are a few exceptions to the
232to disable debug symbols with FEATURES="nostrip". With debug symbols stripped, 246output. First off is forgetting to enable debug symbols with
233output looks something like this: 247<c>FEATURES="nostrip"</c>. With debug symbols stripped, the output looks something
248like this:
234</p> 249</p>
235 250
236<pre caption="Program backtrace With debug symbols stripped"> 251<pre caption="Program backtrace With debug symbols stripped">
237(gdb) bt 252(gdb) <i>bt</i>
238#0 0xb7e2cdc0 in strcpy () from /lib/libc.so.6 253#0 0xb7e2cdc0 in strcpy () from /lib/libc.so.6
239#1 0x0804838c in ?? () 254#1 0x0804838c in ?? ()
240#2 0xbfd19510 in ?? () 255#2 0xbfd19510 in ?? ()
241#3 0x00000000 in ?? () 256#3 0x00000000 in ?? ()
242#4 0x00000000 in ?? () 257#4 0x00000000 in ?? ()
243#5 0xb7eef148 in libgcc_s_personality () from /lib/libc.so.6 258#5 0xb7eef148 in libgcc_s_personality () from /lib/libc.so.6
244#6 0x080482ed in ?? () 259#6 0x080482ed in ?? ()
245#7 0x080495b0 in ?? () 260#7 0x080495b0 in ?? ()
246#8 0xbfd19528 in ?? () 261#8 0xbfd19528 in ?? ()
247#9 0xb7dd73b8 in __guard_setup () from /lib/libc.so.6 262#9 0xb7dd73b8 in __guard_setup () from /lib/libc.so.6
248#10 0xb7dd742d in __guard_setup () from /lib/libc.so.6 263#10 0xb7dd742d in __guard_setup () from /lib/libc.so.6
249#11 0x00000006 in ?? () 264#11 0x00000006 in ?? ()
250#12 0xbfd19548 in ?? () 265#12 0xbfd19548 in ?? ()
251#13 0x080483ba in ?? () 266#13 0x080483ba in ?? ()
252#14 0x00000000 in ?? () 267#14 0x00000000 in ?? ()
253#15 0x00000000 in ?? () 268#15 0x00000000 in ?? ()
254#16 0xb7deebcc in __new_exitfn () from /lib/libc.so.6 269#16 0xb7deebcc in __new_exitfn () from /lib/libc.so.6
255#17 0x00000000 in ?? () 270#17 0x00000000 in ?? ()
256#18 0xbfd19560 in ?? () 271#18 0xbfd19560 in ?? ()
257#19 0xb7ef017c in nullserv () from /lib/libc.so.6 272#19 0xb7ef017c in nullserv () from /lib/libc.so.6
258#20 0xb7dd6f37 in __libc_start_main () from /lib/libc.so.6 273#20 0xb7dd6f37 in __libc_start_main () from /lib/libc.so.6
259#21 0x00000001 in ?? () 274#21 0x00000001 in ?? ()
260#22 0xbfd195d4 in ?? () 275#22 0xbfd195d4 in ?? ()
261#23 0xbfd195dc in ?? () 276#23 0xbfd195dc in ?? ()
262#24 0x08048201 in ?? () 277#24 0x08048201 in ?? ()
263</pre> 278</pre>
264 279
265<p> 280<p>
266This backtrace contains a large number of ?? marks. This is because without 281This backtrace contains a large number of ?? marks. This is because without
267debug symbols, <c>gdb</c> doesn't know how the program was ran. Hence, it is 282debug symbols, <c>gdb</c> doesn't know how the program was run. Hence, it is
268crucial that debug symbols are <e>not</e> stripped. Now remember a while ago I 283crucial that debug symbols are <e>not</e> stripped. Now remember a while ago we
269told you about the -g flag. Let's see what the output looks like with that: 284mentioned the -ggdb3 flag. Let's see what the output looks like with the flag
285enabled:
270</p> 286</p>
271 287
272<pre caption="Program backtrace with -g flag"> 288<pre caption="Program backtrace with -ggdb3">
273(gdb) bt 289(gdb) <i>bt</i>
274#0 0xb7e4bdc0 in strcpy () from /lib/libc.so.6 290#0 0xb7e4bdc0 in strcpy () from /lib/libc.so.6
275#1 0x0804838c in run_it (input=0x0) at bad_code.c:7 291#1 0x0804838c in run_it (input=0x0) at bad_code.c:7
276#2 0x080483ba in main (argc=1, argv=0xbfd3a434) at bad_code.c:12 292#2 0x080483ba in main (argc=1, argv=0xbfd3a434) at bad_code.c:12
277</pre> 293</pre>
278 294
279<p> 295<p>
280Here we see that a lot more information is available for developers. Not only is 296Here we see that a lot more information is available for developers. Not only is
281variable information displayed, but even the exact line numbers of the source 297function information displayed, but even the exact line numbers of the source
282files. This method is the most preferred if you can spare the extra space. 298files. This method is the most preferred if you can spare the extra space.
283Here's how much the file size varies between debug, strip, and -g programs. 299Here's how much the file size varies between debug, strip, and -ggdb3 enabled
300programs.
284</p> 301</p>
285 302
286<pre caption="Filesize differences With -g flag"> 303<pre caption="Filesize differences With -ggdb3 flag">
287<comment>(debug symbols stripped)</comment> 304<comment>(debug symbols stripped)</comment>
288-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code 305-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code
289<comment>(debug symbols enabled)</comment> 306<comment>(debug symbols enabled)</comment>
290-rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code 307-rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code
291<comment>(-g flag enabled)</comment> 308<comment>(-ggdb3 flag enabled)</comment>
292-rwxr-xr-x 1 chris users 7366 6/28 13:11 bad_code 309-rwxr-xr-x 1 chris users 19552 6/28 13:11 bad_code
293</pre> 310</pre>
294 311
295<p> 312<p>
296As you can see, -g adds about a 1000 more bytes to the file size over the one 313As you can see, -ggdb3 adds about <e>13178</e> more bytes to the file size over the one
297with debugging symbols. However, as shown above, this increase in file size can 314with debugging symbols. However, as shown above, this increase in file size can
298be worth it if presenting debug information to developers. Now that we have 315be worth it if presenting debug information to developers. The backtrace, can be
299obtained the backtrace, we can save it to a file by copying and pasting from the 316saved to a file by copying and pasting from the terminal (if it's a non-x based
300terminal (if it's a non-x based terminal, you can use gpm. To keep this doc 317terminal, you can use gpm. To keep this doc simple, I recommend you read up on
301simple, I recommend you read up on the documentation for gpm to see how to copy 318the documentation for gpm to see how to copy and paste with it). Now that we're
302and paste with it). Now that we're done with <c>gdb</c>, we can quit. 319done with <c>gdb</c>, we can quit.
303</p> 320</p>
304 321
305<pre caption="Quitting GDB"> 322<pre caption="Quitting GDB">
306(gdb) quit 323(gdb) <i>quit</i>
307The program is running. Exit anyway? (y or n) y 324The program is running. Exit anyway? (y or n) <i>y</i>
308$ 325$
309</pre> 326</pre>
310 327
311<p> 328<p>
312This ends the walk-through of <c>gdb</c>. Using <c>gdb</c>, I hope that you will 329This ends the walk-through of <c>gdb</c>. Using <c>gdb</c>, we hope that you will
313be able to use it to create better bug reports. However, there are other types 330be able to use it to create better bug reports. However, there are other types
314of errors that can cause a program to fail during run time. One of the other 331of errors that can cause a program to fail during run time. One of the other
315ways is through improper file access. We can find those using a nifty little 332ways is through improper file access. We can find those using a nifty little
316tool called <c>strace</c>. 333tool called <c>strace</c>.
317</p> 334</p>
318 335
319</body> 336</body>
320</section> 337</section>
321</chapter> 338</chapter>
322 339
323<chapter> 340<chapter>
324<title>Finding file access errors using strace</title> 341<title>Finding file access errors using strace</title>
325<section> 342<section>
326<title>Introduction</title> 343<title>Introduction</title>
327<body> 344<body>
328 345
329<p> 346<p>
330Programs often use files to get configuration information, get access 347Programs often use files to fetch configuration information, access hardware or
331to hardware, or write logs. Often a program attempts to reach such files 348write logs. Sometimes, a program attempts to reach such files incorrectly. A
332incorrectly. A program called <c>strace</c> was created to help deal with 349tool called <c>strace</c> was created to help deal with this. <c>strace</c>
333this. <c>strace</c> traces system calls (hence the name) which include 350traces system calls (hence the name) which include calls that use the memory and
334calls that use the memory and files. For our example, we're going to take a 351files. For our example, we're going to take a program foobar2. This is an
335program foobar2. This is an updated version of foobar. However, during the 352updated version of foobar. However, during the change over to foobar2, you notice
336changeover to foobar2, you notice all your configurations are missing! In 353all your configurations are missing! In foobar version 1, you had it setup to
337foobar version 1, you had it setup to say "foo", but now it's using the default 354say "foo", but now it's using the default "bar".
338"bar".
339</p> 355</p>
340 356
341<pre caption="Foobar2 With an invalid configuration"> 357<pre caption="Foobar2 With an invalid configuration">
342$ <i>./foobar2</i> 358$ <i>./foobar2</i>
343Configuration says: bar 359Configuration says: bar
344</pre> 360</pre>
345 361
346<p> 362<p>
347Our previous configuration specifically had it set to foo, so let's use 363Our previous configuration specifically had it set to foo, so let's use
348<c>strace</c> to find out what's going on. 364<c>strace</c> to find out what's going on.
349</p> 365</p>
350 366
351</body> 367</body>
352</section> 368</section>
353<section> 369<section>
354<title>Using strace to track the issue</title> 370<title>Using strace to track the issue</title>
355<body> 371<body>
356 372
357<p> 373<p>
358Let's have <c>strace</c> log the results of the system calls. To do this, we run 374We make <c>strace</c> log the results of the system calls. To do this, we run
359<c>strace</c> with the -o[file] arguments. Let's use it on foobar2 like so: 375<c>strace</c> with the -o[file] arguments. Let's use it on foobar2 as shown.
360</p> 376</p>
361 377
362<pre caption="Running foobar2 through strace"> 378<pre caption="Running foobar2 through strace">
363# <i>strace -ostrace.log ./foobar2</i> 379# <i>strace -ostrace.log ./foobar2</i>
364</pre> 380</pre>
365 381
366<p> 382<p>
367This creates a file called <path>strace.log</path> in the current directory. We 383This creates a file called <path>strace.log</path> in the current directory. We
368check the file, and shown below are the relevant parts from the file. 384check the file, and shown below are the relevant parts from the file.
369</p> 385</p>
370 386
371<pre caption="A Look At the strace Log"> 387<pre caption="A Look At the strace Log">
372open(".foobar2/config", O_RDONLY) = 3 388open(".foobar2/config", O_RDONLY) = 3
373read(3, "bar", 3) = 3 389read(3, "bar", 3) = 3
374</pre> 390</pre>
379reading in "bar" as it should. In this case, we can recommend the ebuild 395reading in "bar" as it should. In this case, we can recommend the ebuild
380maintainer to put a warning about it. For now though, we can copy over the 396maintainer to put a warning about it. For now though, we can copy over the
381config file from <path>.foobar</path> and modify it to produce the correct 397config file from <path>.foobar</path> and modify it to produce the correct
382results. 398results.
383</p> 399</p>
384 400
385</body> 401</body>
386</section> 402</section>
387<section> 403<section>
388<title>Conclusion</title> 404<title>Conclusion</title>
389<body> 405<body>
390 406
391<p> 407<p>
392Now we've taken care of finding run time bugs. These bugs prove to be 408Now we've taken care of finding run time bugs. These bugs prove to be
393problematic when you try and run your programs. However, run time errors are 409problematic when you try and run your programs. However, run time errors are
394the least of your concern if your program won't compile at all. Let's take a 410the least of your concerns if your program won't compile at all. Let's take a
395look at how to address <c>emerge</c> compile errors. 411look at how to address <c>emerge</c> compile errors.
396</p> 412</p>
397 413
398</body> 414</body>
399</section> 415</section>
400</chapter> 416</chapter>
401 417
402<chapter> 418<chapter>
403<title>Handling emerge Errors</title> 419<title>Handling emerge Errors</title>
404<section> 420<section>
405<title>Introduction</title> 421<title>Introduction</title>
406<body> 422<body>
407 423
408<p> 424<p>
409<c>emerge</c> errors, such as the one displayed earlier, can be a major cause 425<c>emerge</c> errors, such as the one displayed earlier, can be a major cause
410of frustration for users. Reporting them is considered crucial for helping 426of frustration for users. Reporting them is considered crucial for maintaining
411maintain the health of Gentoo. Let's take a look at a sample ebuild, foobar2, 427the health of Gentoo. Let's take a look at a sample ebuild, foobar2, which
412which contains some build errors. 428contains some build errors.
413</p> 429</p>
414 430
415</body> 431</body>
416</section> 432</section>
417<section id="emerge_error"> 433<section id="emerge_error">
418<title>Evaluating emerge Errors</title> 434<title>Evaluating emerge Errors</title>
419<body> 435<body>
420 436
421<p> 437<p>
422Let's take a look at this very simple <c>emerge</c> error: 438Let's take a look at this very simple <c>emerge</c> error:
423</p> 439</p>
424 440
425<pre caption="emerge Error"> 441<pre caption="emerge Error">
426gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-7.o foobar2-7.c 442gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-7.o foobar2-7.c
427gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-8.o foobar2-8.c 443gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-8.o foobar2-8.c
428gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-9.o foobar2-9.c 444gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-9.o foobar2-9.c
429gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2.o foobar2.c 445gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2.o foobar2.c
430foobar2.c:1:17: ogg.h: No such file or directory 446foobar2.c:1:17: ogg.h: No such file or directory
431make: *** [foobar2.o] Error 1 447make: *** [foobar2.o] Error 1
432 448
433!!! ERROR: sys-apps/foobar2-1.0 failed. 449!!! ERROR: sys-apps/foobar2-1.0 failed.
434!!! Function src_compile, Line 19, Exitcode 2 450!!! Function src_compile, Line 19, Exitcode 2
435!!! Make failed! 451!!! Make failed!
436!!! If you need support, post the topmost build error, NOT this status message 452!!! If you need support, post the topmost build error, NOT this status message
437</pre> 453</pre>
438 454
439<p> 455<p>
440The compile is going smoothly, then it stops and presents an error message. This 456The program is compiling smoothly when it suddenly stops and presents an error message. This
441particular error can be split into 3 different sections, The compile, the build 457particular error can be split into 3 different sections, The compile messages, the build
442error, and the emerge error message as shown below. 458error, and the emerge error message as shown below.
443</p> 459</p>
444 460
445<pre caption="Parts of the error"> 461<pre caption="Parts of the error">
446<comment>(Compile Error)</comment> 462<comment>(Compilation Messages)</comment>
447gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-7.o foobar2-7.c 463gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-7.o foobar2-7.c
448gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-8.o foobar2-8.c 464gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-8.o foobar2-8.c
449gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-9.o foobar2-9.c 465gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2-9.o foobar2-9.c
450gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2.o foobar2.c 466gcc -D__TEST__ -D__GNU__ -D__LINUX__ -L/usr/lib -I/usr/include -L/usr/lib/nspr/ -I/usr/include/fmod -c -o foobar2.o foobar2.c
451 467
452<comment>(Build Error)</comment> 468<comment>(Build Error)</comment>
453foobar2.c:1:17: ogg.h: No such file or directory 469foobar2.c:1:17: ogg.h: No such file or directory
454make: *** [foobar2.o] Error 1 470make: *** [foobar2.o] Error 1
455 471
456<comment>(Emerge Error)</comment> 472<comment>(emerge Error)</comment>
457!!! ERROR: sys-apps/foobar2-1.0 failed. 473!!! ERROR: sys-apps/foobar2-1.0 failed.
458!!! Function src_compile, Line 19, Exitcode 2 474!!! Function src_compile, Line 19, Exitcode 2
459!!! Make failed! 475!!! Make failed!
460!!! If you need support, post the topmost build error, NOT this status message 476!!! If you need support, post the topmost build error, NOT this status message
461</pre> 477</pre>
462 478
463<p> 479<p>
464The compile is what leads up to the error. Most often, it's good to at least 480The compilation messages are what lead up to the error. Most often, it's good to
465include 10 lines of compile information so that the developer knows where the 481at least include 10 lines of compile information so that the developer knows
466compile is at. Make errors are the actual error, and the information the 482where the compilation was at when the error occurred.
467developer needs. When you see "make: ***", this is often where the error has 483</p>
468occurred. Normally, you can copy and paste 10 lines above it and the developer 484
469will be able to address the issue. However, this may not always work and we'll 485<p>
470take a look at an alternative shortly. The emerge error is what <c>emerge</c> 486Make errors are the actual error and the information the developer needs. When
471can address from the make error. Often people make the mistake of posting the 487you see "make: ***", this is often where the error has occurred. Normally, you
488can copy and paste 10 lines above it and the developer will be able to address
489the issue. However, this may not always work and we'll take a look at an
490alternative shortly.
491</p>
492
493<p>
494The emerge error is what <c>emerge</c> throws out as an error. Sometimes, this
495might also contain some important information. Often people make the mistake of
472emerge error and that's all. This is useless by itself, but with make error and 496posting the emerge error and that's all. This is useless by itself, but with
473compile information, a developer can get what application and what version of 497make error and compile information, a developer can get what application and
474the package is failing. As a side note, make is commonly used as the build 498what version of the package is failing. As a side note, make is commonly used as
475process for programs (<b>but not always</b>). If you can't find a "make: ***" 499the build process for programs (<b>but not always</b>). If you can't find a
476error anywhere, then simply copy and paste 20 lines before the emerge error. 500"make: ***" error anywhere, then simply copy and paste 20 lines before the
477This should take care of most all build system error messages. Now let's say the 501emerge error. This should take care of most all build system error messages. Now
478errors seem to be quite large. 10 lines won't be enough to catch everything. 502let's say the errors seem to be quite large. 10 lines won't be enough to catch
479That's where PORT_LOGDIR comes into play. 503everything. That's where PORT_LOGDIR comes into play.
480</p> 504</p>
481 505
482</body> 506</body>
483</section> 507</section>
484<section> 508<section>
485<title>emerge and PORT_LOGDIR</title> 509<title>emerge and PORT_LOGDIR</title>
486<body> 510<body>
487 511
488<p> 512<p>
489PORT_LOGDIR is a portage variable that sets up a log directory for separate 513PORT_LOGDIR is a portage variable that sets up a log directory for separate
490emerge logs. Let's take a look and see what that entails. First, run your emerge 514emerge logs. Let's take a look and see what that entails. First, run your emerge
491with PORT_LOGDIR set to your favorite log location. Let's say we have a 515with PORT_LOGDIR set to your favorite log location. Let's say we have a
492location /var/log/portage. We'll use that for our log directory: 516location <path>/var/log/portage</path>. We'll use that for our log directory:
493</p> 517</p>
494 518
495<note> 519<note>
496In the default setup, /var/log/portage does not exist, and you will most likely 520In the default setup, <path>/var/log/portage</path> does not exist, and you will
497have to create it. If you do not, portage will fail to write the logs. 521most likely have to create it. If you do not, portage will fail to write the
522logs.
498</note> 523</note>
499 524
500<pre caption="emerge-ing With PORT_LOGDIR"> 525<pre caption="emerge-ing With PORT_LOGDIR">
501# <i>PORT_LOGDIR=/var/log/portage emerge foobar2</i> 526# <i>PORT_LOGDIR=/var/log/portage emerge foobar2</i>
502</pre> 527</pre>
503 528
504<p> 529<p>
505Now the emerge fails again. However, this time we have a log we can work with, 530Now the emerge fails again. However, this time we have a log we can work with,
506and attach to the bug later on. Let's take a quick look at our log directory. 531and attach to the bug later on. Let's take a quick look at our log directory.
507</p> 532</p>
508 533
509<pre caption="PORT_LOGDIR Contents"> 534<pre caption="PORT_LOGDIR Contents">
510# <i>ls -la /var/log/portage</i> 535# <i>ls -la /var/log/portage</i>
511total 16 536total 16
512drwxrws--- 2 root root 4096 Jun 30 10:08 . 537drwxrws--- 2 root root 4096 Jun 30 10:08 .
527 552
528</body> 553</body>
529</section> 554</section>
530</chapter> 555</chapter>
531 556
532<chapter> 557<chapter>
533<title>Searching Using Bugzilla</title> 558<title>Searching Using Bugzilla</title>
534<section> 559<section>
535<title>Introduction</title> 560<title>Introduction</title>
536<body> 561<body>
537 562
538<p> 563<p>
539<uri link="http://www.bugzilla.org">Bugzilla</uri> is what we at Gentoo use to 564<uri link="http://www.bugzilla.org">Bugzilla</uri> is what we at Gentoo use to
540handle bugs. Gentoo's Bugzilla is reachable by HTTPS and HTTP. HTTPS is 565handle bugs. Gentoo's Bugzilla is reachable by HTTPS and HTTP. HTTPS is
541available for those on insecure networks or simply paranoid :). For the sake of 566available for those on insecure networks or simply paranoid :). For the sake of
542consistency, I will be using the HTTPS version in the examples to follow. Head 567consistency, we will be using the HTTPS version in the examples to follow. Head
543over to <uri link="https://bugs.gentoo.org">Gentoo Bugs</uri> to see how it 568over to <uri link="https://bugs.gentoo.org">Gentoo Bugs</uri> to see how it
544looks. 569looks.
545</p> 570</p>
546 571
547<p> 572<p>
548One of the most frustrating thing for developers and bug-wranglers is finding 573One of the most frustrating things for developers and bug-wranglers is finding
549duplicate bug reports. This causes them valuable time they could be using to 574duplicate bug reports. These cost them valuable time that they could otherwise
550find new and more important bugs. Often, this can be prevented by a few simple 575use to work on more important bugs. Often, this can be prevented by a few simple
551search methods. So we're going to see how to search for bugs and find out if 576search methods. So we're going to see how to search for bugs and find out if
552you have one that's similar. For this example, we're going to use the xclass 577you have one that's similar. For this example, we're going to use the xclass
553emerge error that was used earlier: 578emerge error that was used earlier.
554</p> 579</p>
555 580
556<pre caption="xclass emerge error"> 581<pre caption="xclass emerge error">
557/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.2/include/g++-v3/backward/backward_warning.h:32:2: 582/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.2/include/g++-v3/backward/backward_warning.h:32:2:
558warning: #warning This file includes at least one deprecated or antiquated 583warning: #warning This file includes at least one deprecated or antiquated
559header. Please consider using one of the 32 headers found in section 17.4.1.2 of 584header. Please consider using one of the 32 headers found in section 17.4.1.2 of
560the C++ standard. Examples include substituting the &lt;X&gt; header for the &lt;X.h&gt; 585the C++ standard. Examples include substituting the &lt;X&gt; header for the &lt;X.h&gt;
561header for C++ includes, or &lt;sstream&gt; instead of the deprecated header 586header for C++ includes, or &lt;sstream&gt; instead of the deprecated header
562&lt;strstream.h&gt;. To disable this warning use -Wno-deprecated. 587&lt;strstream.h&gt;. To disable this warning use -Wno-deprecated.
563In file included from main.cc:40: 588In file included from main.cc:40:
564menudef.h:55: error: brace-enclosed initializer used to initialize ` 589menudef.h:55: error: brace-enclosed initializer used to initialize `
565OXPopupMenu*' 590OXPopupMenu*'
566menudef.h:62: error: brace-enclosed initializer used to initialize ` 591menudef.h:62: error: brace-enclosed initializer used to initialize `
567OXPopupMenu*' 592OXPopupMenu*'
568menudef.h:70: error: brace-enclosed initializer used to initialize ` 593menudef.h:70: error: brace-enclosed initializer used to initialize `
579make: *** [shared] Error 2 604make: *** [shared] Error 2
580 605
581!!! ERROR: x11-libs/xclass-0.7.4 failed. 606!!! ERROR: x11-libs/xclass-0.7.4 failed.
582!!! Function src_compile, Line 29, Exitcode 2 607!!! Function src_compile, Line 29, Exitcode 2
583!!! 'emake shared' failed 608!!! 'emake shared' failed
584</pre> 609</pre>
585 610
586<p> 611<p>
587So to begin searching, we head over to the <uri 612So to begin searching, we head over to the <uri
588link="https://bugs.gentoo.org/">Bugzilla Homepage</uri>. 613link="https://bugs.gentoo.org/">Bugzilla Homepage</uri>.
589</p> 614</p>
590 615
591<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/> 616<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>
592 617
593<p> 618<p>
594In order to begin our search, we'll click on "Query Existing bug reports". The 619We'll click on "Query Existing bug reports". The reason why we choose this
595reason why we choose this versus the basic bug search is because the basic bug 620over the basic bug search is because the basic bug search tends to give vague
596search tends to give vague results and often hinders users from looking 621results and often hinders users from looking through the results and finding the
597through the results and finding the duplicate bug. Once we click on the query 622duplicate bug. Once we click on the query screen, we reach the next page:
598screen, we reach the next page:
599</p> 623</p>
600 624
601<figure link="/images/docs/bugzie-search.png" caption="Bugzilla Search Page"/> 625<figure link="/images/docs/bugzie-search.png" caption="Bugzilla Search Page"/>
602 626
603<note> 627<note>
604If you've used the Advanced Search before, you'll most likely see that screen 628If you've used the Advanced Search before, you'll most likely see that screen
605instead. 629instead.
606</note> 630</note>
607 631
608<p> 632<p>
609Proceed on clicking the "Advanced Search" link to bring up the Advanced 633Proceed by clicking on the "Advanced Search" link to bring up the Advanced
610Search page: 634Search page.
611</p> 635</p>
612 636
613<figure link="/images/docs/bugzie-adv-search.png" caption="Advanced Search Page"/> 637<figure link="/images/docs/bugzie-adv-search.png" caption="Advanced Search Page"/>
614 638
615<p> 639<p>
616This is how the Advanced Search Page looks like. While it may seem overwhelming 640This is how the Advanced Search Page looks like. While it may seem overwhelming
617at first, we're going to look at a few simple areas to narrow down the rather 641at first, we're going to look at a few simple areas to narrow down the rather
618vague searches bugzilla returns. 642vague searches bugzilla returns.
619</p> 643</p>
620 644
621<figure link="/images/docs/bugzie-content.png" caption="Content"/> 645<figure link="/images/docs/bugzie-content.png" caption="Content"/>
622 646
623<p> 647<p>
624The first field is the summary of the bug. Here we're simply going to put the 648The first field is the summary of the bug. Here we're simply going to put the
625name of the package that's crashing. If you still don't get results, try 649name of the package that's crashing. If bugzie doesn't return results, try
626removing the package name, just in case someone didn't put that in the summary 650removing the package name, just in case someone didn't put that in the summary
627(highly unlikely, but I've seen my fair share of strange bug reports). 651(highly unlikely, but we've seen a fair share of strange bug reports).
628</p> 652</p>
629 653
630<p> 654<p>
631Product, Component, and Version should all be set to the default. This 655Product, Component, and Version should all be set to the default. This
632prevents us from being too specific and missing all the bugs. 656prevents us from being too specific and missing all the bugs.
633</p> 657</p>
634 658
635<p> 659<p>
636Comment is the important part. Use comment to list what appears to be a 660Comment is the important part. Use the comment field to list what appears to be a
637specific instance of the error. Basically, don't use anything like the 661specific instance of the error. Basically, don't use anything like the
638beginning of the build error, find a line that's before it stating a true 662beginning of the build error, find a line that's before it stating a true
639error. Also, you'll want to filter out any punctuation to prevent bugzilla 663error. Also, you'll want to filter out any punctuation to prevent bugzilla
640from interpreting the results the comment the wrong way. Example from the xclass 664from interpreting the results the comment the wrong way. Example from the xclass
641emerge error: 665emerge error:
642</p> 666</p>
643 667
644<pre caption="Comment Line Content"> 668<pre caption="Comment Line Content">
645menudef.h:78: error: brace-enclosed initializer used to initialize `OXPopupMenu' 669menudef.h:78: error: brace-enclosed initializer used to initialize `OXPopupMenu'
646<comment>(Remove the quotes ' ')</comment> 670<comment>(Remove the quotes ' ')</comment>
647menudef.h 78 error brace-enclosed initializer used to initialize OXPopupMenu 671menudef.h 78 error brace-enclosed initializer used to initialize OXPopupMenu
648</pre> 672</pre>
649 673
650<p> 674<p>
651The above is specific enough to where we'll find the bug without wading through 675The above is specific enough to where we'll find the bug without wading through
652other xclass compile failure candidates. 676other xclass compile failure candidates.
653</p> 677</p>
654 678
655<p> 679<p>
656URI, Whiteboard, and Keywords can all be left alone. What we've entered so far 680URI, Whiteboard, and Keywords can all be left alone. What we've entered so far
657should be enough to find our bug. Let's see what we have filled out: 681should be enough to find our bug. Let's take a look at what we have filled out.
658</p> 682</p>
659 683
660<figure link="/images/docs/bugzie-comp-search.png" caption="Completed Search Form"/> 684<figure link="/images/docs/bugzie-comp-search.png" caption="Completed Search Form"/>
661 685
662<p> 686<p>
663Now we click on the Search button and here come the results: 687Now we click on the Search button and here come the results...
664</p> 688</p>
665 689
666<figure link="/images/docs/bugzie-search-result.png" caption="Search Results"/> 690<figure link="/images/docs/bugzie-search-result.png" caption="Search Results"/>
667 691
668<p> 692<p>
669Only 2 bugs! That's a lot easier to deal with. We click on the first one to 693Only 2 bugs! That's a lot easier to deal with. We click on the first one to
670check, and sure enough it's the one we're looking for: 694check, and sure enough it's the one we're looking for.
671</p> 695</p>
672 696
673<figure link="/images/docs/bugzie-located.png" caption="Bug Located"/> 697<figure link="/images/docs/bugzie-located.png" caption="Bug Located"/>
674 698
675<p> 699<p>
676Not only is it the one we want, but it has also been resolved. By checking the 700Not only is it the one we want, but it has also been resolved. By checking the
677last comment we see the solution and know what to do in order to resolve it. 701last comment we see the solution and know what to do in order to resolve it.
678Now, let's see what would have happened if we had not used the advanced search: 702Now, let's see what would have happened if we had not used the advanced search.
679</p> 703</p>
680 704
681<figure link="/images/docs/bugzie-basic-search-result.png" caption="Basic Search Results"/> 705<figure link="/images/docs/bugzie-basic-search-result.png" caption="Basic Search Results"/>
682 706
683<p> 707<p>
6844 more bugs to deal with! It gets even worse with larger packages. However, 7084 more bugs to deal with! It gets even worse with larger packages. However,
685with these simple tools, we're able to significantly narrow down the search to 709with these simple tools, we're able to significantly narrow down the search to
686try and locate a specific bug. 710try and locate a specific bug.
687</p> 711</p>
688 712
689</body> 713</body>
690</section> 714</section>
691<section> 715<section>
692<title>Conclusion</title> 716<title>Conclusion</title>
693<body> 717<body>
704 728
705<chapter> 729<chapter>
706<title>Reporting Bugs</title> 730<title>Reporting Bugs</title>
707<section> 731<section>
708<title>Introduction</title> 732<title>Introduction</title>
709<body> 733<body>
710 734
711<p> 735<p>
712In this chapter, we'll figure out how to use Bugzilla to file a shiny, new bug. 736In this chapter, we'll figure out how to use Bugzilla to file a shiny, new bug.
713Head over to <uri link="https://bugs.gentoo.org">Gentoo Bugs</uri> and... 737Head over to <uri link="https://bugs.gentoo.org">Gentoo Bugs</uri> and...
714</p> 738</p>
715 739
716<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/> 740<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>
717 741
718<p> 742<p>
719Go ahead and click on "Report a Bug - Using the Guided format". 743Click on "Report a Bug - Using the guided format".
720</p> 744</p>
721 745
722<figure link="/images/docs/bugzie-prod-select.png" caption="Product Selection"/> 746<figure link="/images/docs/bugzie-prod-select.png" caption="Product Selection"/>
723 747
724<p> 748<p>
725As you can see, <b>major</b> emphasis has been placed on putting your bug in the 749As you can see, <b>major</b> emphasis has been placed on putting your bug in the
726right place. Gentoo Linux is where a large majority of bugs go. Despite this, 750right place. Gentoo Linux is where a large majority of bugs go.
751</p>
752
753<p>
727some people will file ebuild bugs in portage development (assumption that 754Despite this, some people will file ebuild bugs in portage development
728portage team handles the portage tree) or infra (assumption that infra has 755(assumption that portage team handles the portage tree) or infra (assumption
729access to mirrors and rsync and can fix it directly). This is simply not how 756that infra has access to mirrors and rsync and can fix it directly). This is
730things work. Our bug goes in Gentoo Linux, as it's an ebuild bug. We head over 757simply not how things work.
731there and are presented with the multi-step bug reporting process. 758</p>
759
760<p>
761Another common misconception occurs with our Documentation bugs. For example, a
762user finds a bug with the <uri
763link="http://www.gentoo.org/proj/en/releng/catalyst/index.xml">Catalyst
764Docs</uri>. The general tendency is to file a bug under Docs-user, which gets
765assigned to the <uri link="http://gdp.gentoo.org">GDP</uri>, when it should
766actually go to a member of the <uri
767link="http://www.gentoo.org/proj/en/releng/">Release Engineering</uri> team. As
768a rule of thumb, only documentation under http://www.gentoo.org/doc/* is under
769the GDP. Anything under http://www.gentoo.org/proj/* is under the respective
770teams.
732</p> 771</p>
733 772
734<note> 773<note>
735We would rather see a non-Gentoo Linux bug filed in Gentoo Linux than a Gentoo 774We would rather see a bug whose product was not supposed to be Gentoo Linux but
736Linux bug filed in non-Gentoo Linux projects! While neither is preferred, the 775has been filed under the same rather than seeing a bug which belongs the Gentoo
776Linux product and filed elsewhere. While neither is preferred, the former is more
737former is more acceptable and understandable (except website bugs.. we might 777acceptable and understandable (except website bugs.. we might have an issue with
738have an issue with that...) 778that...).
739</note> 779</note>
740 780
741<p> 781<p>
742Let us now proceed with Step 1... 782Our bug goes in Gentoo Linux as it's an ebuild bug. We head over there and are presented
783with the multi-step bug reporting process. Let us now proceed with Step 1...
743</p> 784</p>
744 785
745<figure link="/images/docs/bugzie-guide-step1.png" caption="Guided Format Step 1"/> 786<figure link="/images/docs/bugzie-guide-step1.png" caption="Guided Format Step 1"/>
746 787
747<p> 788<p>
748The first step here is really important (as the red text tells you). This is 789The first step here is really important (as the red text tells you). This is
749where you search to see that someone else hasn't hit the same bug you have, yet. 790where you search to see that someone else hasn't hit the same bug you have, yet.
750If you do skip this step, and a bug like yours already exists, it will be marked 791If you do skip this step and a bug like yours already exists, it will be marked
751as a DUPLICATE thus wasting a large amount of QA effort. To give you an idea, 792as a DUPLICATE thus wasting a large amount of QA effort. To give you an idea,
752the numbers that are struck out above are duplicate bugs. Now comes step 2, 793the bug numbers that are struck out above are duplicate bugs. Now comes step 2,
753where we give the information. 794where we give the information.
754</p> 795</p>
755 796
756</body> 797</body>
757</section> 798</section>
758<section> 799<section>
759<title>Required Information</title> 800<title>Required Information</title>
760<body> 801<body>
761 802
762<p>
763Onto Step 2, let's see what we have here.
764</p>
765
766<figure link="/images/docs/bugzie-basic.png" caption="Basic Information"/> 803<figure link="/images/docs/bugzie-basic.png" caption="Basic Information"/>
767 804
768<p> 805<p>
769First, there's the product. This is Gentoo Linux, which we selected earlier. 806Let us take a closer look at what's what.
770Component is where the problem occurs. We use this to help us sort out the 807</p>
771severity of the issue (i.e. baselayout and core systems will be more important 808
772than new ebuilds or application bugs). Here we select Application, as it is an 809<ul>
773application at fault. Hardware platform is what architecture you're running. 810 <li>
774If you were running SPARC, you would set it to SPARC. For this example, we know 811 First, there's the Product. The product will narrow down the bug to a
775this error can occur on multiple architectures, so we'll select All. Operating 812 specific area of Gentoo like Bugzilla (for bugs relating to bugs.gentoo.org),
776System is what Operating System you're using. Because Gentoo is considered a 813 Docs-user(for User Documentation) or Gentoo Linux (for ebuilds and the like).
814 </li>
815 <li>
816 Component is where exactly the problem occurs, more specifically which part
817 of selected product the bug comes under. This makes classification easier.
818 </li>
819 <li>
820 Hardware platform is what architecture you're running. If you were running
821 SPARC, you would set it to SPARC.
822 </li>
823 <li>
824 Operating System is what Operating System you're using. Because Gentoo is
777"Meta-distribution", it can run on other operating systems beside Linux. 825 considered a "Meta-distribution", it can run on other operating systems
778Examples are Gentoo on MacOS, Gentoo on FreeBSD, etc. For this example, 826 beside Linux.
779we'll select All, as this can occur on all types of systems. Build Identifier 827 </li>
780is what is being used to report the bugs (for logging purposes). You can just 828</ul>
781leave this as is. Let's see what we have so far: 829
782</p> 830<p>
831So, for our example bug, we have :
832</p>
833
834<ul>
835 <li>
836 Product - Gentoo Linux (Since it is an ebuild issue)
837 </li>
838 <li>
839 Component - Application (It is an application at fault, foobar2)
840 </li>
841 <li>
842 Hardware Platform - All (This error could occur across architectures)
843 </li>
844 <li>
845 Operation System - All (It could occur on all types of systems)
846 </li>
847</ul>
783 848
784<figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/> 849<figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/>
785 850
786<p> 851<ul>
787That does look good, so we'll begin with the actual report. In this instance, 852 <li>
788we'll use the foobar2 bug as our example. URL is used to point to errors on a 853 Build Identifier is basically the User Agent of the browser that is being used
789site someplace (pastebin, etc.). However, doing it inside the bug allows the 854 to report the bugs (for logging purposes). You can just leave this as is.
790developers be able to reference to it at any time and is preferred. Then we have 855 </li>
856 <li>
857 URL is optional and is used to point to errors on a site someplace (pastebin,
858 etc.). However, doing it inside the bug allows the developers be able to
859 reference to it at any time and is preferred.
860 </li>
861 <li>
791the summary. In the summary, you should put the package category, name, and 862 In the Summary, you should put the package category, name, and number.
863 </li>
864</ul>
865
866<p>
792number. Not including the category really isn't too bad, but it's recommended. 867Not including the category in the summary really isn't too bad, but it's
793If you don't include the package name, however, we won't know what you're 868recommended. If you don't include the package name, however, we won't know what
794filling a bug for, and will have to ask you about it later. The version number 869you're filling a bug for, and will have to ask you about it later. The version
795is important for people searching for bugs. If 20 people filed bugs and not one 870number is important for people searching for bugs. If 20 people filed bugs and
796put a version number, how would people looking for similar bugs be able to tell 871not one put a version number, how would people looking for similar bugs be able
797if one was there's? They'd have to look through every single bug, which isn't 872to tell if one was there's? They'd have to look through every single bug, which
798too hard, but if there are say, 200 bugs.. it's not that easy. After all the 873isn't too hard, but if there are say, 200 bugs.. it's not that easy. After all
799package information, you'll want to include a small description of the incident. 874the package information, you'll want to include a small description of the
800Here's an example: 875incident. Here's an example:
801</p> 876</p>
802 877
803<figure link="/images/docs/bugzie-summary.png" caption="Summary"/> 878<figure link="/images/docs/bugzie-summary.png" caption="Summary"/>
804 879
805<p> 880<p>
806Just these simple rules can make handling bugs a lot easier. Next are the 881These simple rules can make handling bugs a lot easier. Next are the details.
807details. Here we put in the information about the bug. We'll demonstrate with an 882Here we put in the information about the bug. We'll demonstrate with an example:
808example:
809</p> 883</p>
810 884
811<figure link="/images/docs/bugzie-details.png" caption="Details"/> 885<figure link="/images/docs/bugzie-details.png" caption="Details"/>
812 886
813<p> 887<p>
814So now the developer knows why we're filing the bug. They can then try to 888Now the developer knows why we're filing the bug. They can then try to
815reproduce it. Reproducibility tells us how often we were able to make the 889reproduce it. Reproducibility tells us how often we were able to make the
816problem recur. In this example, we can reproduce it any time simply by running 890problem recur. In this example, we can reproduce it any time simply by running
817foobar2. Let's put that information in: 891foobar2. Let's put that information in.
818</p> 892</p>
819 893
820<figure link="/images/docs/bugzie-reprod.png" caption="Reproduction"/> 894<figure link="/images/docs/bugzie-reprod.png" caption="Reproduction"/>
821 895
822<p> 896<p>
823So now we have explained how we found the bug. Next we want to explain what 897We have explained how we found the bug. The next step is to explain what were
824the results were and what we think they should be: 898the results we got and what we think they should actually be.
825</p> 899</p>
826 900
827<figure link="/images/docs/bugzie-results.png" caption="Results"/> 901<figure link="/images/docs/bugzie-results.png" caption="Results"/>
828 902
829<p> 903<p>
830Next we put additional information. This can be things such as stack traces, 904We could then provide additional information. This could be things such as stack traces,
905<b>sections</b> (since the whole log is usually big and of not much use) of
831<b>sections</b> of strace logs, but most importantly, your emerge --info output. 906strace logs, but most importantly, your <c>emerge --info</c> output. Here's an
832Here's an example: 907example.
833</p> 908</p>
834 909
835<figure link="/images/docs/bugzie-addl-info.png" caption="Additional Information"/> 910<figure link="/images/docs/bugzie-addl-info.png" caption="Additional Information"/>
836 911
837<p> 912<p>
838Lastly we select the severity of the bug. Please look this over carefully. In 913Lastly we select the severity of the bug. Please look this over carefully. In
839most cases it's OK to leave it as is and someone will raise/lower it for you. 914most cases it's OK to leave it as is and someone will raise/lower it for you.
840However, if you raise the severity of the bug, please make sure you read it over 915However, if you raise the severity of the bug, please make sure you read it over
841carefully and make sure you're not making a mistake. Here we will set it to the 916carefully and make sure you're not making a mistake. A run down of the various
842default of normal: 917levels is given below.
843</p> 918</p>
919
920<ul>
921 <li>
922 Blocker - The program just plain doesn't want to emerge or is a major
923 hinderance to the system. For example a <c>baselayout</c> issue which prevents
924 a system from booting up would be a sure candidate to be labelled blocker.
925 </li>
926 <li>
927 Critical - The program has loss of data or severe memory leaks during
928 runtime. Again, an important program like say <c>net-tools</c> failing to
929 compile could be labelled critical. It won't prevent the system from starting
930 up, but is quite essential for day to day stuff.
931 </li>
932 <li>
933 Major - The program crashes, but nothing that causes your system severe
934 damage or information loss.
935 </li>
936 <li>
937 Minor - Your program crashes here and there with apparent workarounds.
938 </li>
939 <li>
940 Normal - The default. If you're not sure leave it here unless it's a new
941 build or cosmetic change, then read below for more information.
942 </li>
943 <li>
944 Trivial - Things such as a mispelled word or whitespace clean up.
945 </li>
946 <li>
947 Enhancement - A request to enable a new feature in a program, or more
948 specifically <e>new ebuilds</e>.
949 </li>
950</ul>
844 951
845<figure link="/images/docs/bugzie-sev.png" caption="Severity"/> 952<figure link="/images/docs/bugzie-sev.png" caption="Severity"/>
953
954<p>
955Here, we'll set it to Normal.
956</p>
846 957
847<p> 958<p>
848Now we can submit the bug report by clicking on the Submit Bug Report box. You 959Now we can submit the bug report by clicking on the Submit Bug Report box. You
849will now see your new bug come up. See <uri 960will now see your new bug come up. See <uri
850link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what 961link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what
851the result looks like. We've reported our bug! Now let's see how it's dealt 962the result looks like. We've reported our bug! Now let's see how it's dealt
852with. 963with.
853</p> 964</p>
854 965
855</body> 966</body>
856</section> 967</section>
857</chapter> 968</chapter>
858 969
859<chapter> 970<chapter>
860<title>Working With Your Bug</title> 971<title>Working With Your Bug</title>
861<section> 972<section>
862<body> 973<body>
863 974
864<p> 975<p>
865looking at the bug, we see the information we provided earlier: 976Looking at the bug, we see the information we provided earlier. You will notice
977that the bug has been assigned to bug-wranglers@gentoo.org. This is the default
978location for Application component bugs.
866</p> 979</p>
867 980
868<figure link="/images/docs/bugzie-new-basic.png" caption="New Bug Basic Information"/> 981<figure link="/images/docs/bugzie-new-basic.png" caption="New Bug Basic Information"/>
869 982
870<p> 983<p>
871And our details are there too: 984The details we entered about the bug are available as well.
872</p> 985</p>
873 986
874<figure link="/images/docs/bugzie-new-details.png" caption="New Bug Details"/> 987<figure link="/images/docs/bugzie-new-details.png" caption="New Bug Details"/>
875 988
876<p> 989<p>
877Now as you can see, the bug has been assigned to bug-wranglers@gentoo.org. This 990However, bug-wranglers (usually) won't fix our bugs, so we'll reassign it to
878is the default location for Application component bugs. However, bug-wranglers 991someone that can (you can let bug-wranglers re-assign it for you as well). For
879(usually) won't fix our bugs, so we'll reassign it to someone that can (you can
880let bug-wranglers re-assign it for you as well). For this we use the package's
881metadata.xml. You can normally find them in 992this we use the package's metadata.xml. You can normally find them in
882/usr/portage/category/package/metadata.xml. Here's one I've made up for foobar2: 993<path>/usr/portage/category/package/metadata.xml</path>. Here's one I've made up
994for foobar2.
883</p> 995</p>
996
997<note>
998You have to be the reporter of the bug or a member of certain Gentoo Bugzilla
999groups (like Gentoo Developers) to be able to reassign bugs.
1000</note>
884 1001
885<pre caption="metadata.xml"> 1002<pre caption="metadata.xml">
886&lt;?xml version="1.0" encoding="UTF-8"?&gt; 1003&lt;?xml version="1.0" encoding="UTF-8"?&gt;
887&lt;!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"&gt; 1004&lt;!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"&gt;
888&lt;pkgmetadata&gt; 1005&lt;pkgmetadata&gt;
889&lt;herd&gt;chriswhite&lt;/herd&gt; 1006&lt;herd&gt;chriswhite&lt;/herd&gt;
890&lt;maintainer&gt; 1007&lt;maintainer&gt;
891&lt;email&gt;chriswhite@gentoo.org&lt;/email&gt; 1008&lt;email&gt;chriswhite@gentoo.org&lt;/email&gt;
892&lt;name&gt;Chris White&lt;/name&gt; 1009&lt;name&gt;Chris White&lt;/name&gt;
893&lt;/maintainer&gt; 1010&lt;/maintainer&gt;
894&lt;longdescription lang="en"&gt; 1011&lt;longdescription lang="en"&gt;
895Foobar2 is a package that uses a configuration file to display a word. 1012Foobar2 is a package that uses a configuration file to display a word.
896&lt;/longdescription&gt; 1013&lt;/longdescription&gt;
897&lt;/pkgmetadata&gt; 1014&lt;/pkgmetadata&gt;
898</pre> 1015</pre>
899 1016
900<p> 1017<p>
901Notice the maintainer section.T his lists the maintainer of the package, which 1018Notice the maintainer section. This lists the maintainer of the package, which
902in this case is myself, Chris White. The email listed is chriswhite@gentoo.org. 1019in this case is myself, Chris White. The email listed is chriswhite@gentoo.org.
903We will use this to re-assign the bug to the proper person. To do this, click 1020We will use this to re-assign the bug to the proper person. To do this, click
904the bubble next to Reassign bug to, then fill in the email: 1021the bubble next to Reassign bug to, then fill in the email.
905</p> 1022</p>
906 1023
907<note> 1024<note>
908A package without a metadata.xml file should be re-assigned to 1025A bug for a package without a metadata.xml file should be re-assigned to
909maintainer-needed@gentoo.org. 1026maintainer-needed@gentoo.org and a package that needs a Gentoo Developer to
1027maintain should be assigned to maintainer-wanted@gentoo.org.
910</note> 1028</note>
911 1029
912<figure link="/images/docs/bugzie-reassign.png" caption="Bug Reassignment"/> 1030<figure link="/images/docs/bugzie-reassign.png" caption="Bug Reassignment"/>
913 1031
914<p> 1032<p>
915Then hit the Commit button for the changes to take place. The bug has been 1033Then hit the Commit button for the changes to take place. The bug has been
916reassigned to me. Shortly afterward, you notice (by email usually) that I've 1034reassigned to me. Shortly afterward, you notice (by email usually) that I've
917responded to your bug. I've stated that I'd like to see an strace log to figure 1035responded to your bug. I've stated that I'd like to see an strace log to figure
918out how the program is trying to reach your configuration file. You follow the 1036out how the program is trying to reach your configuration file. You follow the
919previous instructions on using strace and obtain an strace log. Now you need to 1037previous instructions on using strace and obtain an strace log. Now you need to
920attach it to the bug. In order to do this, click on "Create A New Attachment". 1038attach it to the bug. In order to do this, click on "Create A New Attachment".
921</p> 1039</p>
922 1040
923<figure link="/images/docs/bugzie-new-attach.png" caption="New Attachment"/> 1041<figure link="/images/docs/bugzie-new-attach.png" caption="New Attachment"/>
924 1042
925<p> 1043<p>
926Now we have to attach the log. We click on the "Browse..." button under "File" 1044Now we have to attach the log. Let's go throught it step wise.
927and select the strace log. For Description, we'll put "strace log". Content-Type 1045</p>
928is what kind of file we're attaching. A common mistake is to set it to 1046
929auto. In most cases it's best to manually set it. Our log file is a 1047<ul>
930plain text file, so we select "plain text (text/plain)". Obsoletes are for when 1048 <li>
931you are attaching a revision to a previously attached file. You can simply click 1049 File - This is the location of the file in your machine. In this example, the
932a check box next to the old file and Bugzilla will cross it out in the bug, 1050 location of <path>strace.log</path>. You can use the "Browse..." button to
933indicating that the attachment has been obsoleted. Reassignment means you want 1051 select the file, or enter the path directly in the text field.
934to take the bug yourself. I rarely tend to use this.. and I don't think you will 1052 </li>
935need to at some point (unless you create great patches and we don't care about 1053 <li>
936you taking our bugs ;). Comments are for leaving comments about the file you're 1054 Description - A short one liner, or a few wors describing the attachment.
937posting. We'll put "Here is the strace file you requested". Now we have 1055 We'll just enter strace.log here, since that's quite self-explanatory.
938something like this: 1056 </li>
1057 <li>
1058 Content Type - This is the type of the file we're attaching to the bug.
1059 </li>
1060 <li>
1061 Obsoletes - If there were attachements submitted to the bug before the current
1062 one, you have an option of declaring them obsoleted by yours. Since we have no
1063 prior attachments to this bug, we need not bother.
1064 </li>
1065 <li>
1066 Comment - Enter comments that will be visible along with the attachments. You
1067 could elaborate on the attachment here, if needed.
1068 </li>
1069</ul>
1070
939</p> 1071<p>
1072With respect to Content Type, here are a few more details. You can check the
1073"patch" checkbox if you're submitting a patch. Otherwise, you could ask Bugzilla
1074to "auto-detect" the file type (not advisable). The other options are "select
1075from list", which is most frequently used. Use plain text (text/plain) for <e>most</e>
1076attachments except binary files like images (which can use image/gif,
1077image/jpeg or image/png depending on type) or compressed files like .tar.bz2
1078which would use application/octet-stream as content type.
1079</p>
1080
940 1081
941<figure link="/images/docs/bugzie-new-attach-comp.png" caption="New Attachment Completed"/> 1082<figure link="/images/docs/bugzie-new-attach-comp.png" caption="New Attachment Completed"/>
942 1083
943<p> 1084<p>
944We Submit the patch and it is now reflected on the bug report. 1085We submit <path>strace.log</path> and it is reflected on the bug report.
945</p> 1086</p>
946 1087
947<figure link="/images/docs/bugzie-strace.png" caption="Attached strace log"/> 1088<figure link="/images/docs/bugzie-strace.png" caption="Attached strace log"/>
948 1089
949<p> 1090<p>
950Now, while we're waiting another person notices your bug during step 1 of the 1091We've mentioned before that sometimes ebuilds will tell you to attach a file in
951Guided Format. This person wants to see the status of the bug as well. He or 1092the emerge error. An example can be seen below.
952she may do so by putting their email in the Add CC field like so: 1093</p>
1094
1095<pre caption="Example File Attachment Request">
1096configure: error: PNG support requires ZLIB. Use --with-zlib-dir=&lt;DIR&gt;
1097
1098!!! Please attach the config.log to your bug report:
1099!!! /var/tmp/portage/php-5.0.3-r1/work/php-5.0.3/config.log
1100
1101!!! ERROR: dev-php/php-5.0.3-r1 failed.
1102!!! Function econf, Line 485, Exitcode 0
1103!!! econf failed
1104!!! If you need support, post the topmost build error, NOT this status message.
1105</pre>
1106
1107<p>
1108Please attach any file mentioned like this to your bug report.
1109</p>
1110
1111<p>
1112While we're doing all this, suppose another person finds your bug by searching
1113through bugzilla and is curious to keep track of the bug, they may do so by
1114putting their email in the Add CC field of the bug as shown below. You could
1115also keep track of other bugs by following the same method.
953</p> 1116</p>
954 1117
955<figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/> 1118<figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/>
956 1119
957<note> 1120<note>
958Email addresses must be registered with bugzilla. In order to CC multiple 1121Email addresses must be registered with Gentoo Bugzilla. In order to CC multiple
959addresses, simply separate them with commas or spaces. 1122addresses, simply separate them with commas or spaces.
960</note> 1123</note>
961 1124
962<p> 1125<p>
963After all this work, the bug can undergo various status markings. Here's a few: 1126After all this work, the bug can undergo various status markings. This is
1127usually done by the Gentoo Developers and sometimes by the reporter. The
1128following are the various possible states a bug may go through during its
1129lifetime.
964</p> 1130</p>
965 1131
966<ul> 1132<ul>
967 <li> 1133 <li>
968 UNCONFIRMED - You're generally not going to see this too often. This 1134 UNCONFIRMED - You're generally not going to see this too often. This
969 means that a bug reporter has opened a bug using the advanced method and is 1135 means that a bug reporter has opened a bug using the advanced method and is
970 uncertain his or her bug is an actual bug. 1136 uncertain his or her bug is an actual bug.
971 </li> 1137 </li>
972 <li> 1138 <li>
973 NEW - Bugs that are first opened are considered new. 1139 NEW - Bugs that are first opened are considered new.
974 </li> 1140 </li>
975 <li> 1141 <li>
976 ASSIGNED - When the person you've assigned the bug too validates your 1142 ASSIGNED - When the person you've assigned the bug too validates your
977 bug, it will often receive ASSIGNED status while they figure out the issue. 1143 bug, it will often receive ASSIGNED status while they figure out the issue.
978 This let's you know that they've accepted your bug as a real bug. 1144 This lets you know that they've accepted your bug as a real bug.
979 </li> 1145 </li>
980 <li> 1146 <li>
981 REOPENED - Someone has resolved a bug and you think the solution is not 1147 REOPENED - Someone has resolved a bug and you think the solution is not
982 feasible or the problem still persists. At this point, you may re-open the 1148 feasible or the problem still persists. At this point, you may re-open the
983 bug. However <b>please do not abuse this</b>. If a developer closes the bug a 1149 bug. Please <b>do not abuse this</b>. If a developer closes the bug a
984 second or even third time, chances are that your bug is closed. 1150 second or third time, chances are that your bug is closed.
1151 </li>
1152 <li>
1153 RESOLVED - A firm decision has been taken on the bug. Usually goes onto FIXED
1154 to indicate the bug is solved and the matter closed although various other
1155 resolutions are possible. We'll look into those a little later.
1156 </li>
1157 <li>
1158 VERIFIED - The steps take to work the bug are correct. This is usually a QA
1159 thing.
1160 </li>
1161 <li>
1162 CLOSED - Basically means RIP for the bug and it's buried under the never ending
1163 flow of new bugs.
985 </li> 1164 </li>
986</ul> 1165</ul>
987 1166
988<p> 1167<p>
989Now shortly afterward, I find the error in the strace log. I resolve the bug 1168Now shortly afterward, we find the error in the strace log and fix the bug and
990as RESOLVED FIXED and say that there was a change in the location of 1169mark it as RESOLVED FIXED and mention that there was a change in the location of
991configuration files, and that I will update the ebuild with a warning about it. 1170configuration files, and that I will update the ebuild with a warning about it.
992The bug now becomes resolved, and you are displayed with this: 1171The bug now becomes resolved, and you are shown the following.
993</p> 1172</p>
994 1173
995<figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/> 1174<figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/>
996 1175
997<p> 1176<p>
998Also note the section here: 1177A little below, you'll see the following:
999</p> 1178</p>
1000 1179
1001<figure link="/images/docs/bugzie-options.png" caption="Bug Options"/> 1180<figure link="/images/docs/bugzie-options.png" caption="Bug Options"/>
1002 1181
1003<p> 1182<p>
1004This gives you the option of Reopening the bug if you wish to (i.e. the developer 1183This gives you the option of Reopening the bug if you wish to (i.e. the developer
1005thinks it's resolved but it's really not to your standards). Now our bug is 1184thinks it's resolved but it's really not to your standards). Now our bug is
1006fixed! However, different resolutions can occur. Here's a small list: 1185fixed! However, different resolutions can occur. Here's a small list:
1007</p> 1186</p>
1008 1187
1009<ul> 1188<ul>
1010 <li> 1189 <li>
1011 FIXED - The bug is fixed, follow the instructions to resolve your 1190 FIXED - The bug is fixed, follow the instructions to resolve your
1012 issue. 1191 issue.
1013 </li> 1192 </li>
1014 <li> 1193 <li>
1015 INVALID - You did not do something specifically documented, causing the 1194 INVALID - You did not do something specifically documented, causing the
1016 bug 1195 bug.
1017 </li> 1196 </li>
1018 <li> 1197 <li>
1019 DUPLICATE - You didn't use this guide and reported a duplicate bug 1198 DUPLICATE - You didn't use this guide and reported a duplicate bug
1020 :) 1199 :)
1021 </li> 1200 </li>
1022 <li> 1201 <li>
1023 WORKSFORME - Developer/person assigned the bug cannot reproduce your 1202 WORKSFORME - Developer/person assigned the bug cannot reproduce your
1024 error 1203 error.
1204 </li>
1205 <li>
1206 CANTFIX - Somehow the bug cannot be solved because of certain circumstances.
1207 These circumstances will be noted by the person taking the bug.
1208 </li>
1209 <li>
1210 WONTFIX - This is usually applied to new ebuilds or feature requests.
1211 Basically the developer does not want to add a certain feature because it is
1212 not needed, a better alternative exists, or it's just plain broken. Sometimes
1213 you may be given a solution to get said issue resolved.
1214 </li>
1215 <li>
1216 UPSTREAM - The bug cannot be fixed by the Gentoo development team, and
1217 have requested you take the problem upstream (the people that actually made
1218 the program) for review. Upstream has a few ways of handling bugs. These
1219 include mailing lists, irc channels, and even bug reporting systems. If
1220 you're not sure how to contact them, ask in the bug and someone will point
1221 you to the right direction.
1025 </li> 1222 </li>
1026</ul> 1223</ul>
1027 1224
1225<p>
1226Sometimes, before the bug can be resolved, a developer may request that you
1227test an updated ebulid. In the next chapter we'll take a look at testing
1228ebuilds.
1229</p>
1230
1028</body> 1231</body>
1232</section>
1233</chapter>
1234
1235<chapter>
1236<title>Testing Ebuilds</title>
1029</section> 1237<section>
1238<title>Getting The Files</title>
1239<body>
1030 1240
1241<p>
1242Let's say that you reported a bug for the foobar2 compile fix from earlier. Now
1243developers might find out what the problem is and might need you to test the
1244ebuild for them to be sure it works for you as well:
1245</p>
1246
1247<figure link="/images/docs/bugzie-ebuild-request.png" caption="Ebuild Test Request"/>
1248
1249<p>
1250Some rather confusing vocabulary is used here. First off, let's see what an
1251overlay is. An overlay is a special directory like <path>/usr/portage</path>,
1252the difference being that when you <c>emerge sync</c>, files contained within it
1253will not be deleted. Luckily, a special <path>/usr/local/portage</path>
1254directory is created for that purpose. Let's go ahead and set our portage
1255overlay in<path>/etc/make.conf</path>. Open make.conf up in your favorite editor
1256and add this towards the end.
1257</p>
1258
1259<pre caption="Setting Up PORTDIR_OVERLAY">
1260PORTDIR_OVERLAY="/usr/local/portage"
1261</pre>
1262
1263<p>
1264Now we'll want to create the appropriate directories to put our test ebuild
1265files in. In this case, we're supposed to put them in sys-apps/foobar2. You'll
1266notice that the second comment asks for a files directory for the patch. The
1267files directory holds the digests (md5sums of files for a particular version of
1268a package) and any other required files that aren't included with the standard
1269source archive (patches, init.d scripts, etc). This is a subdir in the package
1270directory called files. Go ahead and create these directories:
1271</p>
1272
1273<pre caption="Setting Up The Category And Package Directories">
1274# <i>mkdir -p /usr/local/portage/sys-apps/foobar2/files</i>
1275</pre>
1276
1277<note>
1278The -p in mkdir creates not only the directory you want but also any missing
1279parent directories as well (sys-apps and foobar2 in this case).
1280</note>
1281
1282<p>
1283Ok now, we can go ahead and download the files. First, download the ebuild
1284into <path>/usr/local/portage/sys-apps/foobar2</path>, and then add the patch
1285to <path>/usr/local/portage/sys-apps/foobar2/files</path>. Now that we have the
1286files, we can begin working on testing the ebuild.
1287</p>
1288
1289</body>
1290</section>
1291<section>
1292<title>Testing The ebuild</title>
1293<body>
1294
1295<p>
1296The process to create an ebuild that can be used by emerge is fairly simple. You
1297must create a Manifest and a digest file for the ebuild. This can be done with
1298the ebuild command. Run it as shown.
1299</p>
1300
1301<pre caption="Creating the Manifest and digest files">
1302# <i>ebuild foobar2-1.0.ebuild digest</i>
1303&gt;&gt;&gt; Generating digest file...
1304&lt;&lt;&lt; foobar2-1.0.tar.bz2
1305&gt;&gt;&gt; Generating manifest file...
1306&lt;&lt;&lt; foobar2-1.0.ebuild
1307&lt;&lt;&lt; files/digest-foobar2-1.0
1308&lt;&lt;&lt; files/foobar2-1.0-Makefile.patch
1309&gt;&gt;&gt; Computed message digests.
1310</pre>
1311
1312<p>
1313Now let's test to see if it works as it should.
1314</p>
1315
1316<pre caption="Testing With emerge -pv">
1317# <i>emerge -pv foobar2</i>
1318
1319These are the packages that I would merge, in order:
1320
1321Calculating dependencies ...done!
1322[ebuild N ] sys-apps/foobar2-1.0 0 kB [1]
1323
1324Total size of downloads: 0 kB
1325Portage overlays:
1326 [1] /usr/local/portage
1327</pre>
1328
1329<p>
1330It does seem to have worked! You'll notice the [1] next to the [ebuild] line.
1331That points to <path>/usr/local/portage</path>, which is the overlay we created
1332earlier. Now we go ahead and emerge the package.
1333</p>
1334
1335<pre caption="Emerge Result">
1336# emerge foobar2
1337 Calculating dependencies ...done!
1338<comment>(compile info snipped)</comment>
1339>>> Unpacking foobar2-1.0.tar.bz2 to /var/tmp/portage/foobar2-1.0/work
1340 * Applying foobar2-1.0-Makefile.patch ... [ ok ]
1341<comment>(compile info snipped)</comment>
1342>>> Merging sys-apps/foobar2-1.0 to /
1343>>> chris +sandbox(preinst)
1344--- /usr/
1345--- /usr/bin/
1346>>> /usr/bin/foobar2
1347</pre>
1348
1349<p>
1350In the first section we see that the emerge started off as it should. The second
1351section shows our patch being applied successfully by the "[ ok ]" status
1352message to the right. The last section tells us the program compiled ok. The
1353patch works! Now we can go and let the developer know that their patch works
1354fine, and that they can commit the fix to portage.
1355</p>
1356
1357</body>
1358</section>
1031<section> 1359<section>
1032<title>Conclusion</title> 1360<title>Conclusion</title>
1033<body> 1361<body>
1034 1362
1035<p> 1363<p>
1036This concludes the howto on working with Bugzilla. I hope you find this useful. 1364This concludes the howto on working with Bugzilla. I hope you find this useful.
1037If you have any questions, comments, or ideas regarding this document, please 1365If you have any questions, comments, or ideas regarding this document, please
1038send them to me at <mail 1366send them to me at <mail
1039link="chriswhite@gentoo.org">chriswhite@gentoo.org</mail>. Special 1367link="chriswhite@gentoo.org">chriswhite@gentoo.org</mail>. Special
1040thanks go to moreon for his notes on -g flags and compile errors, the people at 1368thanks go to moreon for his notes on -g flags and compile errors, the people at
1041#gentoo-bugs for helping out with bug-wrangling, and Griffon26 for his notes on 1369#gentoo-bugs for helping out with bug-wrangling, Griffon26 for his notes on
1042maintainer-needed. 1370maintainer-needed, robbat2 for general suggestions and fox2mike for fixing up
1371the doc and adding stuff as needed.
1043</p> 1372</p>
1044 1373
1045</body> 1374</body>
1046</section> 1375</section>
1047</chapter> 1376</chapter>
1048</guide> 1377</guide>

Legend:
Removed from v.1.2  
changed lines
  Added in v.1.3

  ViewVC Help
Powered by ViewVC 1.1.20