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

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

  ViewVC Help
Powered by ViewVC 1.1.20