214 lines
10 KiB
HTML
214 lines
10 KiB
HTML
|
<html lang="en">
|
||
|
|
<head>
|
||
|
|
<title>Bug Reporting - Debugging with GDB</title>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html">
|
||
|
|
<meta name="description" content="Debugging with GDB">
|
||
|
|
<meta name="generator" content="makeinfo 4.13">
|
||
|
|
<link title="Top" rel="start" href="index.html#Top">
|
||
|
|
<link rel="up" href="GDB-Bugs.html#GDB-Bugs" title="GDB Bugs">
|
||
|
|
<link rel="prev" href="Bug-Criteria.html#Bug-Criteria" title="Bug Criteria">
|
||
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
||
|
|
<!--
|
||
|
|
Copyright (C) 1988-2019 Free Software Foundation, Inc.
|
||
|
|
|
||
|
|
Permission is granted to copy, distribute and/or modify this document
|
||
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
||
|
|
any later version published by the Free Software Foundation; with the
|
||
|
|
Invariant Sections being ``Free Software'' and ``Free Software Needs
|
||
|
|
Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,''
|
||
|
|
and with the Back-Cover Texts as in (a) below.
|
||
|
|
|
||
|
|
(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
|
||
|
|
this GNU Manual. Buying copies from GNU Press supports the FSF in
|
||
|
|
developing GNU and promoting software freedom.''
|
||
|
|
-->
|
||
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
||
|
|
<style type="text/css"><!--
|
||
|
|
pre.display { font-family:inherit }
|
||
|
|
pre.format { font-family:inherit }
|
||
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
||
|
|
pre.smallexample { font-size:smaller }
|
||
|
|
pre.smalllisp { font-size:smaller }
|
||
|
|
span.sc { font-variant:small-caps }
|
||
|
|
span.roman { font-family:serif; font-weight:normal; }
|
||
|
|
span.sansserif { font-family:sans-serif; font-weight:normal; }
|
||
|
|
--></style>
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div class="node">
|
||
|
|
<a name="Bug-Reporting"></a>
|
||
|
|
<p>
|
||
|
|
Previous: <a rel="previous" accesskey="p" href="Bug-Criteria.html#Bug-Criteria">Bug Criteria</a>,
|
||
|
|
Up: <a rel="up" accesskey="u" href="GDB-Bugs.html#GDB-Bugs">GDB Bugs</a>
|
||
|
|
<hr>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<h3 class="section">31.2 How to Report Bugs</h3>
|
||
|
|
|
||
|
|
<p><a name="index-bug-reports-3176"></a><a name="index-g_t_0040value_007bGDBN_007d-bugs_002c-reporting-3177"></a>
|
||
|
|
A number of companies and individuals offer support for <span class="sc">gnu</span> products.
|
||
|
|
If you obtained <span class="sc">gdb</span> from a support organization, we recommend you
|
||
|
|
contact that organization first.
|
||
|
|
|
||
|
|
<p>You can find contact information for many support companies and
|
||
|
|
individuals in the file <samp><span class="file">etc/SERVICE</span></samp> in the <span class="sc">gnu</span> Emacs
|
||
|
|
distribution.
|
||
|
|
<!-- should add a web page ref... -->
|
||
|
|
|
||
|
|
<p>In any event, we also recommend that you submit bug reports for
|
||
|
|
<span class="sc">gdb</span> to <a href="https://bugs.linaro.org/">https://bugs.linaro.org/</a>.
|
||
|
|
|
||
|
|
<p>The fundamental principle of reporting bugs usefully is this:
|
||
|
|
<strong>report all the facts</strong>. If you are not sure whether to state a
|
||
|
|
fact or leave it out, state it!
|
||
|
|
|
||
|
|
<p>Often people omit facts because they think they know what causes the
|
||
|
|
problem and assume that some details do not matter. Thus, you might
|
||
|
|
assume that the name of the variable you use in an example does not matter.
|
||
|
|
Well, probably it does not, but one cannot be sure. Perhaps the bug is a
|
||
|
|
stray memory reference which happens to fetch from the location where that
|
||
|
|
name is stored in memory; perhaps, if the name were different, the contents
|
||
|
|
of that location would fool the debugger into doing the right thing despite
|
||
|
|
the bug. Play it safe and give a specific, complete example. That is the
|
||
|
|
easiest thing for you to do, and the most helpful.
|
||
|
|
|
||
|
|
<p>Keep in mind that the purpose of a bug report is to enable us to fix the
|
||
|
|
bug. It may be that the bug has been reported previously, but neither
|
||
|
|
you nor we can know that unless your bug report is complete and
|
||
|
|
self-contained.
|
||
|
|
|
||
|
|
<p>Sometimes people give a few sketchy facts and ask, “Does this ring a
|
||
|
|
bell?” Those bug reports are useless, and we urge everyone to
|
||
|
|
<em>refuse to respond to them</em> except to chide the sender to report
|
||
|
|
bugs properly.
|
||
|
|
|
||
|
|
<p>To enable us to fix the bug, you should include all these things:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The version of <span class="sc">gdb</span>. <span class="sc">gdb</span> announces it if you start
|
||
|
|
with no arguments; you can also print it at any time using <code>show
|
||
|
|
version</code>.
|
||
|
|
|
||
|
|
<p>Without this, we will not know whether there is any point in looking for
|
||
|
|
the bug in the current version of <span class="sc">gdb</span>.
|
||
|
|
|
||
|
|
<li>The type of machine you are using, and the operating system name and
|
||
|
|
version number.
|
||
|
|
|
||
|
|
<li>The details of the <span class="sc">gdb</span> build-time configuration.
|
||
|
|
<span class="sc">gdb</span> shows these details if you invoke it with the
|
||
|
|
<samp><span class="option">--configuration</span></samp> command-line option, or if you type
|
||
|
|
<code>show configuration</code> at <span class="sc">gdb</span>'s prompt.
|
||
|
|
|
||
|
|
<li>What compiler (and its version) was used to compile <span class="sc">gdb</span>—e.g.
|
||
|
|
“gcc–2.8.1”.
|
||
|
|
|
||
|
|
<li>What compiler (and its version) was used to compile the program you are
|
||
|
|
debugging—e.g. “gcc–2.8.1”, or “HP92453-01 A.10.32.03 HP
|
||
|
|
C Compiler”. For <span class="sc">gcc</span>, you can say <kbd>gcc --version</kbd>
|
||
|
|
to get this information; for other compilers, see the documentation for
|
||
|
|
those compilers.
|
||
|
|
|
||
|
|
<li>The command arguments you gave the compiler to compile your example and
|
||
|
|
observe the bug. For example, did you use ‘<samp><span class="samp">-O</span></samp>’? To guarantee
|
||
|
|
you will not omit something important, list them all. A copy of the
|
||
|
|
Makefile (or the output from make) is sufficient.
|
||
|
|
|
||
|
|
<p>If we were to try to guess the arguments, we would probably guess wrong
|
||
|
|
and then we might not encounter the bug.
|
||
|
|
|
||
|
|
<li>A complete input script, and all necessary source files, that will
|
||
|
|
reproduce the bug.
|
||
|
|
|
||
|
|
<li>A description of what behavior you observe that you believe is
|
||
|
|
incorrect. For example, “It gets a fatal signal.”
|
||
|
|
|
||
|
|
<p>Of course, if the bug is that <span class="sc">gdb</span> gets a fatal signal, then we
|
||
|
|
will certainly notice it. But if the bug is incorrect output, we might
|
||
|
|
not notice unless it is glaringly wrong. You might as well not give us
|
||
|
|
a chance to make a mistake.
|
||
|
|
|
||
|
|
<p>Even if the problem you experience is a fatal signal, you should still
|
||
|
|
say so explicitly. Suppose something strange is going on, such as, your
|
||
|
|
copy of <span class="sc">gdb</span> is out of synch, or you have encountered a bug in
|
||
|
|
the C library on your system. (This has happened!) Your copy might
|
||
|
|
crash and ours would not. If you told us to expect a crash, then when
|
||
|
|
ours fails to crash, we would know that the bug was not happening for
|
||
|
|
us. If you had not told us to expect a crash, then we would not be able
|
||
|
|
to draw any conclusion from our observations.
|
||
|
|
|
||
|
|
<p><a name="index-script-3178"></a><a name="index-recording-a-session-script-3179"></a>To collect all this information, you can use a session recording program
|
||
|
|
such as <samp><span class="command">script</span></samp>, which is available on many Unix systems.
|
||
|
|
Just run your <span class="sc">gdb</span> session inside <samp><span class="command">script</span></samp> and then
|
||
|
|
include the <samp><span class="file">typescript</span></samp> file with your bug report.
|
||
|
|
|
||
|
|
<p>Another way to record a <span class="sc">gdb</span> session is to run <span class="sc">gdb</span>
|
||
|
|
inside Emacs and then save the entire buffer to a file.
|
||
|
|
|
||
|
|
<li>If you wish to suggest changes to the <span class="sc">gdb</span> source, send us context
|
||
|
|
diffs. If you even discuss something in the <span class="sc">gdb</span> source, refer to
|
||
|
|
it by context, not by line number.
|
||
|
|
|
||
|
|
<p>The line numbers in our development sources will not match those in your
|
||
|
|
sources. Your line numbers would convey no useful information to us.
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>Here are some things that are not necessary:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>A description of the envelope of the bug.
|
||
|
|
|
||
|
|
<p>Often people who encounter a bug spend a lot of time investigating
|
||
|
|
which changes to the input file will make the bug go away and which
|
||
|
|
changes will not affect it.
|
||
|
|
|
||
|
|
<p>This is often time consuming and not very useful, because the way we
|
||
|
|
will find the bug is by running a single example under the debugger
|
||
|
|
with breakpoints, not by pure deduction from a series of examples.
|
||
|
|
We recommend that you save your time for something else.
|
||
|
|
|
||
|
|
<p>Of course, if you can find a simpler example to report <em>instead</em>
|
||
|
|
of the original one, that is a convenience for us. Errors in the
|
||
|
|
output will be easier to spot, running under the debugger will take
|
||
|
|
less time, and so on.
|
||
|
|
|
||
|
|
<p>However, simplification is not vital; if you do not want to do this,
|
||
|
|
report the bug anyway and send us the entire test case you used.
|
||
|
|
|
||
|
|
<li>A patch for the bug.
|
||
|
|
|
||
|
|
<p>A patch for the bug does help us if it is a good one. But do not omit
|
||
|
|
the necessary information, such as the test case, on the assumption that
|
||
|
|
a patch is all we need. We might see problems with your patch and decide
|
||
|
|
to fix the problem another way, or we might not understand it at all.
|
||
|
|
|
||
|
|
<p>Sometimes with a program as complicated as <span class="sc">gdb</span> it is very hard to
|
||
|
|
construct an example that will make the program follow a certain path
|
||
|
|
through the code. If you do not send us the example, we will not be able
|
||
|
|
to construct one, so we will not be able to verify that the bug is fixed.
|
||
|
|
|
||
|
|
<p>And if we cannot understand what bug you are trying to fix, or why your
|
||
|
|
patch should be an improvement, we will not install it. A test case will
|
||
|
|
help us to understand.
|
||
|
|
|
||
|
|
<li>A guess about what the bug is or what it depends on.
|
||
|
|
|
||
|
|
<p>Such guesses are usually wrong. Even we cannot guess right about such
|
||
|
|
things without first using the debugger to find the facts.
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<!-- The readline documentation is distributed with the readline code -->
|
||
|
|
<!-- and consists of the two following files: -->
|
||
|
|
<!-- rluser.texi -->
|
||
|
|
<!-- hsuser.texi -->
|
||
|
|
<!-- Use -I with makeinfo to point to the appropriate directory, -->
|
||
|
|
<!-- environment var TEXINPUTS with TeX. -->
|
||
|
|
<!-- %**start of header (This is for running Texinfo on a region.) -->
|
||
|
|
<!-- %**end of header (This is for running Texinfo on a region.) -->
|
||
|
|
<!-- If you are including this manual as an appendix, then set the -->
|
||
|
|
<!-- variable readline-appendix. -->
|
||
|
|
</body></html>
|
||
|
|
|