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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.18 - (hide annotations) (download) (as text)
Tue Jul 24 12:12:51 2012 UTC (2 years, 4 months ago) by swift
Branch: MAIN
Changes since 1.17: +5 -5 lines
File MIME type: application/xml
Fix bug #427860 - Use /etc/portage for make.conf and make.profile. Old location (/etc) is still supported, this is a heads up (new default)

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

  ViewVC Help
Powered by ViewVC 1.1.20