Gentoo Linux Debugging Guide

1.0 2005-07-13 Introduction

Preface

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.

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.

$ ./bad_code `perl -e 'print Ax100'`
Segmentation fault

/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

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 -- gdb.

Debugging using GDB

Introduction

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 emerge 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.

(debug symbols stripped)
-rwxr-xr-x  1 chris users 3140  6/28 13:11 bad_code
(debug symbols intact)
-rwxr-xr-x  1 chris users 6374  6/28 13:10 bad_code

Just for reference, bad_code is the program we'll be debugging with gdb 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 /etc/make.conf might look with the newly added flags.

CFLAGS="-O2 -pipe -ggdb3"
CXXFLAGS="${CFLAGS}"

Lastly, you can also add debug to the package's USE flags. This can be done with the package.use file.

# echo "category/package debug" >> /etc/portage/package.use

The directory /etc/portage 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 package.use, you will need to manually modify them in your favorite editor.

Then we re-emerge the package with the modifications we've done so far as shown below.

# FEATURES="nostrip" emerge package

Now that debug symbols are setup, we can continue with debugging the program.

Running the program with GDB

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:

$ ./bad_code `perl -e 'print Ax100'`
Segmentation fault

It seems this person was right. Since the program is obviously broken, we have a bug at hand. Now, it's time to use gdb to help solve this matter. First we run gdb with --args, then give it the full program with arguments like shown:

$ gdb --args ./bad_code `perl -e 'print Ax100'`
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.



-- 
gentoo-doc-cvs@gentoo.org mailing list