pylon 05/11/12 17:10:06 Modified: xml/htdocs/doc/en test.xml Log: works; removing stuff
Revision Changes Path 1.41 +1 -1338 /var/cvsroot/gentoo/xml/htdocs/doc/en/test.xml file : http://www.gentoo.org/cgi-bin/viewcvs.cgi//var/cvsroot/gentoo/xml/htdocs/doc/en/test.xml?rev=1.41&content-type=text/x-cvsweb-markup&cvsroot=gentoo plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi//var/cvsroot/gentoo/xml/htdocs/doc/en/test.xml?rev=1.41&content-type=text/plain&cvsroot=gentoo diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi//var/cvsroot/gentoo/xml/htdocs/doc/en/test.xml.diff?r1=1.40&r2=1.41&cvsroot=gentoo Index: test.xml =================================================================== RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/test.xml,v retrieving revision 1.40 retrieving revision 1.41 diff -u -r1.40 -r1.41 --- test.xml 12 Nov 2005 17:07:53 -0000 1.40 +++ test.xml 12 Nov 2005 17:10:06 -0000 1.41 @@ -1,5 +1,5 @@ <?xml version='1.0' encoding="UTF-8"?> -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/test.xml,v 1.40 2005/11/12 17:07:53 pylon Exp $ --> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/test.xml,v 1.41 2005/11/12 17:10:06 pylon Exp $ --> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <guide link="/doc/en/test.xml"> @@ -45,1341 +45,4 @@ </chapter> -<chapter> -<title>Introduction</title> -<section> -<title>Preface</title> -<body> - -<p> -One of the factors that delay a bug being fixed is the way it is reported. By -creating this guide, we hope to help improve the communication between -developers and users in bug resolution. Getting bugs fixed is an important, if -not crucial part of the quality assurance for any project and hopefully this -guide will help make that a success. -</p> - -</body> -</section> -<section> -<title>Bugs!!!!</title> -<body> - -<p> -You're emerge-ing a package or working with a program and suddenly the worst -happens -- you find a bug. Bugs come in many forms like emerge failures or -segmentation faults. Whatever the cause, the fact still remains that such a bug -must be fixed. Here is a few examples of such bugs. -</p> - -<pre caption="A run time error"> -$ <i>./bad_code `perl -e 'print Ax100'`</i> -Segmentation fault -</pre> - -<pre caption="An emerge failure"> -/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.2/include/g++-v3/backward/backward_warning.h:32:2: -warning: #warning This file includes at least one deprecated or antiquated -header. Please consider using one of the 32 headers found in section 17.4.1.2 of -the C++ standard. Examples include substituting the <X> header for the <X.h> -header for C++ includes, or <sstream> instead of the deprecated header -<strstream.h>. To disable this warning use -Wno-deprecated. -In file included from main.cc:40: -menudef.h:55: error: brace-enclosed initializer used to initialize ` -OXPopupMenu*' -menudef.h:62: error: brace-enclosed initializer used to initialize ` -OXPopupMenu*' -menudef.h:70: error: brace-enclosed initializer used to initialize ` -OXPopupMenu*' -menudef.h:78: error: brace-enclosed initializer used to initialize ` -OXPopupMenu*' -main.cc: In member function `void OXMain::DoOpen()': -main.cc:323: warning: unused variable `FILE*fp' -main.cc: In member function `void OXMain::DoSave(char*)': -main.cc:337: warning: unused variable `FILE*fp' -make[1]: *** [main.o] Error 1 -make[1]: Leaving directory -`/var/tmp/portage/xclass-0.7.4/work/xclass-0.7.4/example-app' -make: *** [shared] Error 2 - -!!! ERROR: x11-libs/xclass-0.7.4 failed. -!!! Function src_compile, Line 29, Exitcode 2 -!!! 'emake shared' failed -</pre> - -<p> -These errors can be quite troublesome. However, once you find them, what do you -do? The following sections will look at two important tools for handling run -time errors. After that, we'll take a look at compile errors, and how to handle -them. Let's start out with the first tool for debugging run time errors -- -<c>gdb</c>. -</p> - -</body> -</section> -</chapter> - - -<chapter> -<title>Debugging using GDB</title> -<section> -<title>Introduction</title> -<body> - -<p> -GDB, or the (G)NU (D)e(B)ugger, is a program used to find run time errors that -normally involve memory corruption. First off, let's take a look at what -debugging entails. One of the main things you must do in order to debug a -program is to <c>emerge</c> the program with <c>FEATURES="nostrip"</c>. This -prevents the stripping of debug symbols. Why are programs stripped by default? -The reason is the same as that for having gzipped man pages -- saving space. -Here's how the size of a program varies with and without debug symbol stripping. -</p> - -<pre caption="Filesize Comparison"> -<comment>(debug symbols stripped)</comment> --rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code -<comment>(debug symbols intact)</comment> --rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code -</pre> - -<p> -Just for reference, <e>bad_code</e> is the program we'll be debugging with -<c>gdb</c> later on. As you can see, the program without debugging symbols is -3140 bytes, while the program with them is 6374 bytes. That's close to double -the size! Two more things can be done for debugging. The first is adding ggdb3 -to your CFLAGS and CXXFLAGS. This flag adds more debugging information than is -generally included. We'll see what that means later on. This is how -<path>/etc/make.conf</path> <e>might</e> look with the newly added flags. -</p> - -<pre caption="make.conf settings"> -CFLAGS="-O1 -pipe -g -ggdb" -CXXFLAGS="${CFLAGS}" -</pre> - -<p> -Lastly, you can also add debug to the package's USE flags. This can be done -with the <path>package.use</path> file. -</p> - -<pre caption="Using package.use to add debug USE flag"> -# <i>echo "category/package debug" >> /etc/portage/package.use</i> -</pre> - -<note> -The directory <path>/etc/portage</path> does not exist by default and you may -have to create it, if you have not already done so. If the package already has -USE flags set in <path>package.use</path>, you will need to manually modify them -in your favorite editor. -</note> - -<p> -Then we re-emerge the package with the modifications we've done so far as shown -below. -</p> - -<pre caption="Re-emergeing a package with debugging"> -# <i>FEATURES="nostrip" emerge package</i> -</pre> - -<p> -Now that debug symbols are setup, we can continue with debugging the program. -</p> - -</body> -</section> -<section> -<title>Running the program with GDB</title> -<body> - -<p> -Let's say we have a program here called "bad_code". Some person claims that the -program crashes and provides an example. You go ahead and test it out: -</p> - -<pre caption="Breaking The Program"> -$ <i>./bad_code `perl -e 'print Ax100'`</i> -Segmentation fault -</pre> - -<p> -It seems this person was right. Since the program is obviously broken, we have -a bug at hand. Now, it's time to use <c>gdb</c> to help solve this matter. First -we run <c>gdb</c> with <c>--args</c>, then give it the full program with -arguments like shown: -</p> - -<pre caption="Running Our Program Through GDB"> -$ <i>gdb --args ./bad_code `perl -e 'print Ax100'`</i> -GNU gdb 6.3 -Copyright 2004 Free Software Foundation, Inc. -GDB is free software, covered by the GNU General Public License, and you are -welcome to change it and/or distribute copies of it under certain conditions. -Type "show copying" to see the conditions. -There is absolutely no warranty for GDB. Type "show warranty" for details. -This GDB was configured as "i686-pc-linux-gnu"...Using host libthread_db library "/lib/libthread_db.so.1". -</pre> - -<note> -One can also debug with core dumps. These core files contain the same -information that the program would produce when run with gdb. In order to debug -with a core file with bad_code, you would run <c>gdb ./bad_code core</c> where -core is the name of the core file. -</note> - -<p> -You should see a prompt that says "(gdb)" and waits for input. First, we have to -run the program. We type in <c>run</c> at the command and receive a notice like: -</p> - -<pre caption="Running the program in GDB"> -(gdb) <i>run</i> -Starting program: /home/chris/bad_code - -Program received signal SIGSEGV, Segmentation fault. -0xb7ec6dc0 in strcpy () from /lib/libc.so.6 -</pre> - -<p> -Here we see the program starting, as well as a notification of SIGSEGV, or -Segmentation Fault. This is GDB telling us that our program has crashed. It -also gives the last run function it could trace when the program crashes. -However, this isn't too useful, as there could be multiple strcpy's in the -program, making it hard for developers to find which one is causing the issue. -In order to help them out, we do what's called a backtrace. A backtrace runs -backwards through all the functions that occurred upon program execution, to the -function at fault. Functions that return (without causing a crash) will not show -up on the backtrace. To get a backtrace, at the (gdb) prompt, type in <c>bt</c>. -You will get something like this: -</p> - -<pre caption="Program backtrace"> -(gdb) <i>bt</i> -#0 0xb7ec6dc0 in strcpy () from /lib/libc.so.6 -#1 0x0804838c in run_it () -#2 0x080483ba in main () -</pre> - -<p> -You can notice the trace pattern clearly. main() is called first, followed by -run_it(), and somewhere in run_it() lies the strcpy() at fault. Things such as -this help developers narrow down problems. There are a few exceptions to the -output. First off is forgetting to enable debug symbols with -<c>FEATURES="nostrip"</c>. With debug symbols stripped, the output looks something -like this: -</p> - -<pre caption="Program backtrace With debug symbols stripped"> -(gdb) <i>bt</i> -#0 0xb7e2cdc0 in strcpy () from /lib/libc.so.6 -#1 0x0804838c in ?? () -#2 0xbfd19510 in ?? () -#3 0x00000000 in ?? () -#4 0x00000000 in ?? () -#5 0xb7eef148 in libgcc_s_personality () from /lib/libc.so.6 -#6 0x080482ed in ?? () -#7 0x080495b0 in ?? () -#8 0xbfd19528 in ?? () -#9 0xb7dd73b8 in __guard_setup () from /lib/libc.so.6 -#10 0xb7dd742d in __guard_setup () from /lib/libc.so.6 -#11 0x00000006 in ?? () -#12 0xbfd19548 in ?? () -#13 0x080483ba in ?? () -#14 0x00000000 in ?? () -#15 0x00000000 in ?? () -#16 0xb7deebcc in __new_exitfn () from /lib/libc.so.6 -#17 0x00000000 in ?? () -#18 0xbfd19560 in ?? () -#19 0xb7ef017c in nullserv () from /lib/libc.so.6 -#20 0xb7dd6f37 in __libc_start_main () from /lib/libc.so.6 -#21 0x00000001 in ?? () -#22 0xbfd195d4 in ?? () -#23 0xbfd195dc in ?? () -#24 0x08048201 in ?? () -</pre> - -<p> -This backtrace contains a large number of ?? marks. This is because without -debug symbols, <c>gdb</c> doesn't know how the program was run. Hence, it is -crucial that debug symbols are <e>not</e> stripped. Now remember a while ago we -mentioned the -ggdb flag. Let's see what the output looks like with the flag -enabled: -</p> - -<pre caption="Program backtrace with -ggdb3"> -(gdb) <i>bt</i> -#0 0xb7e4bdc0 in strcpy () from /lib/libc.so.6 -#1 0x0804838c in run_it (input=0x0) at bad_code.c:7 -#2 0x080483ba in main (argc=1, argv=0xbfd3a434) at bad_code.c:12 -</pre> - -<p> -Here we see that a lot more information is available for developers. Not only is -function information displayed, but even the exact line numbers of the source -files. This method is the most preferred if you can spare the extra space. -Here's how much the file size varies between debug, strip, and -ggdb enabled -programs. -</p> - -<pre caption="Filesize differences With -ggdb flag"> -<comment>(debug symbols stripped)</comment> --rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code -<comment>(debug symbols enabled)</comment> --rwxr-xr-x 1 chris users 6374 6/28 13:10 bad_code -<comment>(-ggdb flag enabled)</comment> --rwxr-xr-x 1 chris users 19552 6/28 13:11 bad_code -</pre> - -<p> -As you can see, -ggdb adds about <e>13178</e> more bytes to the file size over the one -with debugging symbols. However, as shown above, this increase in file size can -be worth it if presenting debug information to developers. The backtrace can be -saved to a file by copying and pasting from the terminal (if it's a non-x based -terminal, you can use gpm. To keep this doc simple, I recommend you read up on -the documentation for gpm to see how to copy and paste with it). Now that we're -done with <c>gdb</c>, we can quit. -</p> - -<pre caption="Quitting GDB"> -(gdb) <i>quit</i> -The program is running. Exit anyway? (y or n) <i>y</i> -$ -</pre> - -<p> -This ends the walk-through of <c>gdb</c>. Using <c>gdb</c>, we hope that you will -be able to use it to create better bug reports. However, there are other types -of errors that can cause a program to fail during run time. One of the other -ways is through improper file access. We can find those using a nifty little -tool called <c>strace</c>. -</p> - -</body> -</section> -</chapter> - -<chapter> -<title>Finding file access errors using strace</title> -<section> -<title>Introduction</title> -<body> - -<p> -Programs often use files to fetch configuration information, access hardware or -write logs. Sometimes, a program attempts to reach such files incorrectly. A -tool called <c>strace</c> was created to help deal with this. <c>strace</c> -traces system calls (hence the name) which include calls that use the memory and -files. For our example, we're going to take a program foobar2. This is an -updated version of foobar. However, during the change over to foobar2, you notice -all your configurations are missing! In foobar version 1, you had it setup to -say "foo", but now it's using the default "bar". -</p> - -<pre caption="Foobar2 With an invalid configuration"> -$ <i>./foobar2</i> -Configuration says: bar -</pre> - -<p> -Our previous configuration specifically had it set to foo, so let's use -<c>strace</c> to find out what's going on. -</p> - -</body> -</section> -<section> -<title>Using strace to track the issue</title> -<body> - -<p> -We make <c>strace</c> log the results of the system calls. To do this, we run -<c>strace</c> with the -o[file] arguments. Let's use it on foobar2 as shown. -</p> - -<pre caption="Running foobar2 through strace"> -# <i>strace -ostrace.log ./foobar2</i> -</pre> - -<p> -This creates a file called <path>strace.log</path> in the current directory. We -check the file, and shown below are the relevant parts from the file. -</p> - -<pre caption="A Look At the strace Log"> -open(".foobar2/config", O_RDONLY) = 3 -read(3, "bar", 3) = 3 -</pre> - -<p> -Aha! So There's the problem. Someone moved the configuration directory to -<path>.foobar2</path> instead of <path>.foobar</path>. We also see the program -reading in "bar" as it should. In this case, we can recommend the ebuild -maintainer to put a warning about it. For now though, we can copy over the -config file from <path>.foobar</path> and modify it to produce the correct -results. -</p> - -</body> -</section> -<section> -<title>Conclusion</title> -<body> - -<p> -Now we've taken care of finding run time bugs. These bugs prove to be -problematic when you try and run your programs. However, run time errors are -the least of your concerns if your program won't compile at all. Let's take a -look at how to address <c>emerge</c> compile errors. -</p> - -</body> -</section> -</chapter> - -<chapter> -<title>Handling emerge Errors</title> -<section> -<title>Introduction</title> -<body> - -<p> -<c>emerge</c> errors, such as the one displayed earlier, can be a major cause -of frustration for users. Reporting them is considered crucial for maintaining -the health of Gentoo. Let's take a look at a sample ebuild, foobar2, which -contains some build errors. -</p> - -</body> -</section> -<section id="emerge_error"> -<title>Evaluating emerge Errors</title> -<body> - -<p> -Let's take a look at this very simple <c>emerge</c> error: -</p> - -<pre caption="emerge Error"> -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 -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 -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 -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 -foobar2.c:1:17: ogg.h: No such file or directory -make: *** [foobar2.o] Error 1 - -!!! ERROR: sys-apps/foobar2-1.0 failed. -!!! Function src_compile, Line 19, Exitcode 2 -!!! Make failed! -!!! If you need support, post the topmost build error, NOT this status message -</pre> - -<p> -The program is compiling smoothly when it suddenly stops and presents an error message. This -particular error can be split into 3 different sections, The compile messages, the build -error, and the emerge error message as shown below. -</p> - -<pre caption="Parts of the error"> -<comment>(Compilation Messages)</comment> -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 -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 -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 -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 - -<comment>(Build Error)</comment> -foobar2.c:1:17: ogg.h: No such file or directory -make: *** [foobar2.o] Error 1 - -<comment>(emerge Error)</comment> -!!! ERROR: sys-apps/foobar2-1.0 failed. -!!! Function src_compile, Line 19, Exitcode 2 -!!! Make failed! -!!! If you need support, post the topmost build error, NOT this status message -</pre> - -<p> -The compilation messages are what lead up to the error. Most often, it's good to -at least include 10 lines of compile information so that the developer knows -where the compilation was at when the error occurred. -</p> - -<p> -Make errors are the actual error and the information the developer needs. When -you see "make: ***", this is often where the error has occurred. Normally, you -can copy and paste 10 lines above it and the developer will be able to address -the issue. However, this may not always work and we'll take a look at an -alternative shortly. -</p> - -<p> -The emerge error is what <c>emerge</c> throws out as an error. Sometimes, this -might also contain some important information. Often people make the mistake of -posting the emerge error and that's all. This is useless by itself, but with -make error and compile information, a developer can get what application and -what version of the package is failing. As a side note, make is commonly used as -the build process for programs (<b>but not always</b>). If you can't find a -"make: ***" error anywhere, then simply copy and paste 20 lines before the -emerge error. This should take care of most all build system error messages. Now -let's say the errors seem to be quite large. 10 lines won't be enough to catch -everything. That's where PORT_LOGDIR comes into play. -</p> - -</body> -</section> -<section> -<title>emerge and PORT_LOGDIR</title> -<body> - -<p> -PORT_LOGDIR is a portage variable that sets up a log directory for separate -emerge logs. Let's take a look and see what that entails. First, run your -emerge with PORT_LOGDIR set to your favorite log location. Let's say we have a -location <path>/var/log/portage</path>. We'll use that for our log directory: -</p> - -<note> -In the default setup, <path>/var/log/portage</path> does not exist, and you will -most likely have to create it. If you do not, portage will fail to write the -logs. -</note> - -<pre caption="emerge-ing With PORT_LOGDIR"> -# <i>PORT_LOGDIR=/var/log/portage emerge foobar2</i> -</pre> - -<p> -Now the emerge fails again. However, this time we have a log we can work with, -and attach to the bug later on. Let's take a quick look at our log directory. -</p> - -<pre caption="PORT_LOGDIR Contents"> -# <i>ls -la /var/log/portage</i> -total 16 -drwxrws--- 2 root root 4096 Jun 30 10:08 . -drwxr-xr-x 15 root root 4096 Jun 30 10:08 .. --rw-r--r-- 1 root root 7390 Jun 30 10:09 2115-foobar2-1.0.log -</pre> - -<p> -The log files have the format [counter]-[package name]-[version].log. Counter -is a special variable that is meant to state this package as the n-th package -you've emerged. This prevents duplicate logs from appearing. A quick look at -the log file will show the entire emerge process. This can be attached later -on as we'll see in the bug reporting section. Now that we've safely obtained -our information needed to report the bug we can continue to do so. However, -before we get started on that, we need to make sure no one else has reported -the issue. Let's take a look at searching for bugs. -</p> - -</body> -</section> -</chapter> - -<chapter> -<title>Searching Using Bugzilla</title> -<section> -<title>Introduction</title> -<body> - -<p> -<uri link="http://www.bugzilla.org";>Bugzilla</uri> is what we at Gentoo use to -handle bugs. Gentoo's Bugzilla is reachable by HTTPS and HTTP. HTTPS is -available for those on insecure networks or simply paranoid :). For the sake of -consistency, we will be using the HTTPS version in the examples to follow. Head -over to <uri link="https://bugs.gentoo.org";>Gentoo Bugs</uri> to see how it -looks. -</p> - -<p> -One of the most frustrating things for developers and bug-wranglers is finding -duplicate bug reports. These cost them valuable time that they could otherwise -use to work on more important bugs. Often, this can be prevented by a few simple -search methods. So we're going to see how to search for bugs and find out if -you have one that's similar. For this example, we're going to use the xclass -emerge error that was used earlier. -</p> - -<pre caption="xclass emerge error"> -/usr/lib/gcc-lib/i686-pc-linux-gnu/3.3.2/include/g++-v3/backward/backward_warning.h:32:2: -warning: #warning This file includes at least one deprecated or antiquated -header. Please consider using one of the 32 headers found in section 17.4.1.2 of -the C++ standard. Examples include substituting the <X> header for the <X.h> -header for C++ includes, or <sstream> instead of the deprecated header -<strstream.h>. To disable this warning use -Wno-deprecated. -In file included from main.cc:40: -menudef.h:55: error: brace-enclosed initializer used to initialize ` -OXPopupMenu*' -menudef.h:62: error: brace-enclosed initializer used to initialize ` -OXPopupMenu*' -menudef.h:70: error: brace-enclosed initializer used to initialize ` -OXPopupMenu*' -menudef.h:78: error: brace-enclosed initializer used to initialize ` -OXPopupMenu*' -main.cc: In member function `void OXMain::DoOpen()': -main.cc:323: warning: unused variable `FILE*fp' -main.cc: In member function `void OXMain::DoSave(char*)': -main.cc:337: warning: unused variable `FILE*fp' -make[1]: *** [main.o] Error 1 -make[1]: Leaving directory -`/var/tmp/portage/xclass-0.7.4/work/xclass-0.7.4/example-app' -make: *** [shared] Error 2 - -!!! ERROR: x11-libs/xclass-0.7.4 failed. -!!! Function src_compile, Line 29, Exitcode 2 -!!! 'emake shared' failed -</pre> - -<p> -So to begin searching, we head over to the <uri -link="https://bugs.gentoo.org/";>Bugzilla Homepage</uri>. -</p> - -<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/> - -<p> -We'll click on "Query Existing bug reports". The reason why we choose this -over the basic bug search is because the basic bug search tends to give vague -results and often hinders users from looking through the results and finding the -duplicate bug. Once we click on the query screen, we reach the next page: -</p> - -<figure link="/images/docs/bugzie-search.png" caption="Bugzilla Search Page"/> - -<note> -If you've used the Advanced Search before, you'll most likely see that screen -instead. -</note> - -<p> -Proceed by clicking on the "Advanced Search" link to bring up the Advanced -Search page. -</p> - -<figure link="/images/docs/bugzie-adv-search.png" caption="Advanced Search Page"/> - -<p> -This is how the Advanced Search Page looks like. While it may seem overwhelming -at first, we're going to look at a few simple areas to narrow down the rather -vague searches bugzilla returns. -</p> - -<figure link="/images/docs/bugzie-content.png" caption="Content"/> - -<p> -The first field is the summary of the bug. Here we're simply going to put the -name of the package that's crashing. If bugzie doesn't return results, try -removing the package name, just in case someone didn't put that in the summary -(highly unlikely, but we've seen a fair share of strange bug reports). -</p> - -<p> -Product, Component, and Version should all be set to the default. This -prevents us from being too specific and missing all the bugs. -</p> - -<p> -Comment is the important part. Use the comment field to list what appears to be a -specific instance of the error. Basically, don't use anything like the -beginning of the build error, find a line that's before it stating a true -error. Also, you'll want to filter out any punctuation to prevent bugzilla -from interpreting the results the comment the wrong way. Example from the xclass -emerge error: -</p> - -<pre caption="Comment Line Content"> -menudef.h:78: error: brace-enclosed initializer used to initialize `OXPopupMenu' -<comment>(Remove the quotes ' ')</comment> -menudef.h 78 error brace-enclosed initializer used to initialize OXPopupMenu -</pre> - -<p> -The above is specific enough to where we'll find the bug without wading through -other xclass compile failure candidates. -</p> - -<p> -URI, Whiteboard, and Keywords can all be left alone. What we've entered so far -should be enough to find our bug. Let's take a look at what we have filled out. -</p> - -<figure link="/images/docs/bugzie-comp-search.png" caption="Completed Search Form"/> - -<p> -Now we click on the Search button and here come the results... -</p> - -<figure link="/images/docs/bugzie-search-result.png" caption="Search Results"/> - -<p> -Only 2 bugs! That's a lot easier to deal with. We click on the first one to -check, and sure enough it's the one we're looking for. -</p> - -<figure link="/images/docs/bugzie-located.png" caption="Bug Located"/> - -<p> -Not only is it the one we want, but it has also been resolved. By checking the -last comment we see the solution and know what to do in order to resolve it. -Now, let's see what would have happened if we had not used the advanced search. -</p> - -<figure link="/images/docs/bugzie-basic-search-result.png" caption="Basic Search Results"/> - -<p> -4 more bugs to deal with! It gets even worse with larger packages. However, -with these simple tools, we're able to significantly narrow down the search to -try and locate a specific bug. -</p> - -</body> -</section> -<section> -<title>Conclusion</title> -<body> - -<p> -Let's say that you have searched and searched but still can't find a bug. -You've found yourself a new bug. Let's take a look at the bug reporting process -for submitting your new bug. -</p> - -</body> -</section> -</chapter> - -<chapter> -<title>Reporting Bugs</title> -<section> -<title>Introduction</title> -<body> - -<p> -In this chapter, we'll figure out how to use Bugzilla to file a shiny, new bug. -Head over to <uri link="https://bugs.gentoo.org";>Gentoo Bugs</uri> and... -</p> - -<figure link="/images/docs/bugzie-homepage.png" caption="Bugzilla Homepage"/> - -<p> -Click on "Report a Bug - Using the guided format". -</p> - -<figure link="/images/docs/bugzie-prod-select.png" caption="Product Selection"/> - -<p> -As you can see, <b>major</b> emphasis has been placed on putting your bug in the -right place. Gentoo Linux is where a large majority of bugs go. -</p> - -<p> -Despite this, some people will file ebuild bugs in portage development -(assumption that portage team handles the portage tree) or infra (assumption -that infra has access to mirrors and rsync and can fix it directly). This is -simply not how things work. -</p> - -<p> -Another common misconception occurs with our Documentation bugs. For example, a -user finds a bug with the <uri link="/proj/en/releng/catalyst/">Catalyst -Docs</uri>. The general tendency is to file a bug under Docs-user, which gets -assigned to the <uri link="http://gdp.gentoo.org";>GDP</uri>, when it should -actually go to a member of the <uri link="/proj/en/releng/">Release -Engineering</uri> team. As a rule of thumb, only documentation under -<path>http://www.gentoo.org/doc/*</path> is under the GDP. Anything under -<path>http://www.gentoo.org/proj/*</path> is under the respective teams. -</p> - -<note> -We would rather see a bug whose product was not supposed to be Gentoo Linux but -has been filed under the same rather than seeing a bug which belongs the Gentoo -Linux product and filed elsewhere. While neither is preferred, the former is more -acceptable and understandable (except website bugs.. we might have an issue with -that...). -</note> - -<p> -Our bug goes in Gentoo Linux as it's an ebuild bug. We head over there and are -presented with the multi-step bug reporting process. Let us now proceed with -Step 1... -</p> - -<figure link="/images/docs/bugzie-guide-step1.png" caption="Guided Format Step 1"/> - -<p> -The first step here is really important (as the red text tells you). This is -where you search to see that someone else hasn't hit the same bug you have, yet. -If you do skip this step and a bug like yours already exists, it will be marked -as a DUPLICATE thus wasting a large amount of QA effort. To give you an idea, -the bug numbers that are struck out above are duplicate bugs. Now comes step 2, -where we give the information. -</p> - -</body> -</section> -<section> -<title>Required Information</title> -<body> - -<figure link="/images/docs/bugzie-basic.png" caption="Basic Information"/> - -<p> -Let us take a closer look at what's what. -</p> - -<ul> - <li> - First, there's the Product. The product will narrow down the bug to a - specific area of Gentoo like Bugzilla (for bugs relating to - bugs.gentoo.org), Docs-user(for User Documentation) or Gentoo Linux (for - ebuilds and the like). - </li> - <li> - Component is where exactly the problem occurs, more specifically which part - of selected product the bug comes under. This makes classification easier. - </li> - <li> - Hardware platform is what architecture you're running. If you were running - SPARC, you would set it to SPARC. - </li> - <li> - Operating System is what Operating System you're using. Because Gentoo is - considered a "Meta-distribution", it can run on other operating systems - beside Linux. - </li> -</ul> - -<p> -So, for our example bug, we have : -</p> - -<ul> - <li>Product - Gentoo Linux (Since it is an ebuild issue)</li> - <li>Component - Application (It is an application at fault, foobar2)</li> - <li>Hardware Platform - All (This error could occur across architectures)</li> - <li>Operation System - All (It could occur on all types of systems)</li> -</ul> - -<figure link="/images/docs/bugzie-basic-comp.png" caption="Completed Basic Information"/> - -<ul> - <li> - Build Identifier is basically the User Agent of the browser that is being - used to report the bugs (for logging purposes). You can just leave this as - is. - </li> - <li> - URL is optional and is used to point to errors on a site someplace - (pastebin, etc.). However, doing it inside the bug allows the developers be - able to reference to it at any time and is preferred. - </li> - <li> - In the Summary, you should put the package category, name, and number. - </li> -</ul> - -<p> -Not including the category in the summary really isn't too bad, but it's -recommended. If you don't include the package name, however, we won't know what -you're filling a bug for, and will have to ask you about it later. The version -number is important for people searching for bugs. If 20 people filed bugs and -not one put a version number, how would people looking for similar bugs be able -to tell if one was there's? They'd have to look through every single bug, which -isn't too hard, but if there are say, 200 bugs.. it's not that easy. After all -the package information, you'll want to include a small description of the -incident. Here's an example: -</p> - -<figure link="/images/docs/bugzie-summary.png" caption="Summary"/> - -<p> -These simple rules can make handling bugs a lot easier. Next are the details. -Here we put in the information about the bug. We'll demonstrate with an example: -</p> - -<figure link="/images/docs/bugzie-details.png" caption="Details"/> - -<p> -Now the developer knows why we're filing the bug. They can then try to -reproduce it. Reproducibility tells us how often we were able to make the -problem recur. In this example, we can reproduce it any time simply by running -foobar2. Let's put that information in. -</p> - -<figure link="/images/docs/bugzie-reprod.png" caption="Reproduction"/> - -<p> -We have explained how we found the bug. The next step is to explain what were -the results we got and what we think they should actually be. -</p> - -<figure link="/images/docs/bugzie-results.png" caption="Results"/> - -<p> -We could then provide additional information. This could be things such as -stack traces, <b>sections</b> (since the whole log is usually big and of not -much use) of strace logs, but most importantly, your <c>emerge --info</c> -output. Here's an example. -</p> - -<figure link="/images/docs/bugzie-addl-info.png" caption="Additional Information"/> - -<p> -Lastly we select the severity of the bug. Please look this over carefully. In -most cases it's OK to leave it as is and someone will raise/lower it for you. -However, if you raise the severity of the bug, please make sure you read it over -carefully and make sure you're not making a mistake. A run down of the various -levels is given below. -</p> - -<ul> - <li> - Blocker - The program just plain doesn't want to emerge or is a major - hinderance to the system. For example a <c>baselayout</c> issue which - prevents a system from booting up would be a sure candidate to be labelled - blocker. - </li> - <li> - Critical - The program has loss of data or severe memory leaks during - runtime. Again, an important program like say <c>net-tools</c> failing to - compile could be labelled critical. It won't prevent the system from - starting up, but is quite essential for day to day stuff. - </li> - <li> - Major - The program crashes, but nothing that causes your system severe - damage or information loss. - </li> - <li> - Minor - Your program crashes here and there with apparent workarounds. - </li> - <li> - Normal - The default. If you're not sure leave it here unless it's a new - build or cosmetic change, then read below for more information. - </li> - <li>Trivial - Things such as a mispelled word or whitespace clean up. </li> - <li> - Enhancement - A request to enable a new feature in a program, or more - specifically <e>new ebuilds</e>. - </li> -</ul> - -<figure link="/images/docs/bugzie-sev.png" caption="Severity"/> - -<p> -Here, we'll set it to Normal. -</p> - -<p> -Now we can submit the bug report by clicking on the Submit Bug Report box. You -will now see your new bug come up. See <uri -link="https://bugs.gentoo.org/show_bug.cgi?id=97265";>Bug 97561</uri> for what -the result looks like. We've reported our bug! Now let's see how it's dealt -with. -</p> - -</body> -</section> -</chapter> - -<chapter> -<title>Working With Your Bug</title> -<section> -<body> - -<p> -Looking at the bug, we see the information we provided earlier. You will notice -that the bug has been assigned to [EMAIL PROTECTED] This is the default -location for Application component bugs. -</p> - -<figure link="/images/docs/bugzie-new-basic.png" caption="New Bug Basic Information"/> - -<p> -The details we entered about the bug are available as well. -</p> - -<figure link="/images/docs/bugzie-new-details.png" caption="New Bug Details"/> - -<p> -However, bug-wranglers (usually) won't fix our bugs, so we'll reassign it to -someone that can (you can let bug-wranglers re-assign it for you as well). For -this we use the package's metadata.xml. You can normally find them in -<path>/usr/portage/category/package/metadata.xml</path>. Here's one I've made up -for foobar2. -</p> - -<note> -You have to be the reporter of the bug or a member of certain Gentoo Bugzilla -groups (like Gentoo Developers) to be able to reassign bugs. -</note> - -<pre caption="metadata.xml"> -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> -<pkgmetadata> -<herd>chriswhite</herd> -<maintainer> -<email>[EMAIL PROTECTED]</email> -<name>Chris White</name> -</maintainer> -<longdescription lang="en"> -Foobar2 is a package that uses a configuration file to display a word. -</longdescription> -</pkgmetadata> -</pre> - -<p> -Notice the maintainer section. This lists the maintainer of the package, which -in this case is myself, Chris White. The email listed is [EMAIL PROTECTED] -We will use this to re-assign the bug to the proper person. To do this, click -the bubble next to Reassign bug to, then fill in the email. -</p> - -<note> -A bug for a package without a metadata.xml file should be re-assigned to [EMAIL PROTECTED] and a package that needs a Gentoo Developer to -maintain should be assigned to [EMAIL PROTECTED] -</note> - -<figure link="/images/docs/bugzie-reassign.png" caption="Bug Reassignment"/> - -<p> -Then hit the Commit button for the changes to take place. The bug has been -reassigned to me. Shortly afterward, you notice (by email usually) that I've -responded to your bug. I've stated that I'd like to see an strace log to figure -out how the program is trying to reach your configuration file. You follow the -previous instructions on using strace and obtain an strace log. Now you need to -attach it to the bug. In order to do this, click on "Create A New Attachment". -</p> - -<figure link="/images/docs/bugzie-new-attach.png" caption="New Attachment"/> - -<p> -Now we have to attach the log. Let's go throught it step wise. -</p> - -<ul> - <li> - File - This is the location of the file in your machine. In this example, - the location of <path>strace.log</path>. You can use the "Browse..." button - to select the file, or enter the path directly in the text field. - </li> - <li> - Description - A short one liner, or a few wors describing the attachment. - We'll just enter strace.log here, since that's quite self-explanatory. - </li> - <li> - Content Type - This is the type of the file we're attaching to the bug. - </li> - <li> - Obsoletes - If there were attachements submitted to the bug before the - current one, you have an option of declaring them obsoleted by yours. Since - we have no prior attachments to this bug, we need not bother. - </li> - <li> - Comment - Enter comments that will be visible along with the attachments. - You could elaborate on the attachment here, if needed. - </li> -</ul> - -<p> -With respect to Content Type, here are a few more details. You can check the -"patch" checkbox if you're submitting a patch. Otherwise, you could ask -Bugzilla to "auto-detect" the file type (not advisable). The other options are -"select from list", which is most frequently used. Use plain text (text/plain) -for <e>most</e> attachments except binary files like images (which can use -image/gif, image/jpeg or image/png depending on type) or compressed files like -.tar.bz2 which would use application/octet-stream as content type. -</p> - - -<figure link="/images/docs/bugzie-new-attach-comp.png" caption="New Attachment Completed"/> - -<p> -We submit <path>strace.log</path> and it is reflected on the bug report. -</p> - -<figure link="/images/docs/bugzie-strace.png" caption="Attached strace log"/> - -<p> -We've mentioned before that sometimes ebuilds will tell you to attach a file in -the emerge error. An example can be seen below. -</p> - -<pre caption="Example File Attachment Request"> -configure: error: PNG support requires ZLIB. Use --with-zlib-dir=<DIR> - -!!! Please attach the config.log to your bug report: -!!! /var/tmp/portage/php-5.0.3-r1/work/php-5.0.3/config.log - -!!! ERROR: dev-php/php-5.0.3-r1 failed. -!!! Function econf, Line 485, Exitcode 0 -!!! econf failed -!!! If you need support, post the topmost build error, NOT this status message. -</pre> - -<p> -Please attach any file mentioned like this to your bug report. -</p> - -<p> -While we're doing all this, suppose another person finds your bug by searching -through bugzilla and is curious to keep track of the bug, they may do so by -putting their email in the Add CC field of the bug as shown below. You could -also keep track of other bugs by following the same method. -</p> - -<figure link="/images/docs/bugzie-add-email.png" caption="Adding Email To CC:"/> - -<note> -Email addresses must be registered with Gentoo Bugzilla. In order to CC multiple -addresses, simply separate them with commas or spaces. -</note> - -<p> -After all this work, the bug can undergo various status markings. This is -usually done by the Gentoo Developers and sometimes by the reporter. The -following are the various possible states a bug may go through during its -lifetime. -</p> - -<ul> - <li> - UNCONFIRMED - You're generally not going to see this too often. This means - that a bug reporter has opened a bug using the advanced method and is - uncertain his or her bug is an actual bug. - </li> - <li>NEW - Bugs that are first opened are considered new.</li> - <li> - ASSIGNED - When the person you've assigned the bug too validates your bug, - it will often receive ASSIGNED status while they figure out the issue. - This lets you know that they've accepted your bug as a real bug. - </li> - <li> - REOPENED - Someone has resolved a bug and you think the solution is not - feasible or the problem still persists. At this point, you may re-open the - bug. Please <b>do not abuse this</b>. If a developer closes the bug a - second or third time, chances are that your bug is closed. - </li> - <li> - RESOLVED - A firm decision has been taken on the bug. Usually goes onto - FIXED to indicate the bug is solved and the matter closed although various - other resolutions are possible. We'll look into those a little later. - </li> - <li> - VERIFIED - The steps take to work the bug are correct. This is usually a QA - thing. - </li> - <li> - CLOSED - Basically means RIP for the bug and it's buried under the never - ending flow of new bugs. - </li> -</ul> - -<p> -Now shortly afterward, we find the error in the strace log and fix the bug and -mark it as RESOLVED FIXED and mention that there was a change in the location -of configuration files, and that I will update the ebuild with a warning about -it. The bug now becomes resolved, and you are shown the following. -</p> - -<figure link="/images/docs/bugzie-reso.png" caption="Resolved Bug"/> - -<p> -A little below, you'll see the following: -</p> - -<figure link="/images/docs/bugzie-options.png" caption="Bug Options"/> - -<p> -This gives you the option of Reopening the bug if you wish to (i.e. the -developer thinks it's resolved but it's really not to your standards). Now our -bug is fixed! However, different resolutions can occur. Here's a small list: -</p> - -<ul> - <li> - FIXED - The bug is fixed, follow the instructions to resolve your issue. - </li> - <li> - INVALID - You did not do something specifically documented, causing the - bug. - </li> - <li>DUPLICATE - You didn't use this guide and reported a duplicate bug.</li> - <li> - WORKSFORME - Developer/person assigned the bug cannot reproduce your error. - </li> - <li> - CANTFIX - Somehow the bug cannot be solved because of certain - circumstances. These circumstances will be noted by the person taking the - bug. - </li> - <li> - WONTFIX - This is usually applied to new ebuilds or feature requests. - Basically the developer does not want to add a certain feature because it - is not needed, a better alternative exists, or it's just plain broken. - Sometimes you may be given a solution to get said issue resolved. - </li> - <li> - UPSTREAM - The bug cannot be fixed by the Gentoo development team, and have - requested you take the problem upstream (the people that actually made the - program) for review. Upstream has a few ways of handling bugs. These - include mailing lists, irc channels, and even bug reporting systems. If - you're not sure how to contact them, ask in the bug and someone will point - you to the right direction. - </li> -</ul> - -<p> -Sometimes, before the bug can be resolved, a developer may request that you -test an updated ebulid. In the next chapter we'll take a look at testing -ebuilds. -</p> - -</body> -</section> -</chapter> - -<chapter> -<title>Testing Ebuilds</title> -<section> -<title>Getting The Files</title> -<body> - -<p> -Let's say that you reported a bug for the foobar2 compile fix from earlier. Now -developers might find out what the problem is and might need you to test the -ebuild for them to be sure it works for you as well: -</p> - -<figure link="/images/docs/bugzie-ebuild-request.png" caption="Ebuild Test Request"/> - -<p> -Some rather confusing vocabulary is used here. First off, let's see what an -overlay is. An overlay is a special directory like <path>/usr/portage</path>, -the difference being that when you <c>emerge sync</c>, files contained within it -will not be deleted. Luckily, a special <path>/usr/local/portage</path> -directory is created for that purpose. Let's go ahead and set our portage -overlay in<path>/etc/make.conf</path>. Open make.conf up in your favorite editor -and add this towards the end. -</p> - -<pre caption="Setting Up PORTDIR_OVERLAY"> -PORTDIR_OVERLAY="/usr/local/portage" -</pre> - -<p> -Now we'll want to create the appropriate directories to put our test ebuild -files in. In this case, we're supposed to put them in sys-apps/foobar2. You'll -notice that the second comment asks for a files directory for the patch. The -files directory holds the digests (md5sums of files for a particular version of -a package) and any other required files that aren't included with the standard -source archive (patches, init.d scripts, etc). This is a subdir in the package -directory called files. Go ahead and create these directories: -</p> - -<pre caption="Setting Up The Category And Package Directories"> -# <i>mkdir -p /usr/local/portage/sys-apps/foobar2/files</i> -</pre> - -<note> -The -p in mkdir creates not only the directory you want but also any missing -parent directories as well (sys-apps and foobar2 in this case). -</note> - -<p> -Ok now, we can go ahead and download the files. First, download the ebuild -into <path>/usr/local/portage/sys-apps/foobar2</path>, and then add the patch -to <path>/usr/local/portage/sys-apps/foobar2/files</path>. Now that we have the -files, we can begin working on testing the ebuild. -</p> - -</body> -</section> -<section> -<title>Testing The ebuild</title> -<body> - -<p> -The process to create an ebuild that can be used by emerge is fairly simple. You -must create a Manifest and a digest file for the ebuild. This can be done with -the ebuild command. Run it as shown. -</p> - -<pre caption="Creating the Manifest and digest files"> -# <i>ebuild foobar2-1.0.ebuild digest</i> ->>> Generating digest file... -<<< foobar2-1.0.tar.bz2 ->>> Generating manifest file... -<<< foobar2-1.0.ebuild -<<< files/digest-foobar2-1.0 -<<< files/foobar2-1.0-Makefile.patch ->>> Computed message digests. -</pre> - -<p> -Now let's test to see if it works as it should. -</p> - -<pre caption="Testing With emerge -pv"> -# <i>emerge -pv foobar2</i> - -These are the packages that I would merge, in order: - -Calculating dependencies ...done! -[ebuild N ] sys-apps/foobar2-1.0 0 kB [1] - -Total size of downloads: 0 kB -Portage overlays: - [1] /usr/local/portage -</pre> - -<p> -It does seem to have worked! You'll notice the [1] next to the [ebuild] line. -That points to <path>/usr/local/portage</path>, which is the overlay we created -earlier. Now we go ahead and emerge the package. -</p> - -<pre caption="Emerge Result"> -# <i>emerge foobar2</i> - Calculating dependencies ...done! -<comment>(compile info snipped)</comment> ->>> Unpacking foobar2-1.0.tar.bz2 to /var/tmp/portage/foobar2-1.0/work - * Applying foobar2-1.0-Makefile.patch ... [ ok ] -<comment>(compile info snipped)</comment> ->>> Merging sys-apps/foobar2-1.0 to / ->>> chris +sandbox(preinst) ---- /usr/ ---- /usr/bin/ ->>> /usr/bin/foobar2 -</pre> - -<p> -In the first section we see that the emerge started off as it should. The second -section shows our patch being applied successfully by the "[ ok ]" status -message to the right. The last section tells us the program compiled ok. The -patch works! Now we can go and let the developer know that their patch works -fine, and that they can commit the fix to portage. -</p> - -</body> -</section> -<section> -<title>Conclusion</title> -<body> - -<p> -This concludes the howto on working with Bugzilla. I hope you find this useful. -If you have any questions, comments, or ideas regarding this document, please -send them to me at <mail>[EMAIL PROTECTED]</mail>. Special thanks go to -moreon for his notes on -g flags and compile errors, the people at #gentoo-bugs -for helping out with bug-wrangling, Griffon26 for his notes on -maintainer-needed, robbat2 for general suggestions and fox2mike for fixing up -the doc and adding stuff as needed. -</p> - -</body> -</section> -</chapter> - </guide> -- [email protected] mailing list
