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

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.17 - (show annotations) (download) (as text)
Sun Feb 28 06:14:00 2010 UTC (9 years ago) by nightmorph
Branch: MAIN
Changes since 1.16: +7 -7 lines
File MIME type: application/xml
update with new perl commands, bug 307147

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

  ViewVC Help
Powered by ViewVC 1.1.20