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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1.3 Revision 1.16
1<?xml version="1.0" encoding="UTF-8"?> 1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> 2<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.3 2005/07/09 22:31:57 fox2mike Exp $ --> 3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.16 2009/03/05 12:13:20 jkt Exp $ -->
4 4
5<guide link="/doc/en/bugzilla-howto.xml"> 5<guide link="/doc/en/bugzilla-howto.xml">
6<title>Gentoo Bug Reporting Guide</title> 6<title>Gentoo Bug Reporting Guide</title>
7 7
8<author title="Author"> 8<author title="Author">
18 18
19<!-- The content of this document is licensed under the CC-BY-SA license --> 19<!-- The content of this document is licensed under the CC-BY-SA license -->
20<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> 20<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
21<license/> 21<license/>
22 22
23<version>1.2</version> 23<version>1.14</version>
24<date>2005-07-10</date> 24<date>2009-03-05</date>
25 25
26<chapter> 26<chapter>
27<title>Introduction</title> 27<title>Introduction</title>
28<section> 28<section>
29<title>Preface</title> 29<title>Preface</title>
84!!! Function src_compile, Line 29, Exitcode 2 84!!! Function src_compile, Line 29, Exitcode 2
85!!! 'emake shared' failed 85!!! 'emake shared' failed
86</pre> 86</pre>
87 87
88<p> 88<p>
89These errors can be quite troublesome. However, once you find them, what do 89These errors can be quite troublesome. However, once you find them, what do you
90you do? The following sections will look at two important tools for handling 90do? The following sections will look at two important tools for handling run
91run time errors. After that, we'll take a look at compile errors, and how to 91time errors. After that, we'll take a look at compile errors, and how to handle
92handle them. Let's start out with the first tool for debugging run time 92them. Let's start out with the first tool for debugging run time errors --
93errors -- <c>gdb</c>. 93<c>gdb</c>.
94</p> 94</p>
95 95
96</body> 96</body>
97</section> 97</section>
98</chapter> 98</chapter>
109normally involve memory corruption. First off, let's take a look at what 109normally involve memory corruption. First off, let's take a look at what
110debugging entails. One of the main things you must do in order to debug a 110debugging entails. One of the main things you must do in order to debug a
111program is to <c>emerge</c> the program with <c>FEATURES="nostrip"</c>. This 111program is to <c>emerge</c> the program with <c>FEATURES="nostrip"</c>. This
112prevents the stripping of debug symbols. Why are programs stripped by default? 112prevents the stripping of debug symbols. Why are programs stripped by default?
113The reason is the same as that for having gzipped man pages -- saving space. 113The reason is the same as that for having gzipped man pages -- saving space.
114Here's how the size of a program varies with and without debug symbol stripping. 114Here's how the size of a program varies with and without debug symbol stripping.
115</p> 115</p>
116 116
117<pre caption="Filesize Comparison"> 117<pre caption="Filesize Comparison">
118<comment>(debug symbols stripped)</comment> 118<comment>(debug symbols stripped)</comment>
119-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code 119-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code
123 123
124<p> 124<p>
125Just for reference, <e>bad_code</e> is the program we'll be debugging with 125Just 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 126<c>gdb</c> later on. As you can see, the program without debugging symbols is
1273140 bytes, while the program with them is 6374 bytes. That's close to double 1273140 bytes, while the program with them is 6374 bytes. That's close to double
128the size! Two more things can be done for debugging. The first is adding ggdb3 128the size! Two more things can be done for debugging. The first is adding
129to your CFLAGS and CXXFLAGS. This flag adds more debugging information than is 129<c>ggdb</c> to your CFLAGS and CXXFLAGS. This flag adds more debugging
130generally included. We'll see what that means later on. This is how 130information than is generally included. We'll see what that means later on. This
131<path>/etc/make.conf</path> <e>might</e> look with the newly added flags. 131is how <path>/etc/make.conf</path> <e>might</e> look with the newly added flags.
132</p> 132</p>
133 133
134<pre caption="make.conf settings"> 134<pre caption="make.conf settings">
135CFLAGS="-O2 -pipe -gddb3" 135CFLAGS="-O1 -pipe -ggdb"
136CXXFLAGS="${CFLAGS}" 136CXXFLAGS="${CFLAGS}"
137</pre> 137</pre>
138 138
139<p> 139<p>
140Lastly, you can also add debug to the package's USE flags. This can be done with the 140Lastly, you can also add debug to the package's USE flags. This can be done
141<path>package.use</path> file. 141with the <path>package.use</path> file.
142</p> 142</p>
143 143
144<pre caption="Using package.use to add debug USE flag"> 144<pre caption="Using package.use to add debug USE flag">
145# <i>echo "category/package debug" >> /etc/portage/package.use</i> 145# <i>echo "category/package debug" >> /etc/portage/package.use</i>
146</pre> 146</pre>
147 147
199This GDB was configured as "i686-pc-linux-gnu"...Using host libthread_db library "/lib/libthread_db.so.1". 199This GDB was configured as "i686-pc-linux-gnu"...Using host libthread_db library "/lib/libthread_db.so.1".
200</pre> 200</pre>
201 201
202<note> 202<note>
203One can also debug with core dumps. These core files contain the same 203One can also debug with core dumps. These core files contain the same
204information that the program would produce when run with gdb. In order to debug 204information that the program would produce when run with gdb. In order to debug
205with a core file with bad_code, you would run <c>gdb ./bad_code core</c> where 205with a core file with bad_code, you would run <c>gdb ./bad_code core</c> where
206core is the name of the core file. 206core is the name of the core file.
207</note> 207</note>
208 208
209<p> 209<p>
279 279
280<p> 280<p>
281This backtrace contains a large number of ?? marks. This is because without 281This backtrace contains a large number of ?? marks. This is because without
282debug symbols, <c>gdb</c> doesn't know how the program was run. Hence, it is 282debug symbols, <c>gdb</c> doesn't know how the program was run. Hence, it is
283crucial that debug symbols are <e>not</e> stripped. Now remember a while ago we 283crucial that debug symbols are <e>not</e> stripped. Now remember a while ago we
284mentioned the -ggdb3 flag. Let's see what the output looks like with the flag 284mentioned the -ggdb flag. Let's see what the output looks like with the flag
285enabled: 285enabled:
286</p> 286</p>
287 287
288<pre caption="Program backtrace with -ggdb3"> 288<pre caption="Program backtrace with -ggdb">
289(gdb) <i>bt</i> 289(gdb) <i>bt</i>
290#0 0xb7e4bdc0 in strcpy () from /lib/libc.so.6 290#0 0xb7e4bdc0 in strcpy () from /lib/libc.so.6
291#1 0x0804838c in run_it (input=0x0) at bad_code.c:7 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 292#2 0x080483ba in main (argc=1, argv=0xbfd3a434) at bad_code.c:12
293</pre> 293</pre>
294 294
295<p> 295<p>
296Here we see that a lot more information is available for developers. Not only is 296Here we see that a lot more information is available for developers. Not only is
297function information displayed, but even the exact line numbers of the source 297function information displayed, but even the exact line numbers of the source
298files. This method is the most preferred if you can spare the extra space. 298files. This method is the most preferred if you can spare the extra space.
299Here's how much the file size varies between debug, strip, and -ggdb3 enabled 299Here's how much the file size varies between debug, strip, and -ggdb enabled
300programs. 300programs.
301</p> 301</p>
302 302
303<pre caption="Filesize differences With -ggdb3 flag"> 303<pre caption="Filesize differences With -ggdb flag">
304<comment>(debug symbols stripped)</comment> 304<comment>(debug symbols stripped)</comment>
305-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code 305-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code
306<comment>(debug symbols enabled)</comment> 306<comment>(debug symbols enabled)</comment>
307-rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code 307-rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code
308<comment>(-ggdb3 flag enabled)</comment> 308<comment>(-ggdb flag enabled)</comment>
309-rwxr-xr-x 1 chris users 19552 6/28 13:11 bad_code 309-rwxr-xr-x 1 chris users 19552 6/28 13:11 bad_code
310</pre> 310</pre>
311 311
312<p> 312<p>
313As you can see, -ggdb3 adds about <e>13178</e> more bytes to the file size over the one 313As you can see, -ggdb adds about <e>13178</e> more bytes to the file size over
314with debugging symbols. However, as shown above, this increase in file size can 314the one with debugging symbols. However, as shown above, this increase in file
315be worth it if presenting debug information to developers. The backtrace, can be 315size can be worth it if presenting debug information to developers. The
316saved to a file by copying and pasting from the terminal (if it's a non-x based 316backtrace can be saved to a file by copying and pasting from the terminal (if
317terminal, you can use gpm. To keep this doc simple, I recommend you read up on 317it's a non-x based terminal, you can use gpm. To keep this doc simple, I
318recommend you read up on the <uri link="/doc/en/gpm.xml#doc_chap4">documentation
318the documentation for gpm to see how to copy and paste with it). Now that we're 319for gpm</uri> to see how to copy and paste with it). Now that we're done with
319done with <c>gdb</c>, we can quit. 320<c>gdb</c>, we can quit.
320</p> 321</p>
321 322
322<pre caption="Quitting GDB"> 323<pre caption="Quitting GDB">
323(gdb) <i>quit</i> 324(gdb) <i>quit</i>
324The program is running. Exit anyway? (y or n) <i>y</i> 325The program is running. Exit anyway? (y or n) <i>y</i>
325$ 326$
326</pre> 327</pre>
327 328
328<p> 329<p>
329This ends the walk-through of <c>gdb</c>. Using <c>gdb</c>, we hope that you will 330This ends the walk-through of <c>gdb</c>. Using <c>gdb</c>, we hope that you
330be able to use it to create better bug reports. However, there are other types 331will be able to use it to create better bug reports. However, there are other
331of errors that can cause a program to fail during run time. One of the other 332types of errors that can cause a program to fail during run time. One of the
332ways is through improper file access. We can find those using a nifty little 333other ways is through improper file access. We can find those using a nifty
333tool called <c>strace</c>. 334little tool called <c>strace</c>.
334</p> 335</p>
335 336
336</body> 337</body>
337</section> 338</section>
338</chapter> 339</chapter>
347Programs often use files to fetch configuration information, access hardware or 348Programs often use files to fetch configuration information, access hardware or
348write logs. Sometimes, a program attempts to reach such files incorrectly. A 349write logs. Sometimes, a program attempts to reach such files incorrectly. A
349tool called <c>strace</c> was created to help deal with this. <c>strace</c> 350tool called <c>strace</c> was created to help deal with this. <c>strace</c>
350traces system calls (hence the name) which include calls that use the memory and 351traces system calls (hence the name) which include calls that use the memory and
351files. For our example, we're going to take a program foobar2. This is an 352files. For our example, we're going to take a program foobar2. This is an
352updated version of foobar. However, during the change over to foobar2, you notice 353updated version of foobar. However, during the change over to foobar2, you
353all your configurations are missing! In foobar version 1, you had it setup to 354notice all your configurations are missing! In foobar version 1, you had it
354say "foo", but now it's using the default "bar". 355setup to say "foo", but now it's using the default "bar".
355</p> 356</p>
356 357
357<pre caption="Foobar2 With an invalid configuration"> 358<pre caption="Foobar2 With an invalid configuration">
358$ <i>./foobar2</i> 359$ <i>./foobar2</i>
359Configuration says: bar 360Configuration says: bar
393Aha! So There's the problem. Someone moved the configuration directory to 394Aha! So There's the problem. Someone moved the configuration directory to
394<path>.foobar2</path> instead of <path>.foobar</path>. We also see the program 395<path>.foobar2</path> instead of <path>.foobar</path>. We also see the program
395reading in "bar" as it should. In this case, we can recommend the ebuild 396reading in "bar" as it should. In this case, we can recommend the ebuild
396maintainer to put a warning about it. For now though, we can copy over the 397maintainer to put a warning about it. For now though, we can copy over the
397config file from <path>.foobar</path> and modify it to produce the correct 398config file from <path>.foobar</path> and modify it to produce the correct
398results. 399results.
399</p> 400</p>
400 401
401</body> 402</body>
402</section> 403</section>
403<section> 404<section>
436 437
437<p> 438<p>
438Let's take a look at this very simple <c>emerge</c> error: 439Let's take a look at this very simple <c>emerge</c> error:
439</p> 440</p>
440 441
441<pre caption="emerge Error"> 442<pre caption="emerge Error (long lines are manually wrapped to fit the window)">
442gcc -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
443gcc -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
444gcc -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
445gcc -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 443gcc -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
445gcc -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
447gcc -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
449gcc -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
446foobar2.c:1:17: ogg.h: No such file or directory 451foobar2.c:1:17: ogg.h: No such file or directory
447make: *** [foobar2.o] Error 1 452make: *** [foobar2.o] Error 1
448 453
449!!! ERROR: sys-apps/foobar2-1.0 failed. 454!!! ERROR: sys-apps/foobar2-1.0 failed.
450!!! Function src_compile, Line 19, Exitcode 2 455!!! Function src_compile, Line 19, Exitcode 2
451!!! Make failed! 456!!! Make failed!
452!!! If you need support, post the topmost build error, NOT this status message 457!!! If you need support, post the topmost build error, NOT this status message
453</pre> 458</pre>
454 459
455<p> 460<p>
456The program is compiling smoothly when it suddenly stops and presents an error message. This 461The program is compiling smoothly when it suddenly stops and presents an error
457particular error can be split into 3 different sections, The compile messages, the build 462message. This particular error can be split into 3 different sections, The
458error, and the emerge error message as shown below. 463compile messages, the build error, and the emerge error message as shown below.
459</p> 464</p>
460 465
461<pre caption="Parts of the error"> 466<pre caption="Parts of the error (long lines are manually wrapped to fit the window)">
462<comment>(Compilation Messages)</comment> 467<comment>(Compilation Messages)</comment>
463gcc -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
464gcc -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
465gcc -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
466gcc -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 468gcc -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
470gcc -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
472gcc -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
474gcc -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
467 476
468<comment>(Build Error)</comment> 477<comment>(Build Error)</comment>
469foobar2.c:1:17: ogg.h: No such file or directory 478foobar2.c:1:17: ogg.h: No such file or directory
470make: *** [foobar2.o] Error 1 479make: *** [foobar2.o] Error 1
471 480
479<p> 488<p>
480The compilation messages are what lead up to the error. Most often, it's good to 489The compilation messages are what lead up to the error. Most often, it's good to
481at least include 10 lines of compile information so that the developer knows 490at least include 10 lines of compile information so that the developer knows
482where the compilation was at when the error occurred. 491where the compilation was at when the error occurred.
483</p> 492</p>
493
494<p>
495Please make sure you always include error messages in English, even when your
496system language is set to something else. You can temporarily switch to English
497locale by prepending <c>LC_ALL=C</c> to the emerge command like this:
498</p>
499
500<pre caption="Temporarily switching locale to English">
501# <i>LC_ALL=C emerge sys-apps/foobar2</i>
502</pre>
503
504<note>
505This is also about the only time you should use the <c>LC_ALL</c> environmental
506variable for specifying locale settings. If you are looking for a way to switch
507your system's language, then please consult our <uri
508link="guide-localization.xml">Localization Guide</uri> instead.
509</note>
484 510
485<p> 511<p>
486Make errors are the actual error and the information the developer needs. When 512Make errors are the actual error and the information the developer needs. When
487you see "make: ***", this is often where the error has occurred. Normally, you 513you see "make: ***", this is often where the error has occurred. Normally, you
488can copy and paste 10 lines above it and the developer will be able to address 514can copy and paste 10 lines above it and the developer will be able to address
508<section> 534<section>
509<title>emerge and PORT_LOGDIR</title> 535<title>emerge and PORT_LOGDIR</title>
510<body> 536<body>
511 537
512<p> 538<p>
513PORT_LOGDIR is a portage variable that sets up a log directory for separate 539PORT_LOGDIR is a portage variable that sets up a log directory for separate
514emerge logs. Let's take a look and see what that entails. First, run your emerge 540emerge logs. Let's take a look and see what that entails. First, run your
515with PORT_LOGDIR set to your favorite log location. Let's say we have a 541emerge with PORT_LOGDIR set to your favorite log location. Let's say we have a
516location <path>/var/log/portage</path>. We'll use that for our log directory: 542location <path>/var/log/portage</path>. We'll use that for our log directory:
517</p> 543</p>
518 544
519<note> 545<note>
520In the default setup, <path>/var/log/portage</path> does not exist, and you will 546In the default setup, <path>/var/log/portage</path> does not exist, and you will
521most likely have to create it. If you do not, portage will fail to write the 547most likely have to create it. If you do not, portage will fail to write the
522logs. 548logs.
523</note> 549</note>
524 550
525<pre caption="emerge-ing With PORT_LOGDIR"> 551<pre caption="emerge-ing With PORT_LOGDIR">
526# <i>PORT_LOGDIR=/var/log/portage emerge foobar2</i> 552# <i>PORT_LOGDIR=/var/log/portage emerge cate-gory/foobar2</i>
527</pre> 553</pre>
528 554
529<p> 555<p>
530Now the emerge fails again. However, this time we have a log we can work with, 556Now the emerge fails again. However, this time we have a log we can work with,
531and attach to the bug later on. Let's take a quick look at our log directory. 557and attach to the bug later on. Let's take a quick look at our log directory.
534<pre caption="PORT_LOGDIR Contents"> 560<pre caption="PORT_LOGDIR Contents">
535# <i>ls -la /var/log/portage</i> 561# <i>ls -la /var/log/portage</i>
536total 16 562total 16
537drwxrws--- 2 root root 4096 Jun 30 10:08 . 563drwxrws--- 2 root root 4096 Jun 30 10:08 .
538drwxr-xr-x 15 root root 4096 Jun 30 10:08 .. 564drwxr-xr-x 15 root root 4096 Jun 30 10:08 ..
539-rw-r--r-- 1 root root 7390 Jun 30 10:09 2115-foobar2-1.0.log 565-rw-r--r-- 1 root root 7390 Jun 30 10:09 cate-gory:foobar2-1.0:20090110-213217.log
540</pre> 566</pre>
541 567
542<p> 568<p>
543The log files have the format [counter]-[package name]-[version].log. Counter 569The log files have the format [category]:[package name]-[version]:[date].log. A
544is a special variable that is meant to state this package as the n-th package
545you've emerged. This prevents duplicate logs from appearing. A quick look at
546the log file will show the entire emerge process. This can be attached later 570quick look at the log file will show the entire emerge process. This can be
547on as we'll see in the bug reporting section. Now that we've safely obtained 571attached later on as we'll see in the bug reporting section. Now that we've
548our information needed to report the bug we can continue to do so. However, 572safely obtained our information needed to report the bug we can continue to do
549before we get started on that, we need to make sure no one else has reported 573so. However, before we get started on that, we need to make sure no one else
550the issue. Let's take a look at searching for bugs. 574has reported the issue. Let's take a look at searching for bugs.
551</p> 575</p>
552 576
553</body> 577</body>
554</section> 578</section>
555</chapter> 579</chapter>
637<figure link="/images/docs/bugzie-adv-search.png" caption="Advanced Search Page"/> 661<figure link="/images/docs/bugzie-adv-search.png" caption="Advanced Search Page"/>
638 662
639<p> 663<p>
640This is how the Advanced Search Page looks like. While it may seem overwhelming 664This is how the Advanced Search Page looks like. While it may seem overwhelming
641at first, we're going to look at a few simple areas to narrow down the rather 665at first, we're going to look at a few simple areas to narrow down the rather
642vague searches bugzilla returns. 666vague searches bugzilla returns.
643</p> 667</p>
644 668
645<figure link="/images/docs/bugzie-content.png" caption="Content"/> 669<figure link="/images/docs/bugzie-content.png" caption="Content"/>
646 670
647<p> 671<p>
655Product, Component, and Version should all be set to the default. This 679Product, Component, and Version should all be set to the default. This
656prevents us from being too specific and missing all the bugs. 680prevents us from being too specific and missing all the bugs.
657</p> 681</p>
658 682
659<p> 683<p>
660Comment is the important part. Use the comment field to list what appears to be a 684Comment is the important part. Use the comment field to list what appears to be
661specific instance of the error. Basically, don't use anything like the 685a specific instance of the error. Basically, don't use anything like the
662beginning of the build error, find a line that's before it stating a true 686beginning of the build error, find a line that's before it stating a true
663error. Also, you'll want to filter out any punctuation to prevent bugzilla 687error. Also, you'll want to filter out any punctuation to prevent bugzilla
664from interpreting the results the comment the wrong way. Example from the xclass 688from interpreting the results the comment the wrong way. Example from the xclass
665emerge error: 689emerge error:
666</p> 690</p>
757simply not how things work. 781simply not how things work.
758</p> 782</p>
759 783
760<p> 784<p>
761Another common misconception occurs with our Documentation bugs. For example, a 785Another common misconception occurs with our Documentation bugs. For example, a
762user finds a bug with the <uri 786user finds a bug with the <uri link="/proj/en/releng/catalyst/">Catalyst
763link="http://www.gentoo.org/proj/en/releng/catalyst/index.xml">Catalyst
764Docs</uri>. The general tendency is to file a bug under Docs-user, which gets 787Docs</uri>. The general tendency is to file a bug under Docs-user, which gets
765assigned to the <uri link="http://gdp.gentoo.org">GDP</uri>, when it should 788assigned to the <uri link="http://gdp.gentoo.org">GDP</uri>, when it should
766actually go to a member of the <uri 789actually go to a member of the <uri link="/proj/en/releng/">Release
767link="http://www.gentoo.org/proj/en/releng/">Release Engineering</uri> team. As 790Engineering</uri> team. As a rule of thumb, only documentation under
768a rule of thumb, only documentation under http://www.gentoo.org/doc/* is under 791<path>http://www.gentoo.org/doc/*</path> is under the GDP. Anything under
769the GDP. Anything under http://www.gentoo.org/proj/* is under the respective 792<path>http://www.gentoo.org/proj/*</path> is under the respective teams.
770teams.
771</p> 793</p>
772 794
773<note> 795<note>
774We would rather see a bug whose product was not supposed to be Gentoo Linux but 796We would rather see a bug whose product was not supposed to be Gentoo Linux but
775has been filed under the same rather than seeing a bug which belongs the Gentoo 797has been filed under the same rather than seeing a bug which belongs the Gentoo
776Linux product and filed elsewhere. While neither is preferred, the former is more 798Linux product and filed elsewhere. While neither is preferred, the former is
777acceptable and understandable (except website bugs.. we might have an issue with 799more acceptable and understandable (except website bugs.. we might have an issue
778that...). 800with that...).
779</note> 801</note>
780 802
781<p> 803<p>
782Our bug goes in Gentoo Linux as it's an ebuild bug. We head over there and are presented 804Our bug goes in Gentoo Linux as it's an ebuild bug. We head over there and are
783with the multi-step bug reporting process. Let us now proceed with Step 1... 805presented with the multi-step bug reporting process. Let us now proceed with
806Step 1...
784</p> 807</p>
785 808
786<figure link="/images/docs/bugzie-guide-step1.png" caption="Guided Format Step 1"/> 809<figure link="/images/docs/bugzie-guide-step1.png" caption="Guided Format Step 1"/>
787 810
788<p> 811<p>
806Let us take a closer look at what's what. 829Let us take a closer look at what's what.
807</p> 830</p>
808 831
809<ul> 832<ul>
810 <li> 833 <li>
811 First, there's the Product. The product will narrow down the bug to a 834 First, there's the Product. The product will narrow down the bug to a
812 specific area of Gentoo like Bugzilla (for bugs relating to bugs.gentoo.org), 835 specific area of Gentoo like Bugzilla (for bugs relating to
813 Docs-user(for User Documentation) or Gentoo Linux (for ebuilds and the like). 836 bugs.gentoo.org), Docs-user(for User Documentation) or Gentoo Linux (for
814 </li> 837 ebuilds and the like).
815 <li> 838 </li>
839 <li>
816 Component is where exactly the problem occurs, more specifically which part 840 Component is where exactly the problem occurs, more specifically which part
817 of selected product the bug comes under. This makes classification easier. 841 of selected product the bug comes under. This makes classification easier.
818 </li>
819 <li> 842 </li>
843 <li>
820 Hardware platform is what architecture you're running. If you were running 844 Hardware platform is what architecture you're running. If you were running
821 SPARC, you would set it to SPARC. 845 SPARC, you would set it to SPARC.
822 </li>
823 <li> 846 </li>
847 <li>
824 Operating System is what Operating System you're using. Because Gentoo is 848 Operating System is what Operating System you're using. Because Gentoo is
825 considered a "Meta-distribution", it can run on other operating systems 849 considered a "Meta-distribution", it can run on other operating systems
826 beside Linux. 850 beside Linux.
827 </li> 851 </li>
828</ul> 852</ul>
829 853
830<p> 854<p>
831So, for our example bug, we have : 855So, for our example bug, we have :
832</p> 856</p>
833 857
834<ul> 858<ul>
835 <li>
836 Product - Gentoo Linux (Since it is an ebuild issue) 859 <li>Product - Gentoo Linux (Since it is an ebuild issue)</li>
837 </li>
838 <li>
839 Component - Application (It is an application at fault, foobar2) 860 <li>Component - Application (It is an application at fault, foobar2)</li>
840 </li>
841 <li>
842 Hardware Platform - All (This error could occur across architectures) 861 <li>Hardware Platform - All (This error could occur across architectures)</li>
843 </li>
844 <li>
845 Operation System - All (It could occur on all types of systems) 862 <li>Operation System - All (It could occur on all types of systems)</li>
846 </li>
847</ul> 863</ul>
848 864
849<figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/> 865<figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/>
850 866
851<ul> 867<ul>
852 <li> 868 <li>
853 Build Identifier is basically the User Agent of the browser that is being used 869 Build Identifier is basically the User Agent of the browser that is being
854 to report the bugs (for logging purposes). You can just leave this as is. 870 used to report the bugs (for logging purposes). You can just leave this as
855 </li> 871 is.
856 <li> 872 </li>
857 URL is optional and is used to point to errors on a site someplace (pastebin,
858 etc.). However, doing it inside the bug allows the developers be able to
859 reference to it at any time and is preferred.
860 </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.
861 <li> 879 </li>
880 <li>
862 In the Summary, you should put the package category, name, and number. 881 In the Summary, you should put the package category, name, and number.
863 </li> 882 </li>
864</ul> 883</ul>
865 884
866<p> 885<p>
867Not including the category in the summary really isn't too bad, but it's 886Not including the category in the summary really isn't too bad, but it's
899</p> 918</p>
900 919
901<figure link="/images/docs/bugzie-results.png" caption="Results"/> 920<figure link="/images/docs/bugzie-results.png" caption="Results"/>
902 921
903<p> 922<p>
904We could then provide additional information. This could be things such as stack traces, 923We could then provide additional information. This could be things such as
905<b>sections</b> (since the whole log is usually big and of not much use) of 924stack traces, <b>sections</b> (since the whole log is usually big and of not
906strace logs, but most importantly, your <c>emerge --info</c> output. Here's an 925much use) of strace logs, but most importantly, your <c>emerge --info</c>
907example. 926output. Here's an example.
908</p> 927</p>
909 928
910<figure link="/images/docs/bugzie-addl-info.png" caption="Additional Information"/> 929<figure link="/images/docs/bugzie-addl-info.png" caption="Additional Information"/>
911 930
912<p> 931<p>
917levels is given below. 936levels is given below.
918</p> 937</p>
919 938
920<ul> 939<ul>
921 <li> 940 <li>
922 Blocker - The program just plain doesn't want to emerge or is a major 941 Blocker - The program just plain doesn't want to emerge or is a major
923 hinderance to the system. For example a <c>baselayout</c> issue which prevents 942 hinderance to the system. For example a <c>baselayout</c> issue which
924 a system from booting up would be a sure candidate to be labelled blocker. 943 prevents a system from booting up would be a sure candidate to be labelled
925 </li> 944 blocker.
926 <li> 945 </li>
946 <li>
927 Critical - The program has loss of data or severe memory leaks during 947 Critical - The program has loss of data or severe memory leaks during
928 runtime. Again, an important program like say <c>net-tools</c> failing to 948 runtime. Again, an important program like say <c>net-tools</c> failing to
929 compile could be labelled critical. It won't prevent the system from starting 949 compile could be labelled critical. It won't prevent the system from
930 up, but is quite essential for day to day stuff. 950 starting up, but is quite essential for day to day stuff.
931 </li>
932 <li> 951 </li>
952 <li>
933 Major - The program crashes, but nothing that causes your system severe 953 Major - The program crashes, but nothing that causes your system severe
934 damage or information loss. 954 damage or information loss.
935 </li>
936 <li> 955 </li>
956 <li>
937 Minor - Your program crashes here and there with apparent workarounds. 957 Minor - Your program crashes here and there with apparent workarounds.
938 </li>
939 <li> 958 </li>
959 <li>
940 Normal - The default. If you're not sure leave it here unless it's a new 960 Normal - The default. If you're not sure leave it here unless it's a new
941 build or cosmetic change, then read below for more information. 961 build or cosmetic change, then read below for more information.
942 </li>
943 <li> 962 </li>
944 Trivial - Things such as a mispelled word or whitespace clean up. 963 <li>Trivial - Things such as a mispelled word or whitespace clean up. </li>
945 </li> 964 <li>
946 <li>
947 Enhancement - A request to enable a new feature in a program, or more 965 Enhancement - A request to enable a new feature in a program, or more
948 specifically <e>new ebuilds</e>. 966 specifically <e>new ebuilds</e>.
949 </li> 967 </li>
950</ul> 968</ul>
951 969
952<figure link="/images/docs/bugzie-sev.png" caption="Severity"/> 970<figure link="/images/docs/bugzie-sev.png" caption="Severity"/>
953 971
959Now we can submit the bug report by clicking on the Submit Bug Report box. You 977Now we can submit the bug report by clicking on the Submit Bug Report box. You
960will now see your new bug come up. See <uri 978will now see your new bug come up. See <uri
961link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what 979link="https://bugs.gentoo.org/show_bug.cgi?id=97265">Bug 97561</uri> for what
962the result looks like. We've reported our bug! Now let's see how it's dealt 980the result looks like. We've reported our bug! Now let's see how it's dealt
963with. 981with.
982</p>
983
984</body>
985</section>
986<section>
987<title>Zero-day bump requests</title>
988<body>
989
990<p>
991So far, we've shown what to do when filing a bug. Now let's take a look at what
992<e>not</e> to do.
993</p>
994
995<p>
996Suppose that you've eagerly been following an upstream project's schedule, and
997when you check their homepage, guess what? They just released a new version a
998few minutes ago! Most users would immediately rush over to Gentoo's bugzilla to
999report the new version is available; please bump the existing version and add
1000it to Portage, etc. However, this is exactly what you should <b>not</b> do.
1001These kinds of requests are called zero-day (or 0-day) bump requests, as they're
1002made the same day that a new version is released.
1003</p>
1004
1005<impo>
1006<b>Please wait <e>at least</e> 48 hours before reporting a new release on our
1007bugzilla.</b> Also, you <e>must</e> check bugzilla before posting your request
1008to make sure that someone else hasn't already reported it, or that the Gentoo
1009maintainers haven't already dealt with the new version.
1010</impo>
1011
1012<p>
1013Why should you wait? First, it's quite rude to demand that Gentoo developers
1014drop everything they're doing just to add a new release that came out 15 minutes
1015ago. Your zero-day bump request could be marked as INVALID or LATER, as
1016developers have plenty of pressing issues to keep them busy. Second, developers
1017are usually aware of pending new releases well in advance of users, as they must
1018follow upstream quite closely. They already know a new version is on its way.
1019In many cases, they will have already opened a bug, or might even already added
1020it in Portage as a masked package.
1021</p>
1022
1023<p>
1024Be smart when testing and requesting new versions of packages. Search bugzilla
1025before posting your bump request -- is there already a bug open? Have you synced
1026lately; is it already in Portage? Has it actually been released by upstream?
1027Basic common sense will go a long way, and will endear you to developers that
1028already have a lot to do. If it's been several days since release and you're
1029sure that there are no open requests for it (and that it's not in Portage), then
1030you can open up a new bug. Be sure to mention that it compiles and runs well on
1031your arch. Any other helpful information you provide is most welcome.
1032</p>
1033
1034<p>
1035Want to see the newest version of your favorite package in Portage? File smart
1036bugs.
964</p> 1037</p>
965 1038
966</body> 1039</body>
967</section> 1040</section>
968</chapter> 1041</chapter>
1044Now we have to attach the log. Let's go throught it step wise. 1117Now we have to attach the log. Let's go throught it step wise.
1045</p> 1118</p>
1046 1119
1047<ul> 1120<ul>
1048 <li> 1121 <li>
1049 File - This is the location of the file in your machine. In this example, the 1122 File - This is the location of the file in your machine. In this example,
1050 location of <path>strace.log</path>. You can use the "Browse..." button to 1123 the location of <path>strace.log</path>. You can use the "Browse..." button
1051 select the file, or enter the path directly in the text field. 1124 to select the file, or enter the path directly in the text field.
1052 </li>
1053 <li> 1125 </li>
1126 <li>
1054 Description - A short one liner, or a few wors describing the attachment. 1127 Description - A short one liner, or a few wors describing the attachment.
1055 We'll just enter strace.log here, since that's quite self-explanatory. 1128 We'll just enter strace.log here, since that's quite self-explanatory.
1056 </li>
1057 <li> 1129 </li>
1130 <li>
1058 Content Type - This is the type of the file we're attaching to the bug. 1131 Content Type - This is the type of the file we're attaching to the bug.
1059 </li>
1060 <li> 1132 </li>
1133 <li>
1061 Obsoletes - If there were attachements submitted to the bug before the current 1134 Obsoletes - If there were attachements submitted to the bug before the
1062 one, you have an option of declaring them obsoleted by yours. Since we have no 1135 current one, you have an option of declaring them obsoleted by yours. Since
1063 prior attachments to this bug, we need not bother. 1136 we have no prior attachments to this bug, we need not bother.
1064 </li>
1065 <li> 1137 </li>
1138 <li>
1066 Comment - Enter comments that will be visible along with the attachments. You 1139 Comment - Enter comments that will be visible along with the attachments.
1067 could elaborate on the attachment here, if needed. 1140 You could elaborate on the attachment here, if needed.
1068 </li> 1141 </li>
1069</ul> 1142</ul>
1070 1143
1071<p> 1144<p>
1072With respect to Content Type, here are a few more details. You can check the 1145With respect to Content Type, here are a few more details. You can check the
1073"patch" checkbox if you're submitting a patch. Otherwise, you could ask Bugzilla 1146"patch" checkbox if you're submitting a patch. Otherwise, you could ask
1074to "auto-detect" the file type (not advisable). The other options are "select 1147Bugzilla to "auto-detect" the file type (not advisable). The other options are
1075from list", which is most frequently used. Use plain text (text/plain) for <e>most</e> 1148"select from list", which is most frequently used. Use plain text (text/plain)
1076attachments except binary files like images (which can use image/gif, 1149for <e>most</e> attachments except binary files like images (which can use
1077image/jpeg or image/png depending on type) or compressed files like .tar.bz2 1150image/gif, image/jpeg or image/png depending on type) or compressed files like
1078which would use application/octet-stream as content type. 1151.tar.bz2 which would use application/octet-stream as content type.
1079</p> 1152</p>
1080 1153
1081 1154
1082<figure link="/images/docs/bugzie-new-attach-comp.png" caption="New Attachment Completed"/> 1155<figure link="/images/docs/bugzie-new-attach-comp.png" caption="New Attachment Completed"/>
1083 1156
1107<p> 1180<p>
1108Please attach any file mentioned like this to your bug report. 1181Please attach any file mentioned like this to your bug report.
1109</p> 1182</p>
1110 1183
1111<p> 1184<p>
1112While we're doing all this, suppose another person finds your bug by searching 1185Sometimes a developer might ask you to attach a diff or patch for a file.
1113through bugzilla and is curious to keep track of the bug, they may do so by 1186Standard diff files can be obtained through:
1114putting their email in the Add CC field of the bug as shown below. You could 1187</p>
1188
1189<pre caption="Standard Diff Creation">
1190$ <i>cp file file.old</i>
1191$ <i>nano file</i>
1192$ <i>diff -u file.old file</i>
1193</pre>
1194
1195<p>
1196For C/C++ source files, the <b>-p</b> flag is added to show what function calls
1197the diff applies to:
1198</p>
1199
1200<pre caption="Diff-ing C/C++ source">
1201$ <i>cp file.c file.c.old</i>
1202$ <i>nano file.c</i>
1203$ <i>diff -up file.c.old file.c</i>
1204</pre>
1205
1206<p>
1207The 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
1209with:
1210</p>
1211
1212<pre caption="Documentation diffs">
1213$<i> cp file.xml file.xml.old</i>
1214$<i> nano file.xml</i>
1215$<i> diff -Nut file.xml.old file.xml</i>
1216</pre>
1217
1218<p>
1219And your diff is created. While we're doing all this, suppose another person
1220finds your bug by searching through bugzilla and is curious to keep track of
1221the bug, they may do so by putting their email in the Add CC field of the bug
1115also keep track of other bugs by following the same method. 1222as shown below. You could also keep track of other bugs by following the same
1223method.
1116</p> 1224</p>
1117 1225
1118<figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/> 1226<figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/>
1119 1227
1120<note> 1228<note>
1129lifetime. 1237lifetime.
1130</p> 1238</p>
1131 1239
1132<ul> 1240<ul>
1133 <li> 1241 <li>
1134 UNCONFIRMED - You're generally not going to see this too often. This 1242 UNCONFIRMED - You're generally not going to see this too often. This means
1135 means that a bug reporter has opened a bug using the advanced method and is 1243 that a bug reporter has opened a bug using the advanced method and is
1136 uncertain his or her bug is an actual bug. 1244 uncertain his or her bug is an actual bug.
1137 </li>
1138 <li> 1245 </li>
1139 NEW - Bugs that are first opened are considered new. 1246 <li>NEW - Bugs that are first opened are considered new.</li>
1140 </li> 1247 <li>
1141 <li>
1142 ASSIGNED - When the person you've assigned the bug too validates your 1248 ASSIGNED - When the person you've assigned the bug too validates your bug,
1143 bug, it will often receive ASSIGNED status while they figure out the issue. 1249 it will often receive ASSIGNED status while they figure out the issue.
1144 This lets you know that they've accepted your bug as a real bug. 1250 This lets you know that they've accepted your bug as a real bug.
1145 </li>
1146 <li> 1251 </li>
1252 <li>
1147 REOPENED - Someone has resolved a bug and you think the solution is not 1253 REOPENED - Someone has resolved a bug and you think the solution is not
1148 feasible or the problem still persists. At this point, you may re-open the 1254 feasible or the problem still persists. At this point, you may re-open the
1149 bug. Please <b>do not abuse this</b>. If a developer closes the bug a 1255 bug. Please <b>do not abuse this</b>. If a developer closes the bug a
1150 second or third time, chances are that your bug is closed. 1256 second or third time, chances are that your bug is closed.
1151 </li>
1152 <li> 1257 </li>
1258 <li>
1153 RESOLVED - A firm decision has been taken on the bug. Usually goes onto FIXED 1259 RESOLVED - A firm decision has been taken on the bug. Usually goes onto
1154 to indicate the bug is solved and the matter closed although various other 1260 FIXED to indicate the bug is solved and the matter closed although various
1155 resolutions are possible. We'll look into those a little later. 1261 other resolutions are possible. We'll look into those a little later.
1156 </li>
1157 <li> 1262 </li>
1263 <li>
1158 VERIFIED - The steps take to work the bug are correct. This is usually a QA 1264 VERIFIED - The steps take to work the bug are correct. This is usually a QA
1159 thing. 1265 thing.
1160 </li>
1161 <li> 1266 </li>
1267 <li>
1162 CLOSED - Basically means RIP for the bug and it's buried under the never ending 1268 CLOSED - Basically means RIP for the bug and it's buried under the never
1163 flow of new bugs. 1269 ending flow of new bugs.
1164 </li> 1270 </li>
1165</ul> 1271</ul>
1166 1272
1167<p> 1273<p>
1168Now shortly afterward, we find the error in the strace log and fix the bug and 1274Now shortly afterward, we find the error in the strace log and fix the bug and
1169mark it as RESOLVED FIXED and mention that there was a change in the location of 1275mark it as RESOLVED FIXED and mention that there was a change in the location
1170configuration files, and that I will update the ebuild with a warning about it. 1276of configuration files, and that I will update the ebuild with a warning about
1171The bug now becomes resolved, and you are shown the following. 1277it. The bug now becomes resolved, and you are shown the following.
1172</p> 1278</p>
1173 1279
1174<figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/> 1280<figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/>
1175 1281
1176<p> 1282<p>
1178</p> 1284</p>
1179 1285
1180<figure link="/images/docs/bugzie-options.png" caption="Bug Options"/> 1286<figure link="/images/docs/bugzie-options.png" caption="Bug Options"/>
1181 1287
1182<p> 1288<p>
1183This gives you the option of Reopening the bug if you wish to (i.e. the developer 1289This gives you the option of Reopening the bug if you wish to (i.e. the
1184thinks it's resolved but it's really not to your standards). Now our bug is 1290developer thinks it's resolved but it's really not to your standards). Now our
1185fixed! However, different resolutions can occur. Here's a small list: 1291bug is fixed! However, different resolutions can occur. Here's a small list:
1186</p> 1292</p>
1187 1293
1188<ul> 1294<ul>
1189 <li> 1295 <li>
1190 FIXED - The bug is fixed, follow the instructions to resolve your 1296 FIXED - The bug is fixed, follow the instructions to resolve your issue.
1191 issue.
1192 </li>
1193 <li> 1297 </li>
1298 <li>
1194 INVALID - You did not do something specifically documented, causing the 1299 INVALID - You did not do something specifically documented, causing the
1195 bug. 1300 bug.
1196 </li>
1197 <li> 1301 </li>
1198 DUPLICATE - You didn't use this guide and reported a duplicate bug 1302 <li>DUPLICATE - You didn't use this guide and reported a duplicate bug.</li>
1199 :)
1200 </li> 1303 <li>
1201 <li>
1202 WORKSFORME - Developer/person assigned the bug cannot reproduce your 1304 WORKSFORME - Developer/person assigned the bug cannot reproduce your error.
1203 error.
1204 </li>
1205 <li> 1305 </li>
1206 CANTFIX - Somehow the bug cannot be solved because of certain circumstances.
1207 These circumstances will be noted by the person taking the bug.
1208 </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.
1209 <li> 1310 </li>
1311 <li>
1210 WONTFIX - This is usually applied to new ebuilds or feature requests. 1312 WONTFIX - This is usually applied to new ebuilds or feature requests.
1211 Basically the developer does not want to add a certain feature because it is 1313 Basically the developer does not want to add a certain feature because it
1212 not needed, a better alternative exists, or it's just plain broken. Sometimes 1314 is not needed, a better alternative exists, or it's just plain broken.
1213 you may be given a solution to get said issue resolved. 1315 Sometimes you may be given a solution to get said issue resolved.
1214 </li>
1215 <li> 1316 </li>
1317 <li>
1216 UPSTREAM - The bug cannot be fixed by the Gentoo development team, and 1318 UPSTREAM - The bug cannot be fixed by the Gentoo development team, and have
1217 have requested you take the problem upstream (the people that actually made 1319 requested you take the problem upstream (the people that actually made the
1218 the program) for review. Upstream has a few ways of handling bugs. These 1320 program) for review. Upstream has a few ways of handling bugs. These
1219 include mailing lists, irc channels, and even bug reporting systems. If 1321 include mailing lists, irc channels, and even bug reporting systems. If
1220 you're not sure how to contact them, ask in the bug and someone will point 1322 you're not sure how to contact them, ask in the bug and someone will point
1221 you to the right direction. 1323 you to the right direction.
1222 </li> 1324 </li>
1223</ul> 1325</ul>
1224 1326
1225<p> 1327<p>
1226Sometimes, before the bug can be resolved, a developer may request that you 1328Sometimes, before the bug can be resolved, a developer may request that you
1227test an updated ebulid. In the next chapter we'll take a look at testing 1329test an updated ebulid. In the next chapter we'll take a look at testing
1228ebuilds. 1330ebuilds.
1229</p> 1331</p>
1230 1332
1231</body> 1333</body>
1232</section> 1334</section>
1261</pre> 1363</pre>
1262 1364
1263<p> 1365<p>
1264Now we'll want to create the appropriate directories to put our test ebuild 1366Now we'll want to create the appropriate directories to put our test ebuild
1265files in. In this case, we're supposed to put them in sys-apps/foobar2. You'll 1367files in. In this case, we're supposed to put them in sys-apps/foobar2. You'll
1266notice that the second comment asks for a files directory for the patch. The 1368notice that the second comment asks for a <path>files</path> directory for the
1267files directory holds the digests (md5sums of files for a particular version of 1369patch. This directory holds other required files that aren't included with
1268a package) and any other required files that aren't included with the standard
1269source archive (patches, init.d scripts, etc). This is a subdir in the package 1370the standard source archive (patches, init.d scripts, etc). This is a subdir in
1270directory called files. Go ahead and create these directories: 1371the package directory called <path>files</path>. Go ahead and create these
1372directories:
1271</p> 1373</p>
1272 1374
1273<pre caption="Setting Up The Category And Package Directories"> 1375<pre caption="Setting Up The Category And Package Directories">
1274# <i>mkdir -p /usr/local/portage/sys-apps/foobar2/files</i> 1376# <i>mkdir -p /usr/local/portage/sys-apps/foobar2/files</i>
1275</pre> 1377</pre>
1292<title>Testing The ebuild</title> 1394<title>Testing The ebuild</title>
1293<body> 1395<body>
1294 1396
1295<p> 1397<p>
1296The process to create an ebuild that can be used by emerge is fairly simple. You 1398The process to create an ebuild that can be used by emerge is fairly simple. You
1297must create a Manifest and a digest file for the ebuild. This can be done with 1399must create a Manifest file for the ebuild. This can be done with
1298the ebuild command. Run it as shown. 1400the ebuild command. Run it as shown.
1299</p> 1401</p>
1300 1402
1301<pre caption="Creating the Manifest and digest files"> 1403<pre caption="Creating the Manifest file">
1302# <i>ebuild foobar2-1.0.ebuild digest</i> 1404# <i>ebuild foobar2-1.0.ebuild manifest</i>
1303&gt;&gt;&gt; Generating digest file... 1405&gt;&gt;&gt; Creating Manifest for /usr/local/portage/sys-apps/foobar2
1304&lt;&lt;&lt; foobar2-1.0.tar.bz2
1305&gt;&gt;&gt; Generating manifest file...
1306&lt;&lt;&lt; foobar2-1.0.ebuild
1307&lt;&lt;&lt; files/digest-foobar2-1.0
1308&lt;&lt;&lt; files/foobar2-1.0-Makefile.patch
1309&gt;&gt;&gt; Computed message digests.
1310</pre> 1406</pre>
1311 1407
1312<p> 1408<p>
1313Now let's test to see if it works as it should. 1409Now let's test to see if it works as it should.
1314</p> 1410</p>
1331That points to <path>/usr/local/portage</path>, which is the overlay we created 1427That points to <path>/usr/local/portage</path>, which is the overlay we created
1332earlier. Now we go ahead and emerge the package. 1428earlier. Now we go ahead and emerge the package.
1333</p> 1429</p>
1334 1430
1335<pre caption="Emerge Result"> 1431<pre caption="Emerge Result">
1336# emerge foobar2 1432# <i>emerge foobar2</i>
1337 Calculating dependencies ...done! 1433 Calculating dependencies ...done!
1338<comment>(compile info snipped)</comment> 1434<comment>(compile info snipped)</comment>
1339>>> Unpacking foobar2-1.0.tar.bz2 to /var/tmp/portage/foobar2-1.0/work 1435>>> Unpacking foobar2-1.0.tar.bz2 to /var/tmp/portage/foobar2-1.0/work
1340 * Applying foobar2-1.0-Makefile.patch ... [ ok ] 1436 * Applying foobar2-1.0-Makefile.patch ... [ ok ]
1341<comment>(compile info snipped)</comment> 1437<comment>(compile info snipped)</comment>
1347</pre> 1443</pre>
1348 1444
1349<p> 1445<p>
1350In the first section we see that the emerge started off as it should. The second 1446In the first section we see that the emerge started off as it should. The second
1351section shows our patch being applied successfully by the "[ ok ]" status 1447section shows our patch being applied successfully by the "[ ok ]" status
1352message to the right. The last section tells us the program compiled ok. The 1448message to the right. The last section tells us the program compiled ok. The
1353patch works! Now we can go and let the developer know that their patch works 1449patch works! Now we can go and let the developer know that their patch works
1354fine, and that they can commit the fix to portage. 1450fine, and that they can commit the fix to portage.
1355</p> 1451</p>
1356 1452
1357</body> 1453</body>
1361<body> 1457<body>
1362 1458
1363<p> 1459<p>
1364This concludes the howto on working with Bugzilla. I hope you find this useful. 1460This concludes the howto on working with Bugzilla. I hope you find this useful.
1365If you have any questions, comments, or ideas regarding this document, please 1461If you have any questions, comments, or ideas regarding this document, please
1366send them to me at <mail 1462send them to me at <mail>chriswhite@gentoo.org</mail>. Special thanks go to
1367link="chriswhite@gentoo.org">chriswhite@gentoo.org</mail>. Special
1368thanks go to moreon for his notes on -g flags and compile errors, the people at 1463moreon for his notes on -g flags and compile errors, the people at #gentoo-bugs
1369#gentoo-bugs for helping out with bug-wrangling, Griffon26 for his notes on 1464for helping out with bug-wrangling, Griffon26 for his notes on
1370maintainer-needed, robbat2 for general suggestions and fox2mike for fixing up 1465maintainer-needed, robbat2 for general suggestions and fox2mike for fixing up
1371the doc and adding stuff as needed. 1466the doc and adding stuff as needed.
1372</p> 1467</p>
1373 1468
1374</body> 1469</body>

Legend:
Removed from v.1.3  
changed lines
  Added in v.1.16

  ViewVC Help
Powered by ViewVC 1.1.20