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