/[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.10
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.10 2007/04/01 10:35:45 nightmorph 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.9</version>
24<date>2005-07-07</date> 24<date>2007-04-01</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
297with debugging symbols. However, as shown above, this increase in file size can 314the one with debugging symbols. However, as shown above, this increase in file
298be worth it if presenting debug information to developers. Now that we have 315size can be worth it if presenting debug information to developers. The
299obtained the backtrace, we can save it to a file by copying and pasting from the 316backtrace can be saved to a file by copying and pasting from the terminal (if
300terminal (if it's a non-x based terminal, you can use gpm. To keep this doc 317it's a non-x based terminal, you can use gpm. To keep this doc simple, I
301simple, I recommend you read up on the documentation for gpm to see how to copy 318recommend you read up on the <uri link="/doc/en/gpm.xml#doc_chap4">documentation
302and paste with it). Now that we're done with <c>gdb</c>, we can quit. 319for gpm</uri> to see how to copy and paste with it). Now that we're done with
320<c>gdb</c>, we can quit.
303</p> 321</p>
304 322
305<pre caption="Quitting GDB"> 323<pre caption="Quitting GDB">
306(gdb) quit 324(gdb) <i>quit</i>
307The program is running. Exit anyway? (y or n) y 325The program is running. Exit anyway? (y or n) <i>y</i>
308$ 326$
309</pre> 327</pre>
310 328
311<p> 329<p>
312This ends the walk-through of <c>gdb</c>. Using <c>gdb</c>, I hope that you will 330This 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 331be 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 332of 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 333ways is through improper file access. We can find those using a nifty little
316tool called <c>strace</c>. 334tool called <c>strace</c>.
317</p> 335</p>
325<section> 343<section>
326<title>Introduction</title> 344<title>Introduction</title>
327<body> 345<body>
328 346
329<p> 347<p>
330Programs often use files to get configuration information, get access 348Programs often use files to fetch configuration information, access hardware or
331to hardware, or write logs. Often a program attempts to reach such files 349write logs. Sometimes, a program attempts to reach such files incorrectly. A
332incorrectly. A program called <c>strace</c> was created to help deal with 350tool 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 351traces 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 352files. 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 353updated version of foobar. However, during the change over to foobar2, you notice
336changeover to foobar2, you notice all your configurations are missing! In 354all 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 355say "foo", but now it's using the default "bar".
338"bar".
339</p> 356</p>
340 357
341<pre caption="Foobar2 With an invalid configuration"> 358<pre caption="Foobar2 With an invalid configuration">
342$ <i>./foobar2</i> 359$ <i>./foobar2</i>
343Configuration says: bar 360Configuration says: bar
353<section> 370<section>
354<title>Using strace to track the issue</title> 371<title>Using strace to track the issue</title>
355<body> 372<body>
356 373
357<p> 374<p>
358Let's have <c>strace</c> log the results of the system calls. To do this, we run 375We 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: 376<c>strace</c> with the -o[file] arguments. Let's use it on foobar2 as shown.
360</p> 377</p>
361 378
362<pre caption="Running foobar2 through strace"> 379<pre caption="Running foobar2 through strace">
363# <i>strace -ostrace.log ./foobar2</i> 380# <i>strace -ostrace.log ./foobar2</i>
364</pre> 381</pre>
365 382
366<p> 383<p>
367This creates a file called strace.log in the current directory. We check the 384This creates a file called <path>strace.log</path> in the current directory. We
368file, and shown below are the relevant parts from the file. 385check the file, and shown below are the relevant parts from the file.
369</p> 386</p>
370 387
371<pre caption="A Look At the strace Log"> 388<pre caption="A Look At the strace Log">
372open(".foobar2/config", O_RDONLY) = 3 389open(".foobar2/config", O_RDONLY) = 3
373read(3, "bar", 3) = 3 390read(3, "bar", 3) = 3
376<p> 393<p>
377Aha! So There's the problem. Someone moved the configuration directory to 394Aha! 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 395<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 396reading 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 397maintainer 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. 398config file from <path>.foobar</path> and modify it to produce the correct
399results.
382</p> 400</p>
383 401
384</body> 402</body>
385</section> 403</section>
386<section> 404<section>
388<body> 406<body>
389 407
390<p> 408<p>
391Now we've taken care of finding run time bugs. These bugs prove to be 409Now 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 410problematic 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 411the 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. 412look at how to address <c>emerge</c> compile errors.
395</p> 413</p>
396 414
397</body> 415</body>
398</section> 416</section>
404<title>Introduction</title> 422<title>Introduction</title>
405<body> 423<body>
406 424
407<p> 425<p>
408<c>emerge</c> errors, such as the one displayed earlier, can be a major cause 426<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 427of 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, 428the health of Gentoo. Let's take a look at a sample ebuild, foobar2, which
411which contains some build errors. 429contains some build errors.
412</p> 430</p>
413 431
414</body> 432</body>
415</section> 433</section>
416<section id="emerge_error"> 434<section id="emerge_error">
434!!! Make failed! 452!!! Make failed!
435!!! If you need support, post the topmost build error, NOT this status message 453!!! If you need support, post the topmost build error, NOT this status message
436</pre> 454</pre>
437 455
438<p> 456<p>
439The compile is going smoothly, then it stops and presents an error message. This 457The 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 458particular error can be split into 3 different sections, The compile messages, the build
441error, and the emerge error message as shown below. 459error, and the emerge error message as shown below.
442</p> 460</p>
443 461
444<pre caption="Parts of the error"> 462<pre caption="Parts of the error">
445<comment>(Compile Error)</comment> 463<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 464gcc -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 465gcc -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 466gcc -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 467gcc -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 468
451<comment>(Build Error)</comment> 469<comment>(Build Error)</comment>
452foobar2.c:1:17: ogg.h: No such file or directory 470foobar2.c:1:17: ogg.h: No such file or directory
453make: *** [foobar2.o] Error 1 471make: *** [foobar2.o] Error 1
454 472
455<comment>(Emerge Error)</comment> 473<comment>(emerge Error)</comment>
456!!! ERROR: sys-apps/foobar2-1.0 failed. 474!!! ERROR: sys-apps/foobar2-1.0 failed.
457!!! Function src_compile, Line 19, Exitcode 2 475!!! Function src_compile, Line 19, Exitcode 2
458!!! Make failed! 476!!! Make failed!
459!!! If you need support, post the topmost build error, NOT this status message 477!!! If you need support, post the topmost build error, NOT this status message
460</pre> 478</pre>
461 479
462<p> 480<p>
463The compile is what leads up to the error. Most often, it's good to at least 481The 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 482at 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 483where the compilation was at when the error occurred.
466developer needs. When you see "make: ***", this is often where the error has 484</p>
467occurred. Normally, you can copy and paste 10 lines above it and the developer 485
468will be able to address the issue. However, this may not always work and we'll 486<p>
469take a look at an alternative shortly. The emerge error is what <c>emerge</c> 487Make 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 488you see "make: ***", this is often where the error has occurred. Normally, you
489can copy and paste 10 lines above it and the developer will be able to address
490the issue. However, this may not always work and we'll take a look at an
491alternative shortly.
492</p>
493
494<p>
495The emerge error is what <c>emerge</c> throws out as an error. Sometimes, this
496might 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 497posting 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 498make 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 499what 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: ***" 500the 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. 501"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 502emerge 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. 503let'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. 504everything. That's where PORT_LOGDIR comes into play.
479</p> 505</p>
480 506
481</body> 507</body>
482</section> 508</section>
483<section> 509<section>
484<title>emerge and PORT_LOGDIR</title> 510<title>emerge and PORT_LOGDIR</title>
485<body> 511<body>
486 512
487<p> 513<p>
488PORT_LOGDIR is a portage variable that sets up a log directory for separate 514PORT_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 515emerge 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 516emerge 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: 517location <path>/var/log/portage</path>. We'll use that for our log directory:
492</p> 518</p>
493 519
494<note> 520<note>
495In the default setup, /var/log/portage does not exist, and you will most likely 521In 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. 522most likely have to create it. If you do not, portage will fail to write the
523logs.
497</note> 524</note>
498 525
499<pre caption="emerge-ing With PORT_LOGDIR"> 526<pre caption="emerge-ing With PORT_LOGDIR">
500# <i>PORT_LOGDIR=/var/log/portage emerge foobar2</i> 527# <i>PORT_LOGDIR=/var/log/portage emerge foobar2</i>
501</pre> 528</pre>
536 563
537<p> 564<p>
538<uri link="http://www.bugzilla.org">Bugzilla</uri> is what we at Gentoo use to 565<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 566handle 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 567available 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 568consistency, 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 569over to <uri link="https://bugs.gentoo.org">Gentoo Bugs</uri> to see how it
543looks. 570looks.
544</p> 571</p>
545 572
546<p> 573<p>
547One of the most frustrating thing for developers and bug-wranglers is finding 574One 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 575duplicate 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 576use 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 577search 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 578you have one that's similar. For this example, we're going to use the xclass
552emerge error that was used earlier: 579emerge error that was used earlier.
553</p> 580</p>
554 581
555<pre caption="xclass emerge error"> 582<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: 583/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 584warning: #warning This file includes at least one deprecated or antiquated
582!!! 'emake shared' failed 609!!! 'emake shared' failed
583</pre> 610</pre>
584 611
585<p> 612<p>
586So to begin searching, we head over to the <uri 613So to begin searching, we head over to the <uri
587link="http://bugs.gentoo.org/">Bugzilla Homepage</uri>. 614link="https://bugs.gentoo.org/">Bugzilla Homepage</uri>.
588</p> 615</p>
589 616
590<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/> 617<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>
591 618
592<p> 619<p>
593In order to begin our search, we'll click on "Query Existing bug reports". The 620We'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 621over 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 622results 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 623duplicate bug. Once we click on the query screen, we reach the next page:
597screen, we reach the next page:
598</p> 624</p>
599 625
600<figure link="/images/docs/bugzie-search.png" caption="Bugzilla Search Page"/> 626<figure link="/images/docs/bugzie-search.png" caption="Bugzilla Search Page"/>
601 627
602<note> 628<note>
603If you've used the Advanced Search before, you'll most likely see that screen 629If you've used the Advanced Search before, you'll most likely see that screen
604instead. 630instead.
605</note> 631</note>
606 632
607<p> 633<p>
608Proceed on clicking the "Advanced Search" link to bring up the Advanced 634Proceed by clicking on the "Advanced Search" link to bring up the Advanced
609Search page: 635Search page.
610</p> 636</p>
611 637
612<figure link="/images/docs/bugzie-adv-search.png" caption="Advanced Search Page"/> 638<figure link="/images/docs/bugzie-adv-search.png" caption="Advanced Search Page"/>
613 639
614<p> 640<p>
615This is how the Advanced Search Page looks like. While it may seem overwhelming 641This 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 642at first, we're going to look at a few simple areas to narrow down the rather
617vague searches bugzilla returns. 643vague searches bugzilla returns.
618</p> 644</p>
619 645
620<figure link="/images/docs/bugzie-content.png" caption="Content"/> 646<figure link="/images/docs/bugzie-content.png" caption="Content"/>
621 647
622<p> 648<p>
623The first field is the summary of the bug. Here we're simply going to put the 649The 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 650name 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 651removing 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). 652(highly unlikely, but we've seen a fair share of strange bug reports).
627</p> 653</p>
628 654
629<p> 655<p>
630Product, Component, and Version should all be set to the default. This 656Product, Component, and Version should all be set to the default. This
631prevents us from being too specific and missing all the bugs. 657prevents us from being too specific and missing all the bugs.
632</p> 658</p>
633 659
634<p> 660<p>
635Comment is the important part. Use comment to list what appears to be a 661Comment 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 662specific 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 663beginning 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 664error. 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 665from interpreting the results the comment the wrong way. Example from the xclass
640emerge error: 666emerge error:
651other xclass compile failure candidates. 677other xclass compile failure candidates.
652</p> 678</p>
653 679
654<p> 680<p>
655URI, Whiteboard, and Keywords can all be left alone. What we've entered so far 681URI, 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: 682should be enough to find our bug. Let's take a look at what we have filled out.
657</p> 683</p>
658 684
659<figure link="/images/docs/bugzie-comp-search.png" caption="Completed Search Form"/> 685<figure link="/images/docs/bugzie-comp-search.png" caption="Completed Search Form"/>
660 686
661<p> 687<p>
662Now we click on the Search button and here come the results: 688Now we click on the Search button and here come the results...
663</p> 689</p>
664 690
665<figure link="/images/docs/bugzie-search-result.png" caption="Search Results"/> 691<figure link="/images/docs/bugzie-search-result.png" caption="Search Results"/>
666 692
667<p> 693<p>
668Only 2 bugs! That's a lot easier to deal with. We click on the first one to 694Only 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: 695check, and sure enough it's the one we're looking for.
670</p> 696</p>
671 697
672<figure link="/images/docs/bugzie-located.png" caption="Bug Located"/> 698<figure link="/images/docs/bugzie-located.png" caption="Bug Located"/>
673 699
674<p> 700<p>
675Not only is it the one we want, but it has also been resolved. By checking the 701Not 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. 702last 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: 703Now, let's see what would have happened if we had not used the advanced search.
678</p> 704</p>
679 705
680<figure link="/images/docs/bugzie-basic-search-result.png" caption="Basic Search Results"/> 706<figure link="/images/docs/bugzie-basic-search-result.png" caption="Basic Search Results"/>
681 707
682<p> 708<p>
713</p> 739</p>
714 740
715<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/> 741<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>
716 742
717<p> 743<p>
718Go ahead and click on "Report a Bug - Using the Guided format". 744Click on "Report a Bug - Using the guided format".
719</p> 745</p>
720 746
721<figure link="/images/docs/bugzie-prod-select.png" caption="Product Selection"/> 747<figure link="/images/docs/bugzie-prod-select.png" caption="Product Selection"/>
722 748
723<p> 749<p>
724As you can see, <b>major</b> emphasis has been placed on putting your bug in the 750As 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, 751right place. Gentoo Linux is where a large majority of bugs go.
752</p>
753
754<p>
726some people will file ebuild bugs in portage development (assumption that 755Despite this, some people will file ebuild bugs in portage development
727portage team handles the portage tree) or infra (assumption that infra has 756(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 757that 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 758simply not how things work.
730there and are presented with the multi-step bug reporting process. 759</p>
760
761<p>
762Another common misconception occurs with our Documentation bugs. For example, a
763user finds a bug with the <uri link="/proj/en/releng/catalyst/">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 link="/proj/en/releng/">Release
767Engineering</uri> team. As a rule of thumb, only documentation under
768<path>http://www.gentoo.org/doc/*</path> is under the GDP. Anything under
769<path>http://www.gentoo.org/proj/*</path> is under the respective teams.
731</p> 770</p>
732 771
733<note> 772<note>
734We would rather see a non-Gentoo Linux bug filed in Gentoo Linux than a Gentoo 773We 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 774has been filed under the same rather than seeing a bug which belongs the Gentoo
775Linux product and filed elsewhere. While neither is preferred, the former is more
736former is more acceptable and understandable (except website bugs.. we might 776acceptable and understandable (except website bugs.. we might have an issue with
737have an issue with that...) 777that...).
738</note> 778</note>
739 779
740<p> 780<p>
741Let us now proceed with Step 1... 781Our bug goes in Gentoo Linux as it's an ebuild bug. We head over there and are
782presented with the multi-step bug reporting process. Let us now proceed with
783Step 1...
742</p> 784</p>
743 785
744<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"/>
745 787
746<p> 788<p>
747The 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
748where 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.
749If 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
750as 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,
751the 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,
752where we give the information. 794where we give the information.
753</p> 795</p>
754 796
755</body> 797</body>
756</section> 798</section>
757<section> 799<section>
758<title>Required Information</title> 800<title>Required Information</title>
759<body> 801<body>
760 802
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"/> 803<figure link="/images/docs/bugzie-basic.png" caption="Basic Information"/>
766 804
767<p> 805<p>
768First, there's the product. This is Gentoo Linux, which we selected earlier. 806Let us take a closer look at what's what.
769Component is where the problem occurs. We use this to help us sort out the 807</p>
770severity of the issue (i.e. baselayout and core systems will be more important 808
771than new ebuilds or application bugs). Here we select Application, as it is an 809<ul>
772application at fault. Hardware platform is what architecture you're running. 810 <li>
773If 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
774this error can occur on multiple architectures, so we'll select All. Operating 812 specific area of Gentoo like Bugzilla (for bugs relating to
775System is what Operating System you're using. Because Gentoo is considered a 813 bugs.gentoo.org), Docs-user(for User Documentation) or Gentoo Linux (for
814 ebuilds and the like).
815 </li>
816 <li>
817 Component is where exactly the problem occurs, more specifically which part
818 of selected product the bug comes under. This makes classification easier.
819 </li>
820 <li>
821 Hardware platform is what architecture you're running. If you were running
822 SPARC, you would set it to SPARC.
823 </li>
824 <li>
825 Operating System is what Operating System you're using. Because Gentoo is
776"Meta-distribution", it can run on other operating systems beside Linux. 826 considered a "Meta-distribution", it can run on other operating systems
777Examples are Gentoo on MacOS, Gentoo on FreeBSD, etc. For this example, 827 beside Linux.
778we'll select All, as this can occur on all types of systems. Build Identifier 828 </li>
779is what is being used to report the bugs (for logging purposes). You can just 829</ul>
780leave this as is. Let's see what we have so far: 830
781</p> 831<p>
832So, for our example bug, we have :
833</p>
834
835<ul>
836 <li>Product - Gentoo Linux (Since it is an ebuild issue)</li>
837 <li>Component - Application (It is an application at fault, foobar2)</li>
838 <li>Hardware Platform - All (This error could occur across architectures)</li>
839 <li>Operation System - All (It could occur on all types of systems)</li>
840</ul>
782 841
783<figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/> 842<figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/>
784 843
785<p> 844<ul>
786That does look good, so we'll begin with the actual report. In this instance, 845 <li>
787we'll use the foobar2 bug as our example. URL is used to point to errors on a 846 Build Identifier is basically the User Agent of the browser that is being
788site someplace (pastebin, etc.). However, doing it inside the bug allows the 847 used to report the bugs (for logging purposes). You can just leave this as
789developers be able to reference to it at any time and is preferred. Then we have 848 is.
849 </li>
850 <li>
851 URL is optional and is used to point to relevant information on another site
852 (upstream bugzilla, release notes on package homepage etc.). You should
853 never use URL to point to pastebins for error messages, logs, <c>emerge
854 --info</c> output, screenshots or similar information. Instead, these should
855 always be attached to the bug.
856 </li>
857 <li>
790the summary. In the summary, you should put the package category, name, and 858 In the Summary, you should put the package category, name, and number.
859 </li>
860</ul>
861
862<p>
791number. Not including the category really isn't too bad, but it's recommended. 863Not 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 864recommended. 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 865you'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 866number 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 867not 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 868to 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 869isn'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. 870the package information, you'll want to include a small description of the
799Here's an example: 871incident. Here's an example:
800</p> 872</p>
801 873
802<figure link="/images/docs/bugzie-summary.png" caption="Summary"/> 874<figure link="/images/docs/bugzie-summary.png" caption="Summary"/>
803 875
804<p> 876<p>
805Just these simple rules can make handling bugs a lot easier. Next are the 877These 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 878Here we put in the information about the bug. We'll demonstrate with an example:
807example:
808</p> 879</p>
809 880
810<figure link="/images/docs/bugzie-details.png" caption="Details"/> 881<figure link="/images/docs/bugzie-details.png" caption="Details"/>
811 882
812<p> 883<p>
813So now the developer knows why we're filing the bug. They can then try to 884Now 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 885reproduce 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 886problem recur. In this example, we can reproduce it any time simply by running
816foobar2. Let's put that information in: 887foobar2. Let's put that information in.
817</p> 888</p>
818 889
819<figure link="/images/docs/bugzie-reprod.png" caption="Reproduction"/> 890<figure link="/images/docs/bugzie-reprod.png" caption="Reproduction"/>
820 891
821<p> 892<p>
822So now we have explained how we found the bug. Next we want to explain what 893We 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: 894the results we got and what we think they should actually be.
824</p> 895</p>
825 896
826<figure link="/images/docs/bugzie-results.png" caption="Results"/> 897<figure link="/images/docs/bugzie-results.png" caption="Results"/>
827 898
828<p> 899<p>
829Next we put additional information. This can be things such as stack traces, 900We could then provide additional information. This could be things such as
901stack 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. 902much use) of strace logs, but most importantly, your <c>emerge --info</c>
831Here's an example: 903output. Here's an example.
832</p> 904</p>
833 905
834<figure link="/images/docs/bugzie-addl-info.png" caption="Additional Information"/> 906<figure link="/images/docs/bugzie-addl-info.png" caption="Additional Information"/>
835 907
836<p> 908<p>
837Lastly we select the severity of the bug. Please look this over carefully. In 909Lastly 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. 910most 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 911However, 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 912carefully and make sure you're not making a mistake. A run down of the various
841default of normal: 913levels is given below.
842</p> 914</p>
915
916<ul>
917 <li>
918 Blocker - The program just plain doesn't want to emerge or is a major
919 hinderance to the system. For example a <c>baselayout</c> issue which
920 prevents a system from booting up would be a sure candidate to be labelled
921 blocker.
922 </li>
923 <li>
924 Critical - The program has loss of data or severe memory leaks during
925 runtime. Again, an important program like say <c>net-tools</c> failing to
926 compile could be labelled critical. It won't prevent the system from
927 starting up, but is quite essential for day to day stuff.
928 </li>
929 <li>
930 Major - The program crashes, but nothing that causes your system severe
931 damage or information loss.
932 </li>
933 <li>
934 Minor - Your program crashes here and there with apparent workarounds.
935 </li>
936 <li>
937 Normal - The default. If you're not sure leave it here unless it's a new
938 build or cosmetic change, then read below for more information.
939 </li>
940 <li>Trivial - Things such as a mispelled word or whitespace clean up. </li>
941 <li>
942 Enhancement - A request to enable a new feature in a program, or more
943 specifically <e>new ebuilds</e>.
944 </li>
945</ul>
843 946
844<figure link="/images/docs/bugzie-sev.png" caption="Severity"/> 947<figure link="/images/docs/bugzie-sev.png" caption="Severity"/>
948
949<p>
950Here, we'll set it to Normal.
951</p>
845 952
846<p> 953<p>
847Now we can submit the bug report by clicking on the Submit Bug Report box. You 954Now 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 955will now see your new bug come up. See <uri
849link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what 956link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what
851with. 958with.
852</p> 959</p>
853 960
854</body> 961</body>
855</section> 962</section>
963<section>
964<title>Zero-day bump requests</title>
965<body>
966
967<p>
968So far, we've shown what to do when filing a bug. Now let's take a look at what
969<e>not</e> to do.
970</p>
971
972<p>
973Suppose that you've eagerly been following an upstream project's schedule, and
974when you check their homepage, guess what? They just released a new version a
975few minutes ago! Most users would immediately rush over to Gentoo's bugzilla to
976report the new version is available; please bump the existing version and add
977it to Portage, etc. However, this is exactly what you should <b>not</b> do.
978These kinds of requests are called zero-day (or 0-day) bump requests, as they're
979made the same day that a new version is released.
980</p>
981
982<impo>
983<b>Please wait <e>at least</e> 48 hours before reporting a new release on our
984bugzilla.</b> Also, you <e>must</e> check bugzilla before posting your request
985to make sure that someone else hasn't already reported it, or that the Gentoo
986maintainers haven't already dealt with the new version.
987</impo>
988
989<p>
990Why should you wait? First, it's quite rude to demand that Gentoo developers
991drop everything they're doing just to add a new release that came out 15 minutes
992ago. Your zero-day bump request could be marked as INVALID or LATER, as
993developers have plenty of pressing issues to keep them busy. Second, developers
994are usually aware of pending new releases well in advance of users, as they must
995follow upstream quite closely. They already know a new version is on its way.
996In many cases, they will have already opened a bug, or might even already added
997it in Portage as a masked package.
998</p>
999
1000<p>
1001Be smart when testing and requesting new versions of packages. Search bugzilla
1002before posting your bump request -- is there already a bug open? Have you synced
1003lately; is it already in Portage? Has it actually been released by upstream?
1004Basic common sense will go a long way, and will endear you to developers that
1005already have a lot to do. If it's been several days since release and you're
1006sure that there are no open requests for it (and that it's not in Portage), then
1007you can open up a new bug. Be sure to mention that it compiles and runs well on
1008your arch. Any other helpful information you provide is most welcome.
1009</p>
1010
1011<p>
1012Want to see the newest version of your favorite package in Portage? File smart
1013bugs.
1014</p>
1015
1016</body>
1017</section>
856</chapter> 1018</chapter>
857 1019
858<chapter> 1020<chapter>
859<title>Working With Your Bug</title> 1021<title>Working With Your Bug</title>
860<section> 1022<section>
861<body> 1023<body>
862 1024
863<p> 1025<p>
864looking at the bug, we see the information we provided earlier: 1026Looking at the bug, we see the information we provided earlier. You will notice
1027that the bug has been assigned to bug-wranglers@gentoo.org. This is the default
1028location for Application component bugs.
865</p> 1029</p>
866 1030
867<figure link="/images/docs/bugzie-new-basic.png" caption="New Bug Basic Information"/> 1031<figure link="/images/docs/bugzie-new-basic.png" caption="New Bug Basic Information"/>
868 1032
869<p> 1033<p>
870And our details are there too: 1034The details we entered about the bug are available as well.
871</p> 1035</p>
872 1036
873<figure link="/images/docs/bugzie-new-details.png" caption="New Bug Details"/> 1037<figure link="/images/docs/bugzie-new-details.png" caption="New Bug Details"/>
874 1038
875<p> 1039<p>
876Now as you can see, the bug has been assigned to bug-wranglers@gentoo.org. This 1040However, 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 1041someone 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 1042this 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: 1043<path>/usr/portage/category/package/metadata.xml</path>. Here's one I've made up
1044for foobar2.
882</p> 1045</p>
1046
1047<note>
1048You have to be the reporter of the bug or a member of certain Gentoo Bugzilla
1049groups (like Gentoo Developers) to be able to reassign bugs.
1050</note>
883 1051
884<pre caption="metadata.xml"> 1052<pre caption="metadata.xml">
885&lt;?xml version="1.0" encoding="UTF-8"?&gt; 1053&lt;?xml version="1.0" encoding="UTF-8"?&gt;
886&lt;!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"&gt; 1054&lt;!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"&gt;
887&lt;pkgmetadata&gt; 1055&lt;pkgmetadata&gt;
895&lt;/longdescription&gt; 1063&lt;/longdescription&gt;
896&lt;/pkgmetadata&gt; 1064&lt;/pkgmetadata&gt;
897</pre> 1065</pre>
898 1066
899<p> 1067<p>
900Notice the maintainer section.T his lists the maintainer of the package, which 1068Notice 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. 1069in 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 1070We 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: 1071the bubble next to Reassign bug to, then fill in the email.
904</p> 1072</p>
905 1073
906<note> 1074<note>
907A package without a metadata.xml file should be re-assigned to 1075A bug for a package without a metadata.xml file should be re-assigned to
908maintainer-needed@gentoo.org. 1076maintainer-needed@gentoo.org and a package that needs a Gentoo Developer to
1077maintain should be assigned to maintainer-wanted@gentoo.org.
909</note> 1078</note>
910 1079
911<figure link="/images/docs/bugzie-reassign.png" caption="Bug Reassignment"/> 1080<figure link="/images/docs/bugzie-reassign.png" caption="Bug Reassignment"/>
912 1081
913<p> 1082<p>
920</p> 1089</p>
921 1090
922<figure link="/images/docs/bugzie-new-attach.png" caption="New Attachment"/> 1091<figure link="/images/docs/bugzie-new-attach.png" caption="New Attachment"/>
923 1092
924<p> 1093<p>
925Now we have to attach the log. We click on the "Browse..." button under "File" 1094Now 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 1095</p>
927is what kind of file we're attaching. A common mistake is to set it to 1096
928auto. In most cases it's best to manually set it. Our log file is a 1097<ul>
929plain text file, so we select "plain text (text/plain)". Obsoletes are for when 1098 <li>
930you are attaching a revision to a previously attached file. You can simply click 1099 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, 1100 the location of <path>strace.log</path>. You can use the "Browse..." button
932indicating that the attachment has been obsoleted. Reassignment means you want 1101 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 1102 </li>
934need to at some point (unless you create great patches and we don't care about 1103 <li>
935you taking our bugs ;). Comments are for leaving comments about the file you're 1104 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 1105 We'll just enter strace.log here, since that's quite self-explanatory.
937something like this: 1106 </li>
1107 <li>
1108 Content Type - This is the type of the file we're attaching to the bug.
1109 </li>
1110 <li>
1111 Obsoletes - If there were attachements submitted to the bug before the
1112 current one, you have an option of declaring them obsoleted by yours. Since
1113 we have no prior attachments to this bug, we need not bother.
1114 </li>
1115 <li>
1116 Comment - Enter comments that will be visible along with the attachments.
1117 You could elaborate on the attachment here, if needed.
1118 </li>
1119</ul>
1120
938</p> 1121<p>
1122With respect to Content Type, here are a few more details. You can check the
1123"patch" checkbox if you're submitting a patch. Otherwise, you could ask
1124Bugzilla to "auto-detect" the file type (not advisable). The other options are
1125"select from list", which is most frequently used. Use plain text (text/plain)
1126for <e>most</e> attachments except binary files like images (which can use
1127image/gif, image/jpeg or image/png depending on type) or compressed files like
1128.tar.bz2 which would use application/octet-stream as content type.
1129</p>
1130
939 1131
940<figure link="/images/docs/bugzie-new-attach-comp.png" caption="New Attachment Completed"/> 1132<figure link="/images/docs/bugzie-new-attach-comp.png" caption="New Attachment Completed"/>
941 1133
942<p> 1134<p>
943We Submit the patch and it is now reflected on the bug report. 1135We submit <path>strace.log</path> and it is reflected on the bug report.
944</p> 1136</p>
945 1137
946<figure link="/images/docs/bugzie-strace.png" caption="Attached strace log"/> 1138<figure link="/images/docs/bugzie-strace.png" caption="Attached strace log"/>
947 1139
948<p> 1140<p>
949Now, while we're waiting another person notices your bug during step 1 of the 1141We'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 1142the emerge error. An example can be seen below.
1143</p>
1144
1145<pre caption="Example File Attachment Request">
1146configure: error: PNG support requires ZLIB. Use --with-zlib-dir=&lt;DIR&gt;
1147
1148!!! Please attach the config.log to your bug report:
1149!!! /var/tmp/portage/php-5.0.3-r1/work/php-5.0.3/config.log
1150
1151!!! ERROR: dev-php/php-5.0.3-r1 failed.
1152!!! Function econf, Line 485, Exitcode 0
1153!!! econf failed
1154!!! If you need support, post the topmost build error, NOT this status message.
1155</pre>
1156
1157<p>
1158Please attach any file mentioned like this to your bug report.
1159</p>
1160
1161<p>
1162Sometimes a developer might ask you to attach a diff or patch for a file.
1163Standard diff files can be obtained through:
1164</p>
1165
1166<pre caption="Standard Diff Creation">
1167$ <i>cp file file.old</i>
1168$ <i>nano file</i>
1169$ <i>diff -u file.old file</i>
1170</pre>
1171
1172<p>
1173For C/C++ source files, the <b>-p</b> flag is added to show what function calls
1174the diff applies to:
1175</p>
1176
1177<pre caption="Diff-ing C/C++ source">
1178$ <i>cp file.c file.c.old</i>
1179$ <i>nano file.c</i>
1180$ <i>diff -up file.c.old file.c</i>
1181</pre>
1182
1183<p>
1184The documentation team will require the flag combination <b>-Nt</b> as well as
1185<b>-u</b>. This mainly has to do with tab expansion. You can create such a diff
1186with:
1187</p>
1188
1189<pre caption="Documentation diffs">
1190$<i> cp file.xml file.xml.old</i>
1191$<i> nano file.xml</i>
1192$<i> diff -Nut file.xml.old file.xml</i>
1193</pre>
1194
1195<p>
1196And your diff is created. While we're doing all this, suppose another person
1197finds your bug by searching through bugzilla and is curious to keep track of
951she may do so by putting their email in the Add CC field like so: 1198the bug, they may do so by putting their email in the Add CC field of the bug
1199as shown below. You could also keep track of other bugs by following the same
1200method.
952</p> 1201</p>
953 1202
954<figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/> 1203<figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/>
955 1204
956<note> 1205<note>
957Email addresses must be registered with bugzilla. In order to CC multiple 1206Email addresses must be registered with Gentoo Bugzilla. In order to CC multiple
958addresses, simply separate them with commas or spaces. 1207addresses, simply separate them with commas or spaces.
959</note> 1208</note>
960 1209
961<p> 1210<p>
962After all this work, the bug can undergo various status markings. Here's a few: 1211After all this work, the bug can undergo various status markings. This is
1212usually done by the Gentoo Developers and sometimes by the reporter. The
1213following are the various possible states a bug may go through during its
1214lifetime.
963</p> 1215</p>
964 1216
965<ul> 1217<ul>
966 <li> 1218 <li>
967 UNCONFIRMED - You're generally not going to see this too often. This 1219 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 1220 that a bug reporter has opened a bug using the advanced method and is
969 uncertain his or her bug is an actual bug. 1221 uncertain his or her bug is an actual bug.
970 </li>
971 <li> 1222 </li>
972 NEW - Bugs that are first opened are considered new. 1223 <li>NEW - Bugs that are first opened are considered new.</li>
973 </li>
974 <li> 1224 <li>
975 ASSIGNED - When the person you've assigned the bug too validates your 1225 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. 1226 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. 1227 This lets you know that they've accepted your bug as a real bug.
978 </li>
979 <li> 1228 </li>
1229 <li>
980 REOPENED - Someone has resolved a bug and you think the solution is not 1230 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 1231 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 1232 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. 1233 second or third time, chances are that your bug is closed.
984 </li> 1234 </li>
1235 <li>
1236 RESOLVED - A firm decision has been taken on the bug. Usually goes onto
1237 FIXED to indicate the bug is solved and the matter closed although various
1238 other resolutions are possible. We'll look into those a little later.
1239 </li>
1240 <li>
1241 VERIFIED - The steps take to work the bug are correct. This is usually a QA
1242 thing.
1243 </li>
1244 <li>
1245 CLOSED - Basically means RIP for the bug and it's buried under the never
1246 ending flow of new bugs.
1247 </li>
985</ul> 1248</ul>
986 1249
987<p> 1250<p>
988Now shortly afterward, I find the error in the strace log. I resolve the bug 1251Now 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 1252mark 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. 1253of configuration files, and that I will update the ebuild with a warning about
991The bug now becomes resolved, and you are displayed with this: 1254it. The bug now becomes resolved, and you are shown the following.
992</p> 1255</p>
993 1256
994<figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/> 1257<figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/>
995 1258
996<p> 1259<p>
997Also note the section here: 1260A little below, you'll see the following:
998</p> 1261</p>
999 1262
1000<figure link="/images/docs/bugzie-options.png" caption="Bug Options"/> 1263<figure link="/images/docs/bugzie-options.png" caption="Bug Options"/>
1001 1264
1002<p> 1265<p>
1003This gives you the option of Reopening the bug if you wish to (i.e. the developer 1266This 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 1267developer 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: 1268bug is fixed! However, different resolutions can occur. Here's a small list:
1006</p> 1269</p>
1007 1270
1008<ul> 1271<ul>
1009 <li> 1272 <li>
1010 FIXED - The bug is fixed, follow the instructions to resolve your 1273 FIXED - The bug is fixed, follow the instructions to resolve your issue.
1011 issue.
1012 </li>
1013 <li> 1274 </li>
1275 <li>
1014 INVALID - You did not do something specifically documented, causing the 1276 INVALID - You did not do something specifically documented, causing the
1015 bug 1277 bug.
1016 </li>
1017 <li> 1278 </li>
1018 DUPLICATE - You didn't use this guide and reported a duplicate bug 1279 <li>DUPLICATE - You didn't use this guide and reported a duplicate bug.</li>
1019 :) 1280 <li>
1020 </li> 1281 WORKSFORME - Developer/person assigned the bug cannot reproduce your error.
1021 <li> 1282 </li>
1022 WORKSFORME - Developer/person assigned the bug cannot reproduce your 1283 <li>
1023 error 1284 CANTFIX - Somehow the bug cannot be solved because of certain
1285 circumstances. These circumstances will be noted by the person taking the
1286 bug.
1024 </li> 1287 </li>
1288 <li>
1289 WONTFIX - This is usually applied to new ebuilds or feature requests.
1290 Basically the developer does not want to add a certain feature because it
1291 is not needed, a better alternative exists, or it's just plain broken.
1292 Sometimes you may be given a solution to get said issue resolved.
1293 </li>
1294 <li>
1295 UPSTREAM - The bug cannot be fixed by the Gentoo development team, and have
1296 requested you take the problem upstream (the people that actually made the
1297 program) for review. Upstream has a few ways of handling bugs. These
1298 include mailing lists, irc channels, and even bug reporting systems. If
1299 you're not sure how to contact them, ask in the bug and someone will point
1300 you to the right direction.
1301 </li>
1025</ul> 1302</ul>
1026 1303
1304<p>
1305Sometimes, before the bug can be resolved, a developer may request that you
1306test an updated ebulid. In the next chapter we'll take a look at testing
1307ebuilds.
1308</p>
1309
1027</body> 1310</body>
1311</section>
1312</chapter>
1313
1314<chapter>
1315<title>Testing Ebuilds</title>
1028</section> 1316<section>
1317<title>Getting The Files</title>
1318<body>
1029 1319
1320<p>
1321Let's say that you reported a bug for the foobar2 compile fix from earlier. Now
1322developers might find out what the problem is and might need you to test the
1323ebuild for them to be sure it works for you as well:
1324</p>
1325
1326<figure link="/images/docs/bugzie-ebuild-request.png" caption="Ebuild Test Request"/>
1327
1328<p>
1329Some rather confusing vocabulary is used here. First off, let's see what an
1330overlay is. An overlay is a special directory like <path>/usr/portage</path>,
1331the difference being that when you <c>emerge sync</c>, files contained within it
1332will not be deleted. Luckily, a special <path>/usr/local/portage</path>
1333directory is created for that purpose. Let's go ahead and set our portage
1334overlay in<path>/etc/make.conf</path>. Open make.conf up in your favorite editor
1335and add this towards the end.
1336</p>
1337
1338<pre caption="Setting Up PORTDIR_OVERLAY">
1339PORTDIR_OVERLAY="/usr/local/portage"
1340</pre>
1341
1342<p>
1343Now we'll want to create the appropriate directories to put our test ebuild
1344files in. In this case, we're supposed to put them in sys-apps/foobar2. You'll
1345notice that the second comment asks for a files directory for the patch. The
1346files directory holds the digests (md5sums of files for a particular version of
1347a package) and any other required files that aren't included with the standard
1348source archive (patches, init.d scripts, etc). This is a subdir in the package
1349directory called files. Go ahead and create these directories:
1350</p>
1351
1352<pre caption="Setting Up The Category And Package Directories">
1353# <i>mkdir -p /usr/local/portage/sys-apps/foobar2/files</i>
1354</pre>
1355
1356<note>
1357The -p in mkdir creates not only the directory you want but also any missing
1358parent directories as well (sys-apps and foobar2 in this case).
1359</note>
1360
1361<p>
1362Ok now, we can go ahead and download the files. First, download the ebuild
1363into <path>/usr/local/portage/sys-apps/foobar2</path>, and then add the patch
1364to <path>/usr/local/portage/sys-apps/foobar2/files</path>. Now that we have the
1365files, we can begin working on testing the ebuild.
1366</p>
1367
1368</body>
1369</section>
1370<section>
1371<title>Testing The ebuild</title>
1372<body>
1373
1374<p>
1375The process to create an ebuild that can be used by emerge is fairly simple. You
1376must create a Manifest and a digest file for the ebuild. This can be done with
1377the ebuild command. Run it as shown.
1378</p>
1379
1380<pre caption="Creating the Manifest and digest files">
1381# <i>ebuild foobar2-1.0.ebuild digest</i>
1382&gt;&gt;&gt; Generating digest file...
1383&lt;&lt;&lt; foobar2-1.0.tar.bz2
1384&gt;&gt;&gt; Generating manifest file...
1385&lt;&lt;&lt; foobar2-1.0.ebuild
1386&lt;&lt;&lt; files/digest-foobar2-1.0
1387&lt;&lt;&lt; files/foobar2-1.0-Makefile.patch
1388&gt;&gt;&gt; Computed message digests.
1389</pre>
1390
1391<p>
1392Now let's test to see if it works as it should.
1393</p>
1394
1395<pre caption="Testing With emerge -pv">
1396# <i>emerge -pv foobar2</i>
1397
1398These are the packages that I would merge, in order:
1399
1400Calculating dependencies ...done!
1401[ebuild N ] sys-apps/foobar2-1.0 0 kB [1]
1402
1403Total size of downloads: 0 kB
1404Portage overlays:
1405 [1] /usr/local/portage
1406</pre>
1407
1408<p>
1409It does seem to have worked! You'll notice the [1] next to the [ebuild] line.
1410That points to <path>/usr/local/portage</path>, which is the overlay we created
1411earlier. Now we go ahead and emerge the package.
1412</p>
1413
1414<pre caption="Emerge Result">
1415# <i>emerge foobar2</i>
1416 Calculating dependencies ...done!
1417<comment>(compile info snipped)</comment>
1418>>> Unpacking foobar2-1.0.tar.bz2 to /var/tmp/portage/foobar2-1.0/work
1419 * Applying foobar2-1.0-Makefile.patch ... [ ok ]
1420<comment>(compile info snipped)</comment>
1421>>> Merging sys-apps/foobar2-1.0 to /
1422>>> chris +sandbox(preinst)
1423--- /usr/
1424--- /usr/bin/
1425>>> /usr/bin/foobar2
1426</pre>
1427
1428<p>
1429In the first section we see that the emerge started off as it should. The second
1430section shows our patch being applied successfully by the "[ ok ]" status
1431message to the right. The last section tells us the program compiled ok. The
1432patch works! Now we can go and let the developer know that their patch works
1433fine, and that they can commit the fix to portage.
1434</p>
1435
1436</body>
1437</section>
1030<section> 1438<section>
1031<title>Conclusion</title> 1439<title>Conclusion</title>
1032<body> 1440<body>
1033 1441
1034<p> 1442<p>
1035This concludes the howto on working with Bugzilla. I hope you find this useful. 1443This 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 1444If you have any questions, comments, or ideas regarding this document, please
1037send them to me at <mail 1445send 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 1446moreon 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 1447for helping out with bug-wrangling, Griffon26 for his notes on
1041maintainer-needed. 1448maintainer-needed, robbat2 for general suggestions and fox2mike for fixing up
1449the doc and adding stuff as needed.
1042</p> 1450</p>
1043 1451
1044</body> 1452</body>
1045</section> 1453</section>
1046</chapter> 1454</chapter>

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

  ViewVC Help
Powered by ViewVC 1.1.20