/[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.15
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.15 2009/03/05 12:02:04 jkt 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.13</version>
24<date>2005-07-07</date> 24<date>2009-03-05</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
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/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 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 -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> 495Make 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 496you see "make: ***", this is often where the error has occurred. Normally, you
497can copy and paste 10 lines above it and the developer will be able to address
498the issue. However, this may not always work and we'll take a look at an
499alternative shortly.
500</p>
501
502<p>
503The emerge error is what <c>emerge</c> throws out as an error. Sometimes, this
504might 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 505posting 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 506make 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 507what 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: ***" 508the 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. 509"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 510emerge 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. 511let'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. 512everything. That's where PORT_LOGDIR comes into play.
479</p> 513</p>
480 514
481</body> 515</body>
482</section> 516</section>
483<section> 517<section>
484<title>emerge and PORT_LOGDIR</title> 518<title>emerge and PORT_LOGDIR</title>
485<body> 519<body>
486 520
487<p> 521<p>
488PORT_LOGDIR is a portage variable that sets up a log directory for separate 522PORT_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 523emerge 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 524emerge 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: 525location <path>/var/log/portage</path>. We'll use that for our log directory:
492</p> 526</p>
493 527
494<note> 528<note>
495In the default setup, /var/log/portage does not exist, and you will most likely 529In 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. 530most likely have to create it. If you do not, portage will fail to write the
531logs.
497</note> 532</note>
498 533
499<pre caption="emerge-ing With PORT_LOGDIR"> 534<pre caption="emerge-ing With PORT_LOGDIR">
500# <i>PORT_LOGDIR=/var/log/portage emerge foobar2</i> 535# <i>PORT_LOGDIR=/var/log/portage emerge cate-gory/foobar2</i>
501</pre> 536</pre>
502 537
503<p> 538<p>
504Now the emerge fails again. However, this time we have a log we can work with, 539Now 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. 540and attach to the bug later on. Let's take a quick look at our log directory.
508<pre caption="PORT_LOGDIR Contents"> 543<pre caption="PORT_LOGDIR Contents">
509# <i>ls -la /var/log/portage</i> 544# <i>ls -la /var/log/portage</i>
510total 16 545total 16
511drwxrws--- 2 root root 4096 Jun 30 10:08 . 546drwxrws--- 2 root root 4096 Jun 30 10:08 .
512drwxr-xr-x 15 root root 4096 Jun 30 10:08 .. 547drwxr-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 548-rw-r--r-- 1 root root 7390 Jun 30 10:09 cate-gory:foobar2-1.0:20090110-213217.log
514</pre> 549</pre>
515 550
516<p> 551<p>
517The log files have the format [counter]-[package name]-[version].log. Counter 552The 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 553quick 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 554attached 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, 555safely 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 556so. 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. 557has reported the issue. Let's take a look at searching for bugs.
525</p> 558</p>
526 559
527</body> 560</body>
528</section> 561</section>
529</chapter> 562</chapter>
536 569
537<p> 570<p>
538<uri link="http://www.bugzilla.org">Bugzilla</uri> is what we at Gentoo use to 571<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 572handle 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 573available 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 574consistency, 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 575over to <uri link="https://bugs.gentoo.org">Gentoo Bugs</uri> to see how it
543looks. 576looks.
544</p> 577</p>
545 578
546<p> 579<p>
547One of the most frustrating thing for developers and bug-wranglers is finding 580One 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 581duplicate 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 582use 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 583search 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 584you have one that's similar. For this example, we're going to use the xclass
552emerge error that was used earlier: 585emerge error that was used earlier.
553</p> 586</p>
554 587
555<pre caption="xclass emerge error"> 588<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: 589/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 590warning: #warning This file includes at least one deprecated or antiquated
582!!! 'emake shared' failed 615!!! 'emake shared' failed
583</pre> 616</pre>
584 617
585<p> 618<p>
586So to begin searching, we head over to the <uri 619So to begin searching, we head over to the <uri
587link="http://bugs.gentoo.org/">Bugzilla Homepage</uri>. 620link="https://bugs.gentoo.org/">Bugzilla Homepage</uri>.
588</p> 621</p>
589 622
590<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/> 623<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>
591 624
592<p> 625<p>
593In order to begin our search, we'll click on "Query Existing bug reports". The 626We'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 627over 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 628results 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 629duplicate bug. Once we click on the query screen, we reach the next page:
597screen, we reach the next page:
598</p> 630</p>
599 631
600<figure link="/images/docs/bugzie-search.png" caption="Bugzilla Search Page"/> 632<figure link="/images/docs/bugzie-search.png" caption="Bugzilla Search Page"/>
601 633
602<note> 634<note>
603If you've used the Advanced Search before, you'll most likely see that screen 635If you've used the Advanced Search before, you'll most likely see that screen
604instead. 636instead.
605</note> 637</note>
606 638
607<p> 639<p>
608Proceed on clicking the "Advanced Search" link to bring up the Advanced 640Proceed by clicking on the "Advanced Search" link to bring up the Advanced
609Search page: 641Search page.
610</p> 642</p>
611 643
612<figure link="/images/docs/bugzie-adv-search.png" caption="Advanced Search Page"/> 644<figure link="/images/docs/bugzie-adv-search.png" caption="Advanced Search Page"/>
613 645
614<p> 646<p>
615This is how the Advanced Search Page looks like. While it may seem overwhelming 647This 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 648at first, we're going to look at a few simple areas to narrow down the rather
617vague searches bugzilla returns. 649vague searches bugzilla returns.
618</p> 650</p>
619 651
620<figure link="/images/docs/bugzie-content.png" caption="Content"/> 652<figure link="/images/docs/bugzie-content.png" caption="Content"/>
621 653
622<p> 654<p>
623The first field is the summary of the bug. Here we're simply going to put the 655The 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 656name 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 657removing 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). 658(highly unlikely, but we've seen a fair share of strange bug reports).
627</p> 659</p>
628 660
629<p> 661<p>
630Product, Component, and Version should all be set to the default. This 662Product, Component, and Version should all be set to the default. This
631prevents us from being too specific and missing all the bugs. 663prevents us from being too specific and missing all the bugs.
632</p> 664</p>
633 665
634<p> 666<p>
635Comment is the important part. Use comment to list what appears to be a 667Comment 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 668a 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 669beginning 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 670error. 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 671from interpreting the results the comment the wrong way. Example from the xclass
640emerge error: 672emerge error:
641</p> 673</p>
651other xclass compile failure candidates. 683other xclass compile failure candidates.
652</p> 684</p>
653 685
654<p> 686<p>
655URI, Whiteboard, and Keywords can all be left alone. What we've entered so far 687URI, 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: 688should be enough to find our bug. Let's take a look at what we have filled out.
657</p> 689</p>
658 690
659<figure link="/images/docs/bugzie-comp-search.png" caption="Completed Search Form"/> 691<figure link="/images/docs/bugzie-comp-search.png" caption="Completed Search Form"/>
660 692
661<p> 693<p>
662Now we click on the Search button and here come the results: 694Now we click on the Search button and here come the results...
663</p> 695</p>
664 696
665<figure link="/images/docs/bugzie-search-result.png" caption="Search Results"/> 697<figure link="/images/docs/bugzie-search-result.png" caption="Search Results"/>
666 698
667<p> 699<p>
668Only 2 bugs! That's a lot easier to deal with. We click on the first one to 700Only 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: 701check, and sure enough it's the one we're looking for.
670</p> 702</p>
671 703
672<figure link="/images/docs/bugzie-located.png" caption="Bug Located"/> 704<figure link="/images/docs/bugzie-located.png" caption="Bug Located"/>
673 705
674<p> 706<p>
675Not only is it the one we want, but it has also been resolved. By checking the 707Not 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. 708last 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: 709Now, let's see what would have happened if we had not used the advanced search.
678</p> 710</p>
679 711
680<figure link="/images/docs/bugzie-basic-search-result.png" caption="Basic Search Results"/> 712<figure link="/images/docs/bugzie-basic-search-result.png" caption="Basic Search Results"/>
681 713
682<p> 714<p>
713</p> 745</p>
714 746
715<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/> 747<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/>
716 748
717<p> 749<p>
718Go ahead and click on "Report a Bug - Using the Guided format". 750Click on "Report a Bug - Using the guided format".
719</p> 751</p>
720 752
721<figure link="/images/docs/bugzie-prod-select.png" caption="Product Selection"/> 753<figure link="/images/docs/bugzie-prod-select.png" caption="Product Selection"/>
722 754
723<p> 755<p>
724As you can see, <b>major</b> emphasis has been placed on putting your bug in the 756As 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, 757right place. Gentoo Linux is where a large majority of bugs go.
758</p>
759
760<p>
726some people will file ebuild bugs in portage development (assumption that 761Despite this, some people will file ebuild bugs in portage development
727portage team handles the portage tree) or infra (assumption that infra has 762(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 763that 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 764simply not how things work.
730there and are presented with the multi-step bug reporting process. 765</p>
766
767<p>
768Another common misconception occurs with our Documentation bugs. For example, a
769user finds a bug with the <uri link="/proj/en/releng/catalyst/">Catalyst
770Docs</uri>. The general tendency is to file a bug under Docs-user, which gets
771assigned to the <uri link="http://gdp.gentoo.org">GDP</uri>, when it should
772actually go to a member of the <uri link="/proj/en/releng/">Release
773Engineering</uri> team. As a rule of thumb, only documentation under
774<path>http://www.gentoo.org/doc/*</path> is under the GDP. Anything under
775<path>http://www.gentoo.org/proj/*</path> is under the respective teams.
731</p> 776</p>
732 777
733<note> 778<note>
734We would rather see a non-Gentoo Linux bug filed in Gentoo Linux than a Gentoo 779We 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 780has been filed under the same rather than seeing a bug which belongs the Gentoo
781Linux product and filed elsewhere. While neither is preferred, the former is
736former is more acceptable and understandable (except website bugs.. we might 782more acceptable and understandable (except website bugs.. we might have an issue
737have an issue with that...) 783with that...).
738</note> 784</note>
739 785
740<p> 786<p>
741Let us now proceed with Step 1... 787Our bug goes in Gentoo Linux as it's an ebuild bug. We head over there and are
788presented with the multi-step bug reporting process. Let us now proceed with
789Step 1...
742</p> 790</p>
743 791
744<figure link="/images/docs/bugzie-guide-step1.png" caption="Guided Format Step 1"/> 792<figure link="/images/docs/bugzie-guide-step1.png" caption="Guided Format Step 1"/>
745 793
746<p> 794<p>
747The first step here is really important (as the red text tells you). This is 795The 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. 796where 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 797If 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, 798as 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, 799the bug numbers that are struck out above are duplicate bugs. Now comes step 2,
752where we give the information. 800where we give the information.
753</p> 801</p>
754 802
755</body> 803</body>
756</section> 804</section>
757<section> 805<section>
758<title>Required Information</title> 806<title>Required Information</title>
759<body> 807<body>
760 808
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"/> 809<figure link="/images/docs/bugzie-basic.png" caption="Basic Information"/>
766 810
767<p> 811<p>
768First, there's the product. This is Gentoo Linux, which we selected earlier. 812Let us take a closer look at what's what.
769Component is where the problem occurs. We use this to help us sort out the 813</p>
770severity of the issue (i.e. baselayout and core systems will be more important 814
771than new ebuilds or application bugs). Here we select Application, as it is an 815<ul>
772application at fault. Hardware platform is what architecture you're running. 816 <li>
773If you were running SPARC, you would set it to SPARC. For this example, we know 817 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 818 specific area of Gentoo like Bugzilla (for bugs relating to
775System is what Operating System you're using. Because Gentoo is considered a 819 bugs.gentoo.org), Docs-user(for User Documentation) or Gentoo Linux (for
820 ebuilds and the like).
821 </li>
822 <li>
823 Component is where exactly the problem occurs, more specifically which part
824 of selected product the bug comes under. This makes classification easier.
825 </li>
826 <li>
827 Hardware platform is what architecture you're running. If you were running
828 SPARC, you would set it to SPARC.
829 </li>
830 <li>
831 Operating System is what Operating System you're using. Because Gentoo is
776"Meta-distribution", it can run on other operating systems beside Linux. 832 considered a "Meta-distribution", it can run on other operating systems
777Examples are Gentoo on MacOS, Gentoo on FreeBSD, etc. For this example, 833 beside Linux.
778we'll select All, as this can occur on all types of systems. Build Identifier 834 </li>
779is what is being used to report the bugs (for logging purposes). You can just 835</ul>
780leave this as is. Let's see what we have so far: 836
781</p> 837<p>
838So, for our example bug, we have :
839</p>
840
841<ul>
842 <li>Product - Gentoo Linux (Since it is an ebuild issue)</li>
843 <li>Component - Application (It is an application at fault, foobar2)</li>
844 <li>Hardware Platform - All (This error could occur across architectures)</li>
845 <li>Operation System - All (It could occur on all types of systems)</li>
846</ul>
782 847
783<figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/> 848<figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/>
784 849
785<p> 850<ul>
786That does look good, so we'll begin with the actual report. In this instance, 851 <li>
787we'll use the foobar2 bug as our example. URL is used to point to errors on a 852 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 853 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 854 is.
855 </li>
856 <li>
857 URL is optional and is used to point to relevant information on another site
858 (upstream bugzilla, release notes on package homepage etc.). You should
859 never use URL to point to pastebins for error messages, logs, <c>emerge
860 --info</c> output, screenshots or similar information. Instead, these should
861 always be attached to the bug.
862 </li>
863 <li>
790the summary. In the summary, you should put the package category, name, and 864 In the Summary, you should put the package category, name, and number.
865 </li>
866</ul>
867
868<p>
791number. Not including the category really isn't too bad, but it's recommended. 869Not 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 870recommended. 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 871you'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 872number 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 873not 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 874to 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 875isn'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. 876the package information, you'll want to include a small description of the
799Here's an example: 877incident. Here's an example:
800</p> 878</p>
801 879
802<figure link="/images/docs/bugzie-summary.png" caption="Summary"/> 880<figure link="/images/docs/bugzie-summary.png" caption="Summary"/>
803 881
804<p> 882<p>
805Just these simple rules can make handling bugs a lot easier. Next are the 883These 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 884Here we put in the information about the bug. We'll demonstrate with an example:
807example:
808</p> 885</p>
809 886
810<figure link="/images/docs/bugzie-details.png" caption="Details"/> 887<figure link="/images/docs/bugzie-details.png" caption="Details"/>
811 888
812<p> 889<p>
813So now the developer knows why we're filing the bug. They can then try to 890Now 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 891reproduce 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 892problem recur. In this example, we can reproduce it any time simply by running
816foobar2. Let's put that information in: 893foobar2. Let's put that information in.
817</p> 894</p>
818 895
819<figure link="/images/docs/bugzie-reprod.png" caption="Reproduction"/> 896<figure link="/images/docs/bugzie-reprod.png" caption="Reproduction"/>
820 897
821<p> 898<p>
822So now we have explained how we found the bug. Next we want to explain what 899We 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: 900the results we got and what we think they should actually be.
824</p> 901</p>
825 902
826<figure link="/images/docs/bugzie-results.png" caption="Results"/> 903<figure link="/images/docs/bugzie-results.png" caption="Results"/>
827 904
828<p> 905<p>
829Next we put additional information. This can be things such as stack traces, 906We could then provide additional information. This could be things such as
907stack 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. 908much use) of strace logs, but most importantly, your <c>emerge --info</c>
831Here's an example: 909output. Here's an example.
832</p> 910</p>
833 911
834<figure link="/images/docs/bugzie-addl-info.png" caption="Additional Information"/> 912<figure link="/images/docs/bugzie-addl-info.png" caption="Additional Information"/>
835 913
836<p> 914<p>
837Lastly we select the severity of the bug. Please look this over carefully. In 915Lastly 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. 916most 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 917However, 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 918carefully and make sure you're not making a mistake. A run down of the various
841default of normal: 919levels is given below.
842</p> 920</p>
921
922<ul>
923 <li>
924 Blocker - The program just plain doesn't want to emerge or is a major
925 hinderance to the system. For example a <c>baselayout</c> issue which
926 prevents a system from booting up would be a sure candidate to be labelled
927 blocker.
928 </li>
929 <li>
930 Critical - The program has loss of data or severe memory leaks during
931 runtime. Again, an important program like say <c>net-tools</c> failing to
932 compile could be labelled critical. It won't prevent the system from
933 starting up, but is quite essential for day to day stuff.
934 </li>
935 <li>
936 Major - The program crashes, but nothing that causes your system severe
937 damage or information loss.
938 </li>
939 <li>
940 Minor - Your program crashes here and there with apparent workarounds.
941 </li>
942 <li>
943 Normal - The default. If you're not sure leave it here unless it's a new
944 build or cosmetic change, then read below for more information.
945 </li>
946 <li>Trivial - Things such as a mispelled word or whitespace clean up. </li>
947 <li>
948 Enhancement - A request to enable a new feature in a program, or more
949 specifically <e>new ebuilds</e>.
950 </li>
951</ul>
843 952
844<figure link="/images/docs/bugzie-sev.png" caption="Severity"/> 953<figure link="/images/docs/bugzie-sev.png" caption="Severity"/>
954
955<p>
956Here, we'll set it to Normal.
957</p>
845 958
846<p> 959<p>
847Now we can submit the bug report by clicking on the Submit Bug Report box. You 960Now 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 961will now see your new bug come up. See <uri
849link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what 962link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what
851with. 964with.
852</p> 965</p>
853 966
854</body> 967</body>
855</section> 968</section>
969<section>
970<title>Zero-day bump requests</title>
971<body>
972
973<p>
974So far, we've shown what to do when filing a bug. Now let's take a look at what
975<e>not</e> to do.
976</p>
977
978<p>
979Suppose that you've eagerly been following an upstream project's schedule, and
980when you check their homepage, guess what? They just released a new version a
981few minutes ago! Most users would immediately rush over to Gentoo's bugzilla to
982report the new version is available; please bump the existing version and add
983it to Portage, etc. However, this is exactly what you should <b>not</b> do.
984These kinds of requests are called zero-day (or 0-day) bump requests, as they're
985made the same day that a new version is released.
986</p>
987
988<impo>
989<b>Please wait <e>at least</e> 48 hours before reporting a new release on our
990bugzilla.</b> Also, you <e>must</e> check bugzilla before posting your request
991to make sure that someone else hasn't already reported it, or that the Gentoo
992maintainers haven't already dealt with the new version.
993</impo>
994
995<p>
996Why should you wait? First, it's quite rude to demand that Gentoo developers
997drop everything they're doing just to add a new release that came out 15 minutes
998ago. Your zero-day bump request could be marked as INVALID or LATER, as
999developers have plenty of pressing issues to keep them busy. Second, developers
1000are usually aware of pending new releases well in advance of users, as they must
1001follow upstream quite closely. They already know a new version is on its way.
1002In many cases, they will have already opened a bug, or might even already added
1003it in Portage as a masked package.
1004</p>
1005
1006<p>
1007Be smart when testing and requesting new versions of packages. Search bugzilla
1008before posting your bump request -- is there already a bug open? Have you synced
1009lately; is it already in Portage? Has it actually been released by upstream?
1010Basic common sense will go a long way, and will endear you to developers that
1011already have a lot to do. If it's been several days since release and you're
1012sure that there are no open requests for it (and that it's not in Portage), then
1013you can open up a new bug. Be sure to mention that it compiles and runs well on
1014your arch. Any other helpful information you provide is most welcome.
1015</p>
1016
1017<p>
1018Want to see the newest version of your favorite package in Portage? File smart
1019bugs.
1020</p>
1021
1022</body>
1023</section>
856</chapter> 1024</chapter>
857 1025
858<chapter> 1026<chapter>
859<title>Working With Your Bug</title> 1027<title>Working With Your Bug</title>
860<section> 1028<section>
861<body> 1029<body>
862 1030
863<p> 1031<p>
864looking at the bug, we see the information we provided earlier: 1032Looking at the bug, we see the information we provided earlier. You will notice
1033that the bug has been assigned to bug-wranglers@gentoo.org. This is the default
1034location for Application component bugs.
865</p> 1035</p>
866 1036
867<figure link="/images/docs/bugzie-new-basic.png" caption="New Bug Basic Information"/> 1037<figure link="/images/docs/bugzie-new-basic.png" caption="New Bug Basic Information"/>
868 1038
869<p> 1039<p>
870And our details are there too: 1040The details we entered about the bug are available as well.
871</p> 1041</p>
872 1042
873<figure link="/images/docs/bugzie-new-details.png" caption="New Bug Details"/> 1043<figure link="/images/docs/bugzie-new-details.png" caption="New Bug Details"/>
874 1044
875<p> 1045<p>
876Now as you can see, the bug has been assigned to bug-wranglers@gentoo.org. This 1046However, 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 1047someone 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 1048this 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: 1049<path>/usr/portage/category/package/metadata.xml</path>. Here's one I've made up
1050for foobar2.
882</p> 1051</p>
1052
1053<note>
1054You have to be the reporter of the bug or a member of certain Gentoo Bugzilla
1055groups (like Gentoo Developers) to be able to reassign bugs.
1056</note>
883 1057
884<pre caption="metadata.xml"> 1058<pre caption="metadata.xml">
885&lt;?xml version="1.0" encoding="UTF-8"?&gt; 1059&lt;?xml version="1.0" encoding="UTF-8"?&gt;
886&lt;!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"&gt; 1060&lt;!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"&gt;
887&lt;pkgmetadata&gt; 1061&lt;pkgmetadata&gt;
895&lt;/longdescription&gt; 1069&lt;/longdescription&gt;
896&lt;/pkgmetadata&gt; 1070&lt;/pkgmetadata&gt;
897</pre> 1071</pre>
898 1072
899<p> 1073<p>
900Notice the maintainer section.T his lists the maintainer of the package, which 1074Notice 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. 1075in 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 1076We 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: 1077the bubble next to Reassign bug to, then fill in the email.
904</p> 1078</p>
905 1079
906<note> 1080<note>
907A package without a metadata.xml file should be re-assigned to 1081A bug for a package without a metadata.xml file should be re-assigned to
908maintainer-needed@gentoo.org. 1082maintainer-needed@gentoo.org and a package that needs a Gentoo Developer to
1083maintain should be assigned to maintainer-wanted@gentoo.org.
909</note> 1084</note>
910 1085
911<figure link="/images/docs/bugzie-reassign.png" caption="Bug Reassignment"/> 1086<figure link="/images/docs/bugzie-reassign.png" caption="Bug Reassignment"/>
912 1087
913<p> 1088<p>
920</p> 1095</p>
921 1096
922<figure link="/images/docs/bugzie-new-attach.png" caption="New Attachment"/> 1097<figure link="/images/docs/bugzie-new-attach.png" caption="New Attachment"/>
923 1098
924<p> 1099<p>
925Now we have to attach the log. We click on the "Browse..." button under "File" 1100Now 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 1101</p>
927is what kind of file we're attaching. A common mistake is to set it to 1102
928auto. In most cases it's best to manually set it. Our log file is a 1103<ul>
929plain text file, so we select "plain text (text/plain)". Obsoletes are for when 1104 <li>
930you are attaching a revision to a previously attached file. You can simply click 1105 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, 1106 the location of <path>strace.log</path>. You can use the "Browse..." button
932indicating that the attachment has been obsoleted. Reassignment means you want 1107 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 1108 </li>
934need to at some point (unless you create great patches and we don't care about 1109 <li>
935you taking our bugs ;). Comments are for leaving comments about the file you're 1110 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 1111 We'll just enter strace.log here, since that's quite self-explanatory.
937something like this: 1112 </li>
1113 <li>
1114 Content Type - This is the type of the file we're attaching to the bug.
1115 </li>
1116 <li>
1117 Obsoletes - If there were attachements submitted to the bug before the
1118 current one, you have an option of declaring them obsoleted by yours. Since
1119 we have no prior attachments to this bug, we need not bother.
1120 </li>
1121 <li>
1122 Comment - Enter comments that will be visible along with the attachments.
1123 You could elaborate on the attachment here, if needed.
1124 </li>
1125</ul>
1126
938</p> 1127<p>
1128With respect to Content Type, here are a few more details. You can check the
1129"patch" checkbox if you're submitting a patch. Otherwise, you could ask
1130Bugzilla to "auto-detect" the file type (not advisable). The other options are
1131"select from list", which is most frequently used. Use plain text (text/plain)
1132for <e>most</e> attachments except binary files like images (which can use
1133image/gif, image/jpeg or image/png depending on type) or compressed files like
1134.tar.bz2 which would use application/octet-stream as content type.
1135</p>
1136
939 1137
940<figure link="/images/docs/bugzie-new-attach-comp.png" caption="New Attachment Completed"/> 1138<figure link="/images/docs/bugzie-new-attach-comp.png" caption="New Attachment Completed"/>
941 1139
942<p> 1140<p>
943We Submit the patch and it is now reflected on the bug report. 1141We submit <path>strace.log</path> and it is reflected on the bug report.
944</p> 1142</p>
945 1143
946<figure link="/images/docs/bugzie-strace.png" caption="Attached strace log"/> 1144<figure link="/images/docs/bugzie-strace.png" caption="Attached strace log"/>
947 1145
948<p> 1146<p>
949Now, while we're waiting another person notices your bug during step 1 of the 1147We'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 1148the emerge error. An example can be seen below.
1149</p>
1150
1151<pre caption="Example File Attachment Request">
1152configure: error: PNG support requires ZLIB. Use --with-zlib-dir=&lt;DIR&gt;
1153
1154!!! Please attach the config.log to your bug report:
1155!!! /var/tmp/portage/php-5.0.3-r1/work/php-5.0.3/config.log
1156
1157!!! ERROR: dev-php/php-5.0.3-r1 failed.
1158!!! Function econf, Line 485, Exitcode 0
1159!!! econf failed
1160!!! If you need support, post the topmost build error, NOT this status message.
1161</pre>
1162
1163<p>
1164Please attach any file mentioned like this to your bug report.
1165</p>
1166
1167<p>
1168Sometimes a developer might ask you to attach a diff or patch for a file.
1169Standard diff files can be obtained through:
1170</p>
1171
1172<pre caption="Standard Diff Creation">
1173$ <i>cp file file.old</i>
1174$ <i>nano file</i>
1175$ <i>diff -u file.old file</i>
1176</pre>
1177
1178<p>
1179For C/C++ source files, the <b>-p</b> flag is added to show what function calls
1180the diff applies to:
1181</p>
1182
1183<pre caption="Diff-ing C/C++ source">
1184$ <i>cp file.c file.c.old</i>
1185$ <i>nano file.c</i>
1186$ <i>diff -up file.c.old file.c</i>
1187</pre>
1188
1189<p>
1190The documentation team will require the flag combination <b>-Nt</b> as well as
1191<b>-u</b>. This mainly has to do with tab expansion. You can create such a diff
1192with:
1193</p>
1194
1195<pre caption="Documentation diffs">
1196$<i> cp file.xml file.xml.old</i>
1197$<i> nano file.xml</i>
1198$<i> diff -Nut file.xml.old file.xml</i>
1199</pre>
1200
1201<p>
1202And your diff is created. While we're doing all this, suppose another person
1203finds 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: 1204the bug, they may do so by putting their email in the Add CC field of the bug
1205as shown below. You could also keep track of other bugs by following the same
1206method.
952</p> 1207</p>
953 1208
954<figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/> 1209<figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/>
955 1210
956<note> 1211<note>
957Email addresses must be registered with bugzilla. In order to CC multiple 1212Email addresses must be registered with Gentoo Bugzilla. In order to CC multiple
958addresses, simply separate them with commas or spaces. 1213addresses, simply separate them with commas or spaces.
959</note> 1214</note>
960 1215
961<p> 1216<p>
962After all this work, the bug can undergo various status markings. Here's a few: 1217After all this work, the bug can undergo various status markings. This is
1218usually done by the Gentoo Developers and sometimes by the reporter. The
1219following are the various possible states a bug may go through during its
1220lifetime.
963</p> 1221</p>
964 1222
965<ul> 1223<ul>
966 <li> 1224 <li>
967 UNCONFIRMED - You're generally not going to see this too often. This 1225 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 1226 that a bug reporter has opened a bug using the advanced method and is
969 uncertain his or her bug is an actual bug. 1227 uncertain his or her bug is an actual bug.
970 </li>
971 <li> 1228 </li>
972 NEW - Bugs that are first opened are considered new. 1229 <li>NEW - Bugs that are first opened are considered new.</li>
973 </li>
974 <li> 1230 <li>
975 ASSIGNED - When the person you've assigned the bug too validates your 1231 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. 1232 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. 1233 This lets you know that they've accepted your bug as a real bug.
978 </li>
979 <li> 1234 </li>
1235 <li>
980 REOPENED - Someone has resolved a bug and you think the solution is not 1236 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 1237 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 1238 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. 1239 second or third time, chances are that your bug is closed.
984 </li> 1240 </li>
1241 <li>
1242 RESOLVED - A firm decision has been taken on the bug. Usually goes onto
1243 FIXED to indicate the bug is solved and the matter closed although various
1244 other resolutions are possible. We'll look into those a little later.
1245 </li>
1246 <li>
1247 VERIFIED - The steps take to work the bug are correct. This is usually a QA
1248 thing.
1249 </li>
1250 <li>
1251 CLOSED - Basically means RIP for the bug and it's buried under the never
1252 ending flow of new bugs.
1253 </li>
985</ul> 1254</ul>
986 1255
987<p> 1256<p>
988Now shortly afterward, I find the error in the strace log. I resolve the bug 1257Now 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 1258mark 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. 1259of configuration files, and that I will update the ebuild with a warning about
991The bug now becomes resolved, and you are displayed with this: 1260it. The bug now becomes resolved, and you are shown the following.
992</p> 1261</p>
993 1262
994<figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/> 1263<figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/>
995 1264
996<p> 1265<p>
997Also note the section here: 1266A little below, you'll see the following:
998</p> 1267</p>
999 1268
1000<figure link="/images/docs/bugzie-options.png" caption="Bug Options"/> 1269<figure link="/images/docs/bugzie-options.png" caption="Bug Options"/>
1001 1270
1002<p> 1271<p>
1003This gives you the option of Reopening the bug if you wish to (i.e. the developer 1272This 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 1273developer 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: 1274bug is fixed! However, different resolutions can occur. Here's a small list:
1006</p> 1275</p>
1007 1276
1008<ul> 1277<ul>
1009 <li> 1278 <li>
1010 FIXED - The bug is fixed, follow the instructions to resolve your 1279 FIXED - The bug is fixed, follow the instructions to resolve your issue.
1011 issue.
1012 </li>
1013 <li> 1280 </li>
1281 <li>
1014 INVALID - You did not do something specifically documented, causing the 1282 INVALID - You did not do something specifically documented, causing the
1015 bug 1283 bug.
1016 </li>
1017 <li> 1284 </li>
1018 DUPLICATE - You didn't use this guide and reported a duplicate bug 1285 <li>DUPLICATE - You didn't use this guide and reported a duplicate bug.</li>
1019 :) 1286 <li>
1020 </li> 1287 WORKSFORME - Developer/person assigned the bug cannot reproduce your error.
1021 <li> 1288 </li>
1022 WORKSFORME - Developer/person assigned the bug cannot reproduce your 1289 <li>
1023 error 1290 CANTFIX - Somehow the bug cannot be solved because of certain
1291 circumstances. These circumstances will be noted by the person taking the
1292 bug.
1024 </li> 1293 </li>
1294 <li>
1295 WONTFIX - This is usually applied to new ebuilds or feature requests.
1296 Basically the developer does not want to add a certain feature because it
1297 is not needed, a better alternative exists, or it's just plain broken.
1298 Sometimes you may be given a solution to get said issue resolved.
1299 </li>
1300 <li>
1301 UPSTREAM - The bug cannot be fixed by the Gentoo development team, and have
1302 requested you take the problem upstream (the people that actually made the
1303 program) for review. Upstream has a few ways of handling bugs. These
1304 include mailing lists, irc channels, and even bug reporting systems. If
1305 you're not sure how to contact them, ask in the bug and someone will point
1306 you to the right direction.
1307 </li>
1025</ul> 1308</ul>
1026 1309
1310<p>
1311Sometimes, before the bug can be resolved, a developer may request that you
1312test an updated ebulid. In the next chapter we'll take a look at testing
1313ebuilds.
1314</p>
1315
1027</body> 1316</body>
1317</section>
1318</chapter>
1319
1320<chapter>
1321<title>Testing Ebuilds</title>
1028</section> 1322<section>
1323<title>Getting The Files</title>
1324<body>
1029 1325
1326<p>
1327Let's say that you reported a bug for the foobar2 compile fix from earlier. Now
1328developers might find out what the problem is and might need you to test the
1329ebuild for them to be sure it works for you as well:
1330</p>
1331
1332<figure link="/images/docs/bugzie-ebuild-request.png" caption="Ebuild Test Request"/>
1333
1334<p>
1335Some rather confusing vocabulary is used here. First off, let's see what an
1336overlay is. An overlay is a special directory like <path>/usr/portage</path>,
1337the difference being that when you <c>emerge sync</c>, files contained within it
1338will not be deleted. Luckily, a special <path>/usr/local/portage</path>
1339directory is created for that purpose. Let's go ahead and set our portage
1340overlay in<path>/etc/make.conf</path>. Open make.conf up in your favorite editor
1341and add this towards the end.
1342</p>
1343
1344<pre caption="Setting Up PORTDIR_OVERLAY">
1345PORTDIR_OVERLAY="/usr/local/portage"
1346</pre>
1347
1348<p>
1349Now we'll want to create the appropriate directories to put our test ebuild
1350files in. In this case, we're supposed to put them in sys-apps/foobar2. You'll
1351notice that the second comment asks for a <path>files</path> directory for the
1352patch. This directory holds other required files that aren't included with
1353the standard source archive (patches, init.d scripts, etc). This is a subdir in
1354the package directory called <path>files</path>. Go ahead and create these
1355directories:
1356</p>
1357
1358<pre caption="Setting Up The Category And Package Directories">
1359# <i>mkdir -p /usr/local/portage/sys-apps/foobar2/files</i>
1360</pre>
1361
1362<note>
1363The -p in mkdir creates not only the directory you want but also any missing
1364parent directories as well (sys-apps and foobar2 in this case).
1365</note>
1366
1367<p>
1368Ok now, we can go ahead and download the files. First, download the ebuild
1369into <path>/usr/local/portage/sys-apps/foobar2</path>, and then add the patch
1370to <path>/usr/local/portage/sys-apps/foobar2/files</path>. Now that we have the
1371files, we can begin working on testing the ebuild.
1372</p>
1373
1374</body>
1375</section>
1376<section>
1377<title>Testing The ebuild</title>
1378<body>
1379
1380<p>
1381The process to create an ebuild that can be used by emerge is fairly simple. You
1382must create a Manifest file for the ebuild. This can be done with
1383the ebuild command. Run it as shown.
1384</p>
1385
1386<pre caption="Creating the Manifest file">
1387# <i>ebuild foobar2-1.0.ebuild manifest</i>
1388&gt;&gt;&gt; Creating Manifest for /usr/local/portage/sys-apps/foobar2
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.15

  ViewVC Help
Powered by ViewVC 1.1.20