fox2mike 05/07/07 12:02:21 Added: xml/htdocs/doc/en bugzilla-howto.xml Log: #97274 - Initial version of the doc, Lots of thanks to Chris "Da PUNK" White :)
Revision Changes Path 1.1 xml/htdocs/doc/en/bugzilla-howto.xml file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.1&content-type=text/x-cvsweb-markup&cvsroot=gentoo plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml?rev=1.1&content-type=text/plain&cvsroot=gentoo Index: bugzilla-howto.xml =================================================================== <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.1 2005/07/07 12:02:21 fox2mike Exp $ --> <guide link="/doc/en/bugzilla-howto.xml"> <title>Gentoo Bug Reporting Guide</title> <author title="Author"> <mail link="[EMAIL PROTECTED]">Chris White</mail> </author> <author title="Editor"> <mail link="[EMAIL PROTECTED]">Shyam Mani</mail> </author> <abstract> This document shows the proper method of reporting bugs using Bugzilla. </abstract> <!-- The content of this document is licensed under the CC-BY-SA license --> <!-- See http://creativecommons.org/licenses/by-sa/2.5 --> <license/> <version>1.0</version> <date>2005-07-07</date> <chapter> <title>Introduction</title> <section> <title>Preface</title> <body> <p> Often one of the factors that delay a bug being fixed is how it is reported. By creating this guide, I 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 of any project and hopefully this guide will help make that a success. </p> </body> </section> <section> <title>Initial Finding</title> <body> <p> You're emerge-ing a package or working with a program, then suddenly the worst happens -- you find a bug. Bugs come in many forms, whether it be 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 2 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 FEATURES="nostrip". 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 -g to your CFLAGS and CXXFLAGS. This flag adds more debugging information than is generally included. We'll see what that means later on. 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> Now that that's done, you will need to re-emerge your package to set the new debug settings into place. This can be done as follows: </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" (I know, it's sort of cheesy but..). Some person claims he can break the code 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> <p> You should see a small terminal like setup after that which 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> -- [email protected] mailing list
