Get Gentoo!
gentoo.org sites
gentoo.org Wiki Bugs Forums Packages
Planet Archives Sources
Infra Status

Gentoo Archives: gentoo-doc-cvs

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