/[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.1 Revision 1.6
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.1 2005/07/07 12:02:21 fox2mike Exp $ --> 3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.6 2005/08/30 02:51:12 vapier 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">
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.0</version> 23<version>1.5</version>
24<date>2005-07-07</date> 24<date>2005-08-29</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
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 you
90you do? The following sections will look at 2 important tools for handling 90do? The following sections will look at two important tools for handling run
91run time errors. After that, we'll take a look at compile errors, and how to 91time errors. After that, we'll take a look at compile errors, and how to handle
92handle them. Let's start out with the first tool for debugging run time 92them. Let's start out with the first tool for debugging run time errors --
93errors -- <c>gdb</c> 93<c>gdb</c>.
94</p> 94</p>
95 95
96</body> 96</body>
97</section> 97</section>
98</chapter> 98</chapter>
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
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
131debug to the package's USE flags. This can be done with the 131<path>/etc/make.conf</path> <e>might</e> look with the newly added flags.
132<path>package.use</path> file.
133</p> 132</p>
133
134<pre caption="make.conf settings">
135CFLAGS="-O1 -pipe -g -ggdb"
136CXXFLAGS="${CFLAGS}"
137</pre>
138
139<p>
140Lastly, you can also add debug to the package's USE flags. This can be done
141with the <path>package.use</path> file.
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
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>
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
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>
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 ?? ()
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 -ggdb 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 -ggdb enabled
300programs.
284</p> 301</p>
285 302
286<pre caption="Filesize differences With -g flag"> 303<pre caption="Filesize differences With -ggdb 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>(-ggdb 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, -ggdb 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>
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
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 strace.log in the current directory. We check the 383This creates a file called <path>strace.log</path> in the current directory. We
368file, 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
376<p> 392<p>
377Aha! So There's the problem. Someone moved the configuration directory to 393Aha! So There's the problem. Someone moved the configuration directory to
378<path>.foobar2</path> instead of <path>.foobar</path>. We also see the program 394<path>.foobar2</path> instead of <path>.foobar</path>. We also see the program
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 .foobar and modify it to produce the correct results. 397config file from <path>.foobar</path> and modify it to produce the correct
398results.
382</p> 399</p>
383 400
384</body> 401</body>
385</section> 402</section>
386<section> 403<section>
388<body> 405<body>
389 406
390<p> 407<p>
391Now 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
392problematic 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
393the 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
394look at how to address <c>emerge</c> compile errors. 411look at how to address <c>emerge</c> compile errors.
395</p> 412</p>
396 413
397</body> 414</body>
398</section> 415</section>
404<title>Introduction</title> 421<title>Introduction</title>
405<body> 422<body>
406 423
407<p> 424<p>
408<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
409of frustration for users. Reporting them is considered crucial for helping 426of frustration for users. Reporting them is considered crucial for maintaining
410maintain 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
411which contains some build errors. 428contains some build errors.
412</p> 429</p>
413 430
414</body> 431</body>
415</section> 432</section>
416<section id="emerge_error"> 433<section id="emerge_error">
434!!! Make failed! 451!!! Make failed!
435!!! 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
436</pre> 453</pre>
437 454
438<p> 455<p>
439The 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
440particular 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
441error, and the emerge error message as shown below. 458error, and the emerge error message as shown below.
442</p> 459</p>
443 460
444<pre caption="Parts of the error"> 461<pre caption="Parts of the error">
445<comment>(Compile Error)</comment> 462<comment>(Compilation Messages)</comment>
446gcc -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
447gcc -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
448gcc -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
449gcc -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
450 467
451<comment>(Build Error)</comment> 468<comment>(Build Error)</comment>
452foobar2.c:1:17: ogg.h: No such file or directory 469foobar2.c:1:17: ogg.h: No such file or directory
453make: *** [foobar2.o] Error 1 470make: *** [foobar2.o] Error 1
454 471
455<comment>(Emerge Error)</comment> 472<comment>(emerge Error)</comment>
456!!! ERROR: sys-apps/foobar2-1.0 failed. 473!!! ERROR: sys-apps/foobar2-1.0 failed.
457!!! Function src_compile, Line 19, Exitcode 2 474!!! Function src_compile, Line 19, Exitcode 2
458!!! Make failed! 475!!! Make failed!
459!!! 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
460</pre> 477</pre>
461 478
462<p> 479<p>
463The 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
464include 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
465compile is at. Make errors are the actual error, and the information the 482where the compilation was at when the error occurred.
466developer needs. When you see "make: ***", this is often where the error has 483</p>
467occurred. Normally, you can copy and paste 10 lines above it and the developer 484
468will be able to address the issue. However, this may not always work and we'll 485<p>
469take 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
470can 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
471emerge 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
472compile information, a developer can get what application and what version of 497make error and compile information, a developer can get what application and
473the 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
474process 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
475error 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
476This 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
477errors 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
478That's where PORT_LOGDIR comes into play. 503everything. That's where PORT_LOGDIR comes into play.
479</p> 504</p>
480 505
481</body> 506</body>
482</section> 507</section>
483<section> 508<section>
484<title>emerge and PORT_LOGDIR</title> 509<title>emerge and PORT_LOGDIR</title>
485<body> 510<body>
486 511
487<p> 512<p>
488PORT_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
489emerge 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
490with PORT_LOGDIR set to your favorite log location. Let's say we have a 515emerge with PORT_LOGDIR set to your favorite log location. Let's say we have a
491location /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:
492</p> 517</p>
493 518
494<note> 519<note>
495In 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
496have 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.
497</note> 523</note>
498 524
499<pre caption="emerge-ing With PORT_LOGDIR"> 525<pre caption="emerge-ing With PORT_LOGDIR">
500# <i>PORT_LOGDIR=/var/log/portage emerge foobar2</i> 526# <i>PORT_LOGDIR=/var/log/portage emerge foobar2</i>
501</pre> 527</pre>
536 562
537<p> 563<p>
538<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
539handle 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
540available 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
541consistency, 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
542over 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
543looks. 569looks.
544</p> 570</p>
545 571
546<p> 572<p>
547One 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
548duplicate bug reports. This causes them valuable time they could be using to 574duplicate bug reports. These cost them valuable time that they could otherwise
549find 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
550search 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
551you 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
552emerge error that was used earlier: 578emerge error that was used earlier.
553</p> 579</p>
554 580
555<pre caption="xclass emerge error"> 581<pre caption="xclass emerge error">
556/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:
557warning: #warning This file includes at least one deprecated or antiquated 583warning: #warning This file includes at least one deprecated or antiquated
582!!! 'emake shared' failed 608!!! 'emake shared' failed
583</pre> 609</pre>
584 610
585<p> 611<p>
586So to begin searching, we head over to the <uri 612So to begin searching, we head over to the <uri
587link="http://bugs.gentoo.org/">Bugzilla Homepage</uri>. 613link="https://bugs.gentoo.org/">Bugzilla Homepage</uri>.
588</p> 614</p>
589 615
590<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/> 616<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>
591 617
592<p> 618<p>
593In 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
594reason 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
595search tends to give vague results and often hinders users from looking 621results and often hinders users from looking through the results and finding the
596through 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:
597screen, we reach the next page:
598</p> 623</p>
599 624
600<figure link="/images/docs/bugzie-search.png" caption="Bugzilla Search Page"/> 625<figure link="/images/docs/bugzie-search.png" caption="Bugzilla Search Page"/>
601 626
602<note> 627<note>
603If 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
604instead. 629instead.
605</note> 630</note>
606 631
607<p> 632<p>
608Proceed on clicking the "Advanced Search" link to bring up the Advanced 633Proceed by clicking on the "Advanced Search" link to bring up the Advanced
609Search page: 634Search page.
610</p> 635</p>
611 636
612<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"/>
613 638
614<p> 639<p>
615This 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
616at 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
617vague searches bugzilla returns. 642vague searches bugzilla returns.
618</p> 643</p>
619 644
620<figure link="/images/docs/bugzie-content.png" caption="Content"/> 645<figure link="/images/docs/bugzie-content.png" caption="Content"/>
621 646
622<p> 647<p>
623The 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
624name 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
625removing 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
626(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).
627</p> 652</p>
628 653
629<p> 654<p>
630Product, Component, and Version should all be set to the default. This 655Product, Component, and Version should all be set to the default. This
631prevents us from being too specific and missing all the bugs. 656prevents us from being too specific and missing all the bugs.
632</p> 657</p>
633 658
634<p> 659<p>
635Comment 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
636specific instance of the error. Basically, don't use anything like the 661specific instance of the error. Basically, don't use anything like the
637beginning 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
638error. 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
639from 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
640emerge error: 665emerge error:
651other xclass compile failure candidates. 676other xclass compile failure candidates.
652</p> 677</p>
653 678
654<p> 679<p>
655URI, 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
656should 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.
657</p> 682</p>
658 683
659<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"/>
660 685
661<p> 686<p>
662Now we click on the Search button and here come the results: 687Now we click on the Search button and here come the results...
663</p> 688</p>
664 689
665<figure link="/images/docs/bugzie-search-result.png" caption="Search Results"/> 690<figure link="/images/docs/bugzie-search-result.png" caption="Search Results"/>
666 691
667<p> 692<p>
668Only 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
669check, and sure enough it's the one we're looking for: 694check, and sure enough it's the one we're looking for.
670</p> 695</p>
671 696
672<figure link="/images/docs/bugzie-located.png" caption="Bug Located"/> 697<figure link="/images/docs/bugzie-located.png" caption="Bug Located"/>
673 698
674<p> 699<p>
675Not 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
676last 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.
677Now, 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.
678</p> 703</p>
679 704
680<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"/>
681 706
682<p> 707<p>
713</p> 738</p>
714 739
715<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/> 740<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>
716 741
717<p> 742<p>
718Go ahead and click on "Report a Bug - Using the Guided format". 743Click on "Report a Bug - Using the guided format".
719</p> 744</p>
720 745
721<figure link="/images/docs/bugzie-prod-select.png" caption="Product Selection"/> 746<figure link="/images/docs/bugzie-prod-select.png" caption="Product Selection"/>
722 747
723<p> 748<p>
724As 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
725right 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>
726some people will file ebuild bugs in portage development (assumption that 754Despite this, some people will file ebuild bugs in portage development
727portage team handles the portage tree) or infra (assumption that infra has 755(assumption that portage team handles the portage tree) or infra (assumption
728access 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
729things work. Our bug goes in Gentoo Linux, as it's an ebuild bug. We head over 757simply not how things work.
730there 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 link="/proj/en/releng/catalyst/">Catalyst
763Docs</uri>. The general tendency is to file a bug under Docs-user, which gets
764assigned to the <uri link="http://gdp.gentoo.org">GDP</uri>, when it should
765actually go to a member of the <uri link="/proj/en/releng/">Release
766Engineering</uri> team. As a rule of thumb, only documentation under
767<path>http://www.gentoo.org/doc/*</path> is under the GDP. Anything under
768<path>http://www.gentoo.org/proj/*</path> is under the respective teams.
731</p> 769</p>
732 770
733<note> 771<note>
734We would rather see a non-Gentoo Linux bug filed in Gentoo Linux than a Gentoo 772We would rather see a bug whose product was not supposed to be Gentoo Linux but
735Linux bug filed in non-Gentoo Linux projects! While neither is preferred, the 773has been filed under the same rather than seeing a bug which belongs the Gentoo
774Linux product and filed elsewhere. While neither is preferred, the former is more
736former is more acceptable and understandable (except website bugs.. we might 775acceptable and understandable (except website bugs.. we might have an issue with
737have an issue with that...) 776that...).
738</note> 777</note>
739 778
740<p> 779<p>
741Let us now proceed with Step 1... 780Our bug goes in Gentoo Linux as it's an ebuild bug. We head over there and are
781presented with the multi-step bug reporting process. Let us now proceed with
782Step 1...
742</p> 783</p>
743 784
744<figure link="/images/docs/bugzie-guide-step1.png" caption="Guided Format Step 1"/> 785<figure link="/images/docs/bugzie-guide-step1.png" caption="Guided Format Step 1"/>
745 786
746<p> 787<p>
747The first step here is really important (as the red text tells you). This is 788The first step here is really important (as the red text tells you). This is
748where you search to see that someone else hasn't hit the same bug you have, yet. 789where you search to see that someone else hasn't hit the same bug you have, yet.
749If you do skip this step, and a bug like yours already exists, it will be marked 790If you do skip this step and a bug like yours already exists, it will be marked
750as a DUPLICATE thus wasting a large amount of QA effort. To give you an idea, 791as a DUPLICATE thus wasting a large amount of QA effort. To give you an idea,
751the numbers that are struck out above are duplicate bugs. Now comes step 2, 792the bug numbers that are struck out above are duplicate bugs. Now comes step 2,
752where we give the information. 793where we give the information.
753</p> 794</p>
754 795
755</body> 796</body>
756</section> 797</section>
757<section> 798<section>
758<title>Required Information</title> 799<title>Required Information</title>
759<body> 800<body>
760 801
761<p>
762Onto Step 2, let's see what we have here.
763</p>
764
765<figure link="/images/docs/bugzie-basic.png" caption="Basic Information"/> 802<figure link="/images/docs/bugzie-basic.png" caption="Basic Information"/>
766 803
767<p> 804<p>
768First, there's the product. This is Gentoo Linux, which we selected earlier. 805Let us take a closer look at what's what.
769Component is where the problem occurs. We use this to help us sort out the 806</p>
770severity of the issue (i.e. baselayout and core systems will be more important 807
771than new ebuilds or application bugs). Here we select Application, as it is an 808<ul>
772application at fault. Hardware platform is what architecture you're running. 809 <li>
773If you were running SPARC, you would set it to SPARC. For this example, we know 810 First, there's the Product. The product will narrow down the bug to a
774this error can occur on multiple architectures, so we'll select All. Operating 811 specific area of Gentoo like Bugzilla (for bugs relating to
775System is what Operating System you're using. Because Gentoo is considered a 812 bugs.gentoo.org), Docs-user(for User Documentation) or Gentoo Linux (for
813 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
776"Meta-distribution", it can run on other operating systems beside Linux. 825 considered a "Meta-distribution", it can run on other operating systems
777Examples are Gentoo on MacOS, Gentoo on FreeBSD, etc. For this example, 826 beside Linux.
778we'll select All, as this can occur on all types of systems. Build Identifier 827 </li>
779is what is being used to report the bugs (for logging purposes). You can just 828</ul>
780leave this as is. Let's see what we have so far: 829
781</p> 830<p>
831So, for our example bug, we have :
832</p>
833
834<ul>
835 <li>Product - Gentoo Linux (Since it is an ebuild issue)</li>
836 <li>Component - Application (It is an application at fault, foobar2)</li>
837 <li>Hardware Platform - All (This error could occur across architectures)</li>
838 <li>Operation System - All (It could occur on all types of systems)</li>
839</ul>
782 840
783<figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/> 841<figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/>
784 842
785<p> 843<ul>
786That does look good, so we'll begin with the actual report. In this instance, 844 <li>
787we'll use the foobar2 bug as our example. URL is used to point to errors on a 845 Build Identifier is basically the User Agent of the browser that is being
846 used to report the bugs (for logging purposes). You can just leave this as
847 is.
848 </li>
849 <li>
850 URL is optional and is used to point to errors on a site someplace
788site someplace (pastebin, etc.). However, doing it inside the bug allows the 851 (pastebin, etc.). However, doing it inside the bug allows the developers be
789developers be able to reference to it at any time and is preferred. Then we have 852 able to reference to it at any time and is preferred.
853 </li>
854 <li>
790the summary. In the summary, you should put the package category, name, and 855 In the Summary, you should put the package category, name, and number.
856 </li>
857</ul>
858
859<p>
791number. Not including the category really isn't too bad, but it's recommended. 860Not including the category in the summary really isn't too bad, but it's
792If you don't include the package name, however, we won't know what you're 861recommended. If you don't include the package name, however, we won't know what
793filling a bug for, and will have to ask you about it later. The version number 862you're filling a bug for, and will have to ask you about it later. The version
794is important for people searching for bugs. If 20 people filed bugs and not one 863number is important for people searching for bugs. If 20 people filed bugs and
795put a version number, how would people looking for similar bugs be able to tell 864not one put a version number, how would people looking for similar bugs be able
796if one was there's? They'd have to look through every single bug, which isn't 865to tell if one was there's? They'd have to look through every single bug, which
797too hard, but if there are say, 200 bugs.. it's not that easy. After all the 866isn't too hard, but if there are say, 200 bugs.. it's not that easy. After all
798package information, you'll want to include a small description of the incident. 867the package information, you'll want to include a small description of the
799Here's an example: 868incident. Here's an example:
800</p> 869</p>
801 870
802<figure link="/images/docs/bugzie-summary.png" caption="Summary"/> 871<figure link="/images/docs/bugzie-summary.png" caption="Summary"/>
803 872
804<p> 873<p>
805Just these simple rules can make handling bugs a lot easier. Next are the 874These simple rules can make handling bugs a lot easier. Next are the details.
806details. Here we put in the information about the bug. We'll demonstrate with an 875Here we put in the information about the bug. We'll demonstrate with an example:
807example:
808</p> 876</p>
809 877
810<figure link="/images/docs/bugzie-details.png" caption="Details"/> 878<figure link="/images/docs/bugzie-details.png" caption="Details"/>
811 879
812<p> 880<p>
813So now the developer knows why we're filing the bug. They can then try to 881Now the developer knows why we're filing the bug. They can then try to
814reproduce it. Reproducibility tells us how often we were able to make the 882reproduce it. Reproducibility tells us how often we were able to make the
815problem recur. In this example, we can reproduce it any time simply by running 883problem recur. In this example, we can reproduce it any time simply by running
816foobar2. Let's put that information in: 884foobar2. Let's put that information in.
817</p> 885</p>
818 886
819<figure link="/images/docs/bugzie-reprod.png" caption="Reproduction"/> 887<figure link="/images/docs/bugzie-reprod.png" caption="Reproduction"/>
820 888
821<p> 889<p>
822So now we have explained how we found the bug. Next we want to explain what 890We have explained how we found the bug. The next step is to explain what were
823the results were and what we think they should be: 891the results we got and what we think they should actually be.
824</p> 892</p>
825 893
826<figure link="/images/docs/bugzie-results.png" caption="Results"/> 894<figure link="/images/docs/bugzie-results.png" caption="Results"/>
827 895
828<p> 896<p>
829Next we put additional information. This can be things such as stack traces, 897We could then provide additional information. This could be things such as
898stack traces, <b>sections</b> (since the whole log is usually big and of not
830<b>sections</b> of strace logs, but most importantly, your emerge --info output. 899much use) of strace logs, but most importantly, your <c>emerge --info</c>
831Here's an example: 900output. Here's an example.
832</p> 901</p>
833 902
834<figure link="/images/docs/bugzie-addl-info.png" caption="Additional Information"/> 903<figure link="/images/docs/bugzie-addl-info.png" caption="Additional Information"/>
835 904
836<p> 905<p>
837Lastly we select the severity of the bug. Please look this over carefully. In 906Lastly we select the severity of the bug. Please look this over carefully. In
838most cases it's OK to leave it as is and someone will raise/lower it for you. 907most cases it's OK to leave it as is and someone will raise/lower it for you.
839However, if you raise the severity of the bug, please make sure you read it over 908However, if you raise the severity of the bug, please make sure you read it over
840carefully and make sure you're not making a mistake. Here we will set it to the 909carefully and make sure you're not making a mistake. A run down of the various
841default of normal: 910levels is given below.
842</p> 911</p>
912
913<ul>
914 <li>
915 Blocker - The program just plain doesn't want to emerge or is a major
916 hinderance to the system. For example a <c>baselayout</c> issue which
917 prevents a system from booting up would be a sure candidate to be labelled
918 blocker.
919 </li>
920 <li>
921 Critical - The program has loss of data or severe memory leaks during
922 runtime. Again, an important program like say <c>net-tools</c> failing to
923 compile could be labelled critical. It won't prevent the system from
924 starting up, but is quite essential for day to day stuff.
925 </li>
926 <li>
927 Major - The program crashes, but nothing that causes your system severe
928 damage or information loss.
929 </li>
930 <li>
931 Minor - Your program crashes here and there with apparent workarounds.
932 </li>
933 <li>
934 Normal - The default. If you're not sure leave it here unless it's a new
935 build or cosmetic change, then read below for more information.
936 </li>
937 <li>Trivial - Things such as a mispelled word or whitespace clean up. </li>
938 <li>
939 Enhancement - A request to enable a new feature in a program, or more
940 specifically <e>new ebuilds</e>.
941 </li>
942</ul>
843 943
844<figure link="/images/docs/bugzie-sev.png" caption="Severity"/> 944<figure link="/images/docs/bugzie-sev.png" caption="Severity"/>
945
946<p>
947Here, we'll set it to Normal.
948</p>
845 949
846<p> 950<p>
847Now we can submit the bug report by clicking on the Submit Bug Report box. You 951Now we can submit the bug report by clicking on the Submit Bug Report box. You
848will now see your new bug come up. See <uri 952will now see your new bug come up. See <uri
849link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what 953link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what
859<title>Working With Your Bug</title> 963<title>Working With Your Bug</title>
860<section> 964<section>
861<body> 965<body>
862 966
863<p> 967<p>
864looking at the bug, we see the information we provided earlier: 968Looking at the bug, we see the information we provided earlier. You will notice
969that the bug has been assigned to bug-wranglers@gentoo.org. This is the default
970location for Application component bugs.
865</p> 971</p>
866 972
867<figure link="/images/docs/bugzie-new-basic.png" caption="New Bug Basic Information"/> 973<figure link="/images/docs/bugzie-new-basic.png" caption="New Bug Basic Information"/>
868 974
869<p> 975<p>
870And our details are there too: 976The details we entered about the bug are available as well.
871</p> 977</p>
872 978
873<figure link="/images/docs/bugzie-new-details.png" caption="New Bug Details"/> 979<figure link="/images/docs/bugzie-new-details.png" caption="New Bug Details"/>
874 980
875<p> 981<p>
876Now as you can see, the bug has been assigned to bug-wranglers@gentoo.org. This 982However, bug-wranglers (usually) won't fix our bugs, so we'll reassign it to
877is the default location for Application component bugs. However, bug-wranglers 983someone that can (you can let bug-wranglers re-assign it for you as well). For
878(usually) won't fix our bugs, so we'll reassign it to someone that can (you can
879let bug-wranglers re-assign it for you as well). For this we use the package's
880metadata.xml. You can normally find them in 984this we use the package's metadata.xml. You can normally find them in
881/usr/portage/category/package/metadata.xml. Here's one I've made up for foobar2: 985<path>/usr/portage/category/package/metadata.xml</path>. Here's one I've made up
986for foobar2.
882</p> 987</p>
988
989<note>
990You have to be the reporter of the bug or a member of certain Gentoo Bugzilla
991groups (like Gentoo Developers) to be able to reassign bugs.
992</note>
883 993
884<pre caption="metadata.xml"> 994<pre caption="metadata.xml">
885&lt;?xml version="1.0" encoding="UTF-8"?&gt; 995&lt;?xml version="1.0" encoding="UTF-8"?&gt;
886&lt;!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"&gt; 996&lt;!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"&gt;
887&lt;pkgmetadata&gt; 997&lt;pkgmetadata&gt;
895&lt;/longdescription&gt; 1005&lt;/longdescription&gt;
896&lt;/pkgmetadata&gt; 1006&lt;/pkgmetadata&gt;
897</pre> 1007</pre>
898 1008
899<p> 1009<p>
900Notice the maintainer section.T his lists the maintainer of the package, which 1010Notice the maintainer section. This lists the maintainer of the package, which
901in this case is myself, Chris White. The email listed is chriswhite@gentoo.org. 1011in this case is myself, Chris White. The email listed is chriswhite@gentoo.org.
902We will use this to re-assign the bug to the proper person. To do this, click 1012We will use this to re-assign the bug to the proper person. To do this, click
903the bubble next to Reassign bug to, then fill in the email: 1013the bubble next to Reassign bug to, then fill in the email.
904</p> 1014</p>
905 1015
906<note> 1016<note>
907A package without a metadata.xml file should be re-assigned to 1017A bug for a package without a metadata.xml file should be re-assigned to
908maintainer-needed@gentoo.org. 1018maintainer-needed@gentoo.org and a package that needs a Gentoo Developer to
1019maintain should be assigned to maintainer-wanted@gentoo.org.
909</note> 1020</note>
910 1021
911<figure link="/images/docs/bugzie-reassign.png" caption="Bug Reassignment"/> 1022<figure link="/images/docs/bugzie-reassign.png" caption="Bug Reassignment"/>
912 1023
913<p> 1024<p>
920</p> 1031</p>
921 1032
922<figure link="/images/docs/bugzie-new-attach.png" caption="New Attachment"/> 1033<figure link="/images/docs/bugzie-new-attach.png" caption="New Attachment"/>
923 1034
924<p> 1035<p>
925Now we have to attach the log. We click on the "Browse..." button under "File" 1036Now we have to attach the log. Let's go throught it step wise.
926and select the strace log. For Description, we'll put "strace log". Content-Type 1037</p>
927is what kind of file we're attaching. A common mistake is to set it to 1038
928auto. In most cases it's best to manually set it. Our log file is a 1039<ul>
929plain text file, so we select "plain text (text/plain)". Obsoletes are for when 1040 <li>
930you are attaching a revision to a previously attached file. You can simply click 1041 File - This is the location of the file in your machine. In this example,
931a check box next to the old file and Bugzilla will cross it out in the bug, 1042 the location of <path>strace.log</path>. You can use the "Browse..." button
932indicating that the attachment has been obsoleted. Reassignment means you want 1043 to select the file, or enter the path directly in the text field.
933to take the bug yourself. I rarely tend to use this.. and I don't think you will 1044 </li>
934need to at some point (unless you create great patches and we don't care about 1045 <li>
935you taking our bugs ;). Comments are for leaving comments about the file you're 1046 Description - A short one liner, or a few wors describing the attachment.
936posting. We'll put "Here is the strace file you requested". Now we have 1047 We'll just enter strace.log here, since that's quite self-explanatory.
937something like this: 1048 </li>
1049 <li>
1050 Content Type - This is the type of the file we're attaching to the bug.
1051 </li>
1052 <li>
1053 Obsoletes - If there were attachements submitted to the bug before the
1054 current one, you have an option of declaring them obsoleted by yours. Since
1055 we have no prior attachments to this bug, we need not bother.
1056 </li>
1057 <li>
1058 Comment - Enter comments that will be visible along with the attachments.
1059 You could elaborate on the attachment here, if needed.
1060 </li>
1061</ul>
1062
938</p> 1063<p>
1064With respect to Content Type, here are a few more details. You can check the
1065"patch" checkbox if you're submitting a patch. Otherwise, you could ask
1066Bugzilla to "auto-detect" the file type (not advisable). The other options are
1067"select from list", which is most frequently used. Use plain text (text/plain)
1068for <e>most</e> attachments except binary files like images (which can use
1069image/gif, image/jpeg or image/png depending on type) or compressed files like
1070.tar.bz2 which would use application/octet-stream as content type.
1071</p>
1072
939 1073
940<figure link="/images/docs/bugzie-new-attach-comp.png" caption="New Attachment Completed"/> 1074<figure link="/images/docs/bugzie-new-attach-comp.png" caption="New Attachment Completed"/>
941 1075
942<p> 1076<p>
943We Submit the patch and it is now reflected on the bug report. 1077We submit <path>strace.log</path> and it is reflected on the bug report.
944</p> 1078</p>
945 1079
946<figure link="/images/docs/bugzie-strace.png" caption="Attached strace log"/> 1080<figure link="/images/docs/bugzie-strace.png" caption="Attached strace log"/>
947 1081
948<p> 1082<p>
949Now, while we're waiting another person notices your bug during step 1 of the 1083We've mentioned before that sometimes ebuilds will tell you to attach a file in
950Guided Format. This person wants to see the status of the bug as well. He or 1084the emerge error. An example can be seen below.
951she may do so by putting their email in the Add CC field like so: 1085</p>
1086
1087<pre caption="Example File Attachment Request">
1088configure: error: PNG support requires ZLIB. Use --with-zlib-dir=&lt;DIR&gt;
1089
1090!!! Please attach the config.log to your bug report:
1091!!! /var/tmp/portage/php-5.0.3-r1/work/php-5.0.3/config.log
1092
1093!!! ERROR: dev-php/php-5.0.3-r1 failed.
1094!!! Function econf, Line 485, Exitcode 0
1095!!! econf failed
1096!!! If you need support, post the topmost build error, NOT this status message.
1097</pre>
1098
1099<p>
1100Please attach any file mentioned like this to your bug report.
1101</p>
1102
1103<p>
1104While we're doing all this, suppose another person finds your bug by searching
1105through bugzilla and is curious to keep track of the bug, they may do so by
1106putting their email in the Add CC field of the bug as shown below. You could
1107also keep track of other bugs by following the same method.
952</p> 1108</p>
953 1109
954<figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/> 1110<figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/>
955 1111
956<note> 1112<note>
957Email addresses must be registered with bugzilla. In order to CC multiple 1113Email addresses must be registered with Gentoo Bugzilla. In order to CC multiple
958addresses, simply separate them with commas or spaces. 1114addresses, simply separate them with commas or spaces.
959</note> 1115</note>
960 1116
961<p> 1117<p>
962After all this work, the bug can undergo various status markings. Here's a few: 1118After all this work, the bug can undergo various status markings. This is
1119usually done by the Gentoo Developers and sometimes by the reporter. The
1120following are the various possible states a bug may go through during its
1121lifetime.
963</p> 1122</p>
964 1123
965<ul> 1124<ul>
966 <li> 1125 <li>
967 UNCONFIRMED - You're generally not going to see this too often. This 1126 UNCONFIRMED - You're generally not going to see this too often. This means
968 means that a bug reporter has opened a bug using the advanced method and is 1127 that a bug reporter has opened a bug using the advanced method and is
969 uncertain his or her bug is an actual bug. 1128 uncertain his or her bug is an actual bug.
970 </li>
971 <li> 1129 </li>
972 NEW - Bugs that are first opened are considered new. 1130 <li>NEW - Bugs that are first opened are considered new.</li>
973 </li>
974 <li> 1131 <li>
975 ASSIGNED - When the person you've assigned the bug too validates your 1132 ASSIGNED - When the person you've assigned the bug too validates your bug,
976 bug, it will often receive ASSIGNED status while they figure out the issue. 1133 it will often receive ASSIGNED status while they figure out the issue.
977 This let's you know that they've accepted your bug as a real bug. 1134 This lets you know that they've accepted your bug as a real bug.
978 </li>
979 <li> 1135 </li>
1136 <li>
980 REOPENED - Someone has resolved a bug and you think the solution is not 1137 REOPENED - Someone has resolved a bug and you think the solution is not
981 feasible or the problem still persists. At this point, you may re-open the 1138 feasible or the problem still persists. At this point, you may re-open the
982 bug. However <b>please do not abuse this</b>. If a developer closes the bug a 1139 bug. Please <b>do not abuse this</b>. If a developer closes the bug a
983 second or even third time, chances are that your bug is closed. 1140 second or third time, chances are that your bug is closed.
984 </li> 1141 </li>
1142 <li>
1143 RESOLVED - A firm decision has been taken on the bug. Usually goes onto
1144 FIXED to indicate the bug is solved and the matter closed although various
1145 other resolutions are possible. We'll look into those a little later.
1146 </li>
1147 <li>
1148 VERIFIED - The steps take to work the bug are correct. This is usually a QA
1149 thing.
1150 </li>
1151 <li>
1152 CLOSED - Basically means RIP for the bug and it's buried under the never
1153 ending flow of new bugs.
1154 </li>
985</ul> 1155</ul>
986 1156
987<p> 1157<p>
988Now shortly afterward, I find the error in the strace log. I resolve the bug 1158Now shortly afterward, we find the error in the strace log and fix the bug and
989as RESOLVED FIXED and say that there was a change in the location of 1159mark it as RESOLVED FIXED and mention that there was a change in the location
990configuration files, and that I will update the ebuild with a warning about it. 1160of configuration files, and that I will update the ebuild with a warning about
991The bug now becomes resolved, and you are displayed with this: 1161it. The bug now becomes resolved, and you are shown the following.
992</p> 1162</p>
993 1163
994<figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/> 1164<figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/>
995 1165
996<p> 1166<p>
997Also note the section here: 1167A little below, you'll see the following:
998</p> 1168</p>
999 1169
1000<figure link="/images/docs/bugzie-options.png" caption="Bug Options"/> 1170<figure link="/images/docs/bugzie-options.png" caption="Bug Options"/>
1001 1171
1002<p> 1172<p>
1003This gives you the option of Reopening the bug if you wish to (i.e. the developer 1173This gives you the option of Reopening the bug if you wish to (i.e. the
1004thinks it's resolved but it's really not to your standards). Now our bug is 1174developer thinks it's resolved but it's really not to your standards). Now our
1005fixed! However, different resolutions can occur. Here's a small list: 1175bug is fixed! However, different resolutions can occur. Here's a small list:
1006</p> 1176</p>
1007 1177
1008<ul> 1178<ul>
1009 <li> 1179 <li>
1010 FIXED - The bug is fixed, follow the instructions to resolve your 1180 FIXED - The bug is fixed, follow the instructions to resolve your issue.
1011 issue.
1012 </li>
1013 <li> 1181 </li>
1182 <li>
1014 INVALID - You did not do something specifically documented, causing the 1183 INVALID - You did not do something specifically documented, causing the
1015 bug 1184 bug.
1016 </li>
1017 <li> 1185 </li>
1018 DUPLICATE - You didn't use this guide and reported a duplicate bug 1186 <li>DUPLICATE - You didn't use this guide and reported a duplicate bug.</li>
1019 :) 1187 <li>
1020 </li> 1188 WORKSFORME - Developer/person assigned the bug cannot reproduce your error.
1021 <li> 1189 </li>
1022 WORKSFORME - Developer/person assigned the bug cannot reproduce your 1190 <li>
1023 error 1191 CANTFIX - Somehow the bug cannot be solved because of certain
1192 circumstances. These circumstances will be noted by the person taking the
1193 bug.
1024 </li> 1194 </li>
1195 <li>
1196 WONTFIX - This is usually applied to new ebuilds or feature requests.
1197 Basically the developer does not want to add a certain feature because it
1198 is not needed, a better alternative exists, or it's just plain broken.
1199 Sometimes you may be given a solution to get said issue resolved.
1200 </li>
1201 <li>
1202 UPSTREAM - The bug cannot be fixed by the Gentoo development team, and have
1203 requested you take the problem upstream (the people that actually made the
1204 program) for review. Upstream has a few ways of handling bugs. These
1205 include mailing lists, irc channels, and even bug reporting systems. If
1206 you're not sure how to contact them, ask in the bug and someone will point
1207 you to the right direction.
1208 </li>
1025</ul> 1209</ul>
1026 1210
1211<p>
1212Sometimes, before the bug can be resolved, a developer may request that you
1213test an updated ebulid. In the next chapter we'll take a look at testing
1214ebuilds.
1215</p>
1216
1027</body> 1217</body>
1218</section>
1219</chapter>
1220
1221<chapter>
1222<title>Testing Ebuilds</title>
1028</section> 1223<section>
1224<title>Getting The Files</title>
1225<body>
1029 1226
1227<p>
1228Let's say that you reported a bug for the foobar2 compile fix from earlier. Now
1229developers might find out what the problem is and might need you to test the
1230ebuild for them to be sure it works for you as well:
1231</p>
1232
1233<figure link="/images/docs/bugzie-ebuild-request.png" caption="Ebuild Test Request"/>
1234
1235<p>
1236Some rather confusing vocabulary is used here. First off, let's see what an
1237overlay is. An overlay is a special directory like <path>/usr/portage</path>,
1238the difference being that when you <c>emerge sync</c>, files contained within it
1239will not be deleted. Luckily, a special <path>/usr/local/portage</path>
1240directory is created for that purpose. Let's go ahead and set our portage
1241overlay in<path>/etc/make.conf</path>. Open make.conf up in your favorite editor
1242and add this towards the end.
1243</p>
1244
1245<pre caption="Setting Up PORTDIR_OVERLAY">
1246PORTDIR_OVERLAY="/usr/local/portage"
1247</pre>
1248
1249<p>
1250Now we'll want to create the appropriate directories to put our test ebuild
1251files in. In this case, we're supposed to put them in sys-apps/foobar2. You'll
1252notice that the second comment asks for a files directory for the patch. The
1253files directory holds the digests (md5sums of files for a particular version of
1254a package) and any other required files that aren't included with the standard
1255source archive (patches, init.d scripts, etc). This is a subdir in the package
1256directory called files. Go ahead and create these directories:
1257</p>
1258
1259<pre caption="Setting Up The Category And Package Directories">
1260# <i>mkdir -p /usr/local/portage/sys-apps/foobar2/files</i>
1261</pre>
1262
1263<note>
1264The -p in mkdir creates not only the directory you want but also any missing
1265parent directories as well (sys-apps and foobar2 in this case).
1266</note>
1267
1268<p>
1269Ok now, we can go ahead and download the files. First, download the ebuild
1270into <path>/usr/local/portage/sys-apps/foobar2</path>, and then add the patch
1271to <path>/usr/local/portage/sys-apps/foobar2/files</path>. Now that we have the
1272files, we can begin working on testing the ebuild.
1273</p>
1274
1275</body>
1276</section>
1277<section>
1278<title>Testing The ebuild</title>
1279<body>
1280
1281<p>
1282The process to create an ebuild that can be used by emerge is fairly simple. You
1283must create a Manifest and a digest file for the ebuild. This can be done with
1284the ebuild command. Run it as shown.
1285</p>
1286
1287<pre caption="Creating the Manifest and digest files">
1288# <i>ebuild foobar2-1.0.ebuild digest</i>
1289&gt;&gt;&gt; Generating digest file...
1290&lt;&lt;&lt; foobar2-1.0.tar.bz2
1291&gt;&gt;&gt; Generating manifest file...
1292&lt;&lt;&lt; foobar2-1.0.ebuild
1293&lt;&lt;&lt; files/digest-foobar2-1.0
1294&lt;&lt;&lt; files/foobar2-1.0-Makefile.patch
1295&gt;&gt;&gt; Computed message digests.
1296</pre>
1297
1298<p>
1299Now let's test to see if it works as it should.
1300</p>
1301
1302<pre caption="Testing With emerge -pv">
1303# <i>emerge -pv foobar2</i>
1304
1305These are the packages that I would merge, in order:
1306
1307Calculating dependencies ...done!
1308[ebuild N ] sys-apps/foobar2-1.0 0 kB [1]
1309
1310Total size of downloads: 0 kB
1311Portage overlays:
1312 [1] /usr/local/portage
1313</pre>
1314
1315<p>
1316It does seem to have worked! You'll notice the [1] next to the [ebuild] line.
1317That points to <path>/usr/local/portage</path>, which is the overlay we created
1318earlier. Now we go ahead and emerge the package.
1319</p>
1320
1321<pre caption="Emerge Result">
1322# <i>emerge foobar2</i>
1323 Calculating dependencies ...done!
1324<comment>(compile info snipped)</comment>
1325>>> Unpacking foobar2-1.0.tar.bz2 to /var/tmp/portage/foobar2-1.0/work
1326 * Applying foobar2-1.0-Makefile.patch ... [ ok ]
1327<comment>(compile info snipped)</comment>
1328>>> Merging sys-apps/foobar2-1.0 to /
1329>>> chris +sandbox(preinst)
1330--- /usr/
1331--- /usr/bin/
1332>>> /usr/bin/foobar2
1333</pre>
1334
1335<p>
1336In the first section we see that the emerge started off as it should. The second
1337section shows our patch being applied successfully by the "[ ok ]" status
1338message to the right. The last section tells us the program compiled ok. The
1339patch works! Now we can go and let the developer know that their patch works
1340fine, and that they can commit the fix to portage.
1341</p>
1342
1343</body>
1344</section>
1030<section> 1345<section>
1031<title>Conclusion</title> 1346<title>Conclusion</title>
1032<body> 1347<body>
1033 1348
1034<p> 1349<p>
1035This concludes the howto on working with Bugzilla. I hope you find this useful. 1350This concludes the howto on working with Bugzilla. I hope you find this useful.
1036If you have any questions, comments, or ideas regarding this document, please 1351If you have any questions, comments, or ideas regarding this document, please
1037send them to me at <mail 1352send them to me at <mail>chriswhite@gentoo.org</mail>. Special thanks go to
1038link="chriswhite@gentoo.org">chriswhite@gentoo.org</mail>. Special
1039thanks go to moreon for his notes on -g flags and compile errors, the people at 1353moreon for his notes on -g flags and compile errors, the people at #gentoo-bugs
1040#gentoo-bugs for helping out with bug-wrangling, and Griffon26 for his notes on 1354for helping out with bug-wrangling, Griffon26 for his notes on
1041maintainer-needed. 1355maintainer-needed, robbat2 for general suggestions and fox2mike for fixing up
1356the doc and adding stuff as needed.
1042</p> 1357</p>
1043 1358
1044</body> 1359</body>
1045</section> 1360</section>
1046</chapter> 1361</chapter>

Legend:
Removed from v.1.1  
changed lines
  Added in v.1.6

  ViewVC Help
Powered by ViewVC 1.1.20