fox2mike 05/07/09 22:31:57 Modified: xml/htdocs/doc/en bugzilla-howto.xml Log: Major updates to the guide. GuideXML corrections, content and grammer changes along with a few section additions. IMPORTANT : Translators, Please do not commence work on this guide for the next couple of days as the guide may see drastic changes. See gentoo-doc ML for details. Thanks.
Revision Changes Path 1.3 +539 -210 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.3&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.3&content-type=text/plain&cvsroot=gentoo diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/doc/en/bugzilla-howto.xml.diff?r1=1.2&r2=1.3&cvsroot=gentoo Index: bugzilla-howto.xml =================================================================== RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- bugzilla-howto.xml 7 Jul 2005 18:19:23 -0000 1.2 +++ bugzilla-howto.xml 9 Jul 2005 22:31:57 -0000 1.3 @@ -1,6 +1,6 @@ <?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.2 2005/07/07 18:19:23 fox2mike Exp $ --> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/bugzilla-howto.xml,v 1.3 2005/07/09 22:31:57 fox2mike Exp $ --> <guide link="/doc/en/bugzilla-howto.xml"> <title>Gentoo Bug Reporting Guide</title> @@ -20,8 +20,8 @@ <!-- See http://creativecommons.org/licenses/by-sa/2.5 --> <license/> -<version>1.1</version> -<date>2005-07-07</date> +<version>1.2</version> +<date>2005-07-10</date> <chapter> <title>Introduction</title> @@ -30,24 +30,24 @@ <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 +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 of any project and hopefully this +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>Initial Finding</title> +<title>Bugs!!!!</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. +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"> @@ -87,10 +87,10 @@ <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 +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> +errors -- <c>gdb</c>. </p> </body> @@ -108,10 +108,10 @@ 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. +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"> @@ -125,10 +125,19 @@ 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 +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="-O2 -pipe -gddb3" +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> @@ -144,8 +153,8 @@ </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: +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"> @@ -163,9 +172,8 @@ <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: +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"> @@ -191,14 +199,20 @@ 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 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: +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) run +(gdb) <i>run</i> Starting program: /home/chris/bad_code Program received signal SIGSEGV, Segmentation fault. @@ -219,22 +233,23 @@ </p> <pre caption="Program backtrace"> -(gdb) bt +(gdb) <i>bt</i> #0 0xb7ec6dc0 in strcpy () from /lib/libc.so.6 #1 0x0804838c in run_it () #2 0x080483ba in main () </pre> <p> -So as we see here, first main() was run, then run_it(), and somewhere in run_it -lies the strcpy() at fault. Things such as this help developers narrow things -down. Now, there are a few exceptions to the output. First off is forgetting -to disable debug symbols with FEATURES="nostrip". With debug symbols stripped, -output looks something like this: +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) bt +(gdb) <i>bt</i> #0 0xb7e2cdc0 in strcpy () from /lib/libc.so.6 #1 0x0804838c in ?? () #2 0xbfd19510 in ?? () @@ -264,13 +279,14 @@ <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 ran. Hence, it is -crucial that debug symbols are <e>not</e> stripped. Now remember a while ago I -told you about the -g flag. Let's see what the output looks like with that: +debug symbols, <c>gdb</c> doesn't know how the program was run. Hence, it is -- [email protected] mailing list
