/[gentoo]/xml/htdocs/doc/en/test.xml
Gentoo

Contents of /xml/htdocs/doc/en/test.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.40 - (hide annotations) (download) (as text)
Sat Nov 12 17:07:53 2005 UTC (8 years, 8 months ago) by pylon
Branch: MAIN
Changes since 1.39: +1340 -1 lines
File MIME type: application/xml
Testing if diffs > 200 lines will still be truncated

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

  ViewVC Help
Powered by ViewVC 1.1.20