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

Diff of /xml/htdocs/doc/en/draft/debugging-howto.xml

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

Revision 1.4 Revision 1.5
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/draft/debugging-howto.xml,v 1.4 2005/07/14 09:54:37 fox2mike Exp $ --> 3<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/draft/debugging-howto.xml,v 1.5 2005/09/29 15:11:35 neysx Exp $ -->
4 4
5<guide link="/doc/en/debugging-howto.xml"> 5<guide link="/doc/en/draft/debugging-howto.xml">
6<title>Gentoo Linux Debugging Guide</title> 6<title>Gentoo Linux Debugging Guide</title>
7 7
8<author title="Author"> 8<author title="Author">
9 <mail link="chriswhite@gentoo.org">Chris White</mail> 9 <mail link="chriswhite@gentoo.org">Chris White</mail>
10</author> 10</author>
88 88
89<p> 89<p>
90These errors can be quite troublesome. However, once you find them, what do 90These errors can be quite troublesome. However, once you find them, what do
91you do? The following sections will look at two important tools for handling 91you do? The following sections will look at two important tools for handling
92run time errors. After that, we'll take a look at compile errors, and how to 92run time errors. After that, we'll take a look at compile errors, and how to
93handle them. Let's start out with the first tool for debugging run time 93handle them. Let's start out with the first tool for debugging run time
94errors -- <c>gdb</c>. 94errors -- <c>gdb</c>.
95</p> 95</p>
96 96
97</body> 97</body>
98</section> 98</section>
110normally involve memory corruption. First off, let's take a look at what 110normally involve memory corruption. First off, let's take a look at what
111debugging entails. One of the main things you must do in order to debug a 111debugging entails. One of the main things you must do in order to debug a
112program is to <c>emerge</c> the program with <c>FEATURES="nostrip"</c>. This 112program is to <c>emerge</c> the program with <c>FEATURES="nostrip"</c>. This
113prevents the stripping of debug symbols. Why are programs stripped by default? 113prevents the stripping of debug symbols. Why are programs stripped by default?
114The reason is the same as that for having gzipped man pages -- saving space. 114The reason is the same as that for having gzipped man pages -- saving space.
115Here's how the size of a program varies with and without debug symbol stripping. 115Here's how the size of a program varies with and without debug symbol stripping.
116</p> 116</p>
117 117
118<pre caption="Filesize Comparison"> 118<pre caption="Filesize Comparison">
119<comment>(debug symbols stripped)</comment> 119<comment>(debug symbols stripped)</comment>
120-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code 120-rwxr-xr-x 1 chris users 3140 6/28 13:11 bad_code
127<c>gdb</c> later on. As you can see, the program without debugging symbols is 127<c>gdb</c> later on. As you can see, the program without debugging symbols is
1283140 bytes, while the program with them is 6374 bytes. That's close to double 1283140 bytes, while the program with them is 6374 bytes. That's close to double
129the size! Two more things can be done for debugging. The first is adding ggdb3 129the size! Two more things can be done for debugging. The first is adding ggdb3
130to your CFLAGS and CXXFLAGS. This flag adds more debugging information than is 130to your CFLAGS and CXXFLAGS. This flag adds more debugging information than is
131generally included. We'll see what that means later on. This is how 131generally included. We'll see what that means later on. This is how
132<path>/etc/make.conf</path> <e>might</e> look with the newly added flags. 132<path>/etc/make.conf</path> <e>might</e> look with the newly added flags.
133</p> 133</p>
134 134
135<pre caption="make.conf settings"> 135<pre caption="make.conf settings">
136CFLAGS="-O2 -pipe -ggdb3" 136CFLAGS="-O2 -pipe -ggdb3"
137CXXFLAGS="${CFLAGS}" 137CXXFLAGS="${CFLAGS}"
138</pre> 138</pre>
139 139
140<p> 140<p>
141Lastly, you can also add debug to the package's USE flags. This can be done 141Lastly, you can also add debug to the package's USE flags. This can be done
142with the <path>package.use</path> file. 142with the <path>package.use</path> file.
143</p> 143</p>
144 144
145<pre caption="Using package.use to add debug USE flag"> 145<pre caption="Using package.use to add debug USE flag">
146# <i>echo "category/package debug" >> /etc/portage/package.use</i> 146# <i>echo "category/package debug" >> /etc/portage/package.use</i>
147</pre> 147</pre>
148 148
243<p> 243<p>
244You can notice the trace pattern clearly. main() is called first, followed by 244You can notice the trace pattern clearly. main() is called first, followed by
245run_it(), and somewhere in run_it() lies the strcpy() at fault. Things such as 245run_it(), and somewhere in run_it() lies the strcpy() at fault. Things such as
246this help developers narrow down problems. There are a few exceptions to the 246this help developers narrow down problems. There are a few exceptions to the
247output. First off is forgetting to enable debug symbols with 247output. First off is forgetting to enable debug symbols with
248<c>FEATURES="nostrip"</c>. With debug symbols stripped, the output looks 248<c>FEATURES="nostrip"</c>. With debug symbols stripped, the output looks
249something like this: 249something like this:
250</p> 250</p>
251 251
252<pre caption="Program backtrace With debug symbols stripped"> 252<pre caption="Program backtrace With debug symbols stripped">
253(gdb) <i>bt</i> 253(gdb) <i>bt</i>
309<comment>(-ggdb3 flag enabled)</comment> 309<comment>(-ggdb3 flag enabled)</comment>
310-rwxr-xr-x 1 chris users 19552 6/28 13:11 bad_code 310-rwxr-xr-x 1 chris users 19552 6/28 13:11 bad_code
311</pre> 311</pre>
312 312
313<p> 313<p>
314As you can see, -ggdb3 adds about <e>13178</e> more bytes to the file size 314As you can see, -ggdb3 adds about <e>13178</e> more bytes to the file size
315over the one with debugging symbols. However, as shown above, this increase 315over the one with debugging symbols. However, as shown above, this increase
316in file size can be worth it if presenting debug information to developers. 316in file size can be worth it if presenting debug information to developers.
317The backtrace can be saved to a file by copying and pasting from the 317The backtrace can be saved to a file by copying and pasting from the
318terminal (if it's a non-x based terminal, you can use gpm. To keep this 318terminal (if it's a non-x based terminal, you can use gpm. To keep this
319doc simple, I recommend you read up on the documentation for gpm to see 319doc simple, I recommend you read up on the documentation for gpm to see
320how to copy and paste with it). Now that we're done with <c>gdb</c>, we 320how to copy and paste with it). Now that we're done with <c>gdb</c>, we
321can quit. 321can quit.
322</p> 322</p>
323 323
324<pre caption="Quitting GDB"> 324<pre caption="Quitting GDB">
325(gdb) <i>quit</i> 325(gdb) <i>quit</i>
326The program is running. Exit anyway? (y or n) <i>y</i> 326The program is running. Exit anyway? (y or n) <i>y</i>
327$ 327$
328</pre> 328</pre>
329 329
330<p> 330<p>
331This ends the walk-through of <c>gdb</c>. Using <c>gdb</c>, we hope that you 331This ends the walk-through of <c>gdb</c>. Using <c>gdb</c>, we hope that you
332will be able to use it to create better bug reports. However, there are other 332will be able to use it to create better bug reports. However, there are other
333types of errors that can cause a program to fail during run time. One of the 333types of errors that can cause a program to fail during run time. One of the
334other ways is through improper file access. We can find those using a nifty 334other ways is through improper file access. We can find those using a nifty
335little tool called <c>strace</c>. 335little tool called <c>strace</c>.
336</p> 336</p>
337 337
338</body> 338</body>
339</section> 339</section>
349Programs often use files to fetch configuration information, access hardware or 349Programs often use files to fetch configuration information, access hardware or
350write logs. Sometimes, a program attempts to reach such files incorrectly. A 350write logs. Sometimes, a program attempts to reach such files incorrectly. A
351tool called <c>strace</c> was created to help deal with this. <c>strace</c> 351tool called <c>strace</c> was created to help deal with this. <c>strace</c>
352traces system calls (hence the name) which include calls that use the memory and 352traces system calls (hence the name) which include calls that use the memory and
353files. For our example, we're going to take a program foobar2. This is an 353files. For our example, we're going to take a program foobar2. This is an
354updated version of foobar. However, during the change over to foobar2, you 354updated version of foobar. However, during the change over to foobar2, you
355notice all your configurations are missing! In foobar version 1, you had it 355notice all your configurations are missing! In foobar version 1, you had it
356setup to say "foo", but now it's using the default "bar". 356setup to say "foo", but now it's using the default "bar".
357</p> 357</p>
358 358
359<pre caption="Foobar2 With an invalid configuration"> 359<pre caption="Foobar2 With an invalid configuration">
360$ <i>./foobar2</i> 360$ <i>./foobar2</i>
395Aha! So There's the problem. Someone moved the configuration directory to 395Aha! So There's the problem. Someone moved the configuration directory to
396<path>.foobar2</path> instead of <path>.foobar</path>. We also see the program 396<path>.foobar2</path> instead of <path>.foobar</path>. We also see the program
397reading in "bar" as it should. In this case, we can recommend the ebuild 397reading in "bar" as it should. In this case, we can recommend the ebuild
398maintainer to put a warning about it. For now though, we can copy over the 398maintainer to put a warning about it. For now though, we can copy over the
399config file from <path>.foobar</path> and modify it to produce the correct 399config file from <path>.foobar</path> and modify it to produce the correct
400results. 400results.
401</p> 401</p>
402 402
403</body> 403</body>
404</section> 404</section>
405<section> 405<section>
406<title>Conclusion</title> 406<title>Conclusion</title>
407<body> 407<body>
408 408
409<p> 409<p>
410<c>strace</c> is a great way at seeing what the kernel is doing to with the 410<c>strace</c> is a great way at seeing what the kernel is doing to with the
411filesystem. Another program exists to help users see what the kernel is doing, 411filesystem. Another program exists to help users see what the kernel is doing,
412and help with kernel debugging. This program is called <c>dmesg</c>. 412and help with kernel debugging. This program is called <c>dmesg</c>.
413</p> 413</p>
414 414
415</body> 415</body>
457hdb: ATAPI 52X CD-ROM CD-R/RW drive, 2048kB Cache, UDMA(33) 457hdb: ATAPI 52X CD-ROM CD-R/RW drive, 2048kB Cache, UDMA(33)
458Uniform CD-ROM driver Revision: 3.20 458Uniform CD-ROM driver Revision: 3.20
459hdc: ATAPI 48X DVD-ROM drive, 512kB Cache, UDMA(33) 459hdc: ATAPI 48X DVD-ROM drive, 512kB Cache, UDMA(33)
460ide-floppy driver 0.99.newide 460ide-floppy driver 0.99.newide
461libata version 1.11 loaded. 461libata version 1.11 loaded.
462usbmon: debugs is not available 462usbmon: debugs is not available
463</pre> 463</pre>
464 464
465<p> 465<p>
466The dmesg displayed here is my machine's bootup. You can see the hard disks and 466The dmesg displayed here is my machine's bootup. You can see the hard disks and
467input devices being initialized. While what you see here seems relatively 467input devices being initialized. While what you see here seems relatively
569!!! Make failed! 569!!! Make failed!
570!!! If you need support, post the topmost build error, NOT this status message 570!!! If you need support, post the topmost build error, NOT this status message
571</pre> 571</pre>
572 572
573<p> 573<p>
574The program is compiling smoothly when it suddenly stops and presents an error 574The program is compiling smoothly when it suddenly stops and presents an error
575message. This particular error can be split into 3 different sections, The 575message. This particular error can be split into 3 different sections, The
576compile messages, the build error, and the emerge error message as shown below. 576compile messages, the build error, and the emerge error message as shown below.
577</p> 577</p>
578 578
579<pre caption="Parts of the error"> 579<pre caption="Parts of the error">
580<comment>(Compilation Messages)</comment> 580<comment>(Compilation Messages)</comment>
626<section> 626<section>
627<title>emerge and PORT_LOGDIR</title> 627<title>emerge and PORT_LOGDIR</title>
628<body> 628<body>
629 629
630<p> 630<p>
631PORT_LOGDIR is a portage variable that sets up a log directory for separate 631PORT_LOGDIR is a portage variable that sets up a log directory for separate
632emerge logs. Let's take a look and see what that entails. First, run your emerge 632emerge logs. Let's take a look and see what that entails. First, run your emerge
633with PORT_LOGDIR set to your favorite log location. Let's say we have a 633with PORT_LOGDIR set to your favorite log location. Let's say we have a
634location <path>/var/log/portage</path>. We'll use that for our log directory: 634location <path>/var/log/portage</path>. We'll use that for our log directory:
635</p> 635</p>
636 636
663you've emerged. This prevents duplicate logs from appearing. A quick look at 663you've emerged. This prevents duplicate logs from appearing. A quick look at
664the log file will show the entire emerge process. This can be attached later 664the log file will show the entire emerge process. This can be attached later
665on as we'll see in the bug reporting section. Now that we've safely obtained 665on as we'll see in the bug reporting section. Now that we've safely obtained
666our information needed to report the bug we can continue to do so. However, 666our information needed to report the bug we can continue to do so. However,
667before we get started on that, we need to make sure no one else has reported 667before we get started on that, we need to make sure no one else has reported
668the issue. 668the issue.
669</p> 669</p>
670 670
671</body> 671</body>
672</section> 672</section>
673</chapter> 673</chapter>

Legend:
Removed from v.1.4  
changed lines
  Added in v.1.5

  ViewVC Help
Powered by ViewVC 1.1.20