ld: Bug Reporting
1
1 6.2 How to Report Bugs
1 ======================
1
1 A number of companies and individuals offer support for GNU products.
1 If you obtained 'ld' from a support organization, we recommend you
1 contact that organization first.
1
1 You can find contact information for many support companies and
1 individuals in the file 'etc/SERVICE' in the GNU Emacs distribution.
1
1 Otherwise, send bug reports for 'ld' to
1 <http://www.sourceware.org/bugzilla/>.
1
1 The fundamental principle of reporting bugs usefully is this: *report
1 all the facts*. If you are not sure whether to state a fact or leave it
1 out, state it!
1
1 Often people omit facts because they think they know what causes the
1 problem and assume that some details do not matter. Thus, you might
1 assume that the name of a symbol you use in an example does not matter.
1 Well, probably it does not, but one cannot be sure. Perhaps the bug is
1 a stray memory reference which happens to fetch from the location where
1 that name is stored in memory; perhaps, if the name were different, the
1 contents of that location would fool the linker into doing the right
1 thing despite the bug. Play it safe and give a specific, complete
1 example. That is the easiest thing for you to do, and the most helpful.
1
1 Keep in mind that the purpose of a bug report is to enable us to fix
1 the bug if it is new to us. Therefore, always write your bug reports on
1 the assumption that the bug has not been reported previously.
1
1 Sometimes people give a few sketchy facts and ask, "Does this ring a
1 bell?" This cannot help us fix a bug, so it is basically useless. We
1 respond by asking for enough details to enable us to investigate. You
1 might as well expedite matters by sending them to begin with.
1
1 To enable us to fix the bug, you should include all these things:
1
1 * The version of 'ld'. 'ld' announces it if you start it with the
1 '--version' argument.
1
1 Without this, we will not know whether there is any point in
1 looking for the bug in the current version of 'ld'.
1
1 * Any patches you may have applied to the 'ld' source, including any
1 patches made to the 'BFD' library.
1
1 * The type of machine you are using, and the operating system name
1 and version number.
1
1 * What compiler (and its version) was used to compile 'ld'--e.g.
1 "'gcc-2.7'".
1
1 * The command arguments you gave the linker to link your example and
1 observe the bug. To guarantee you will not omit something
1 important, list them all. A copy of the Makefile (or the output
1 from make) is sufficient.
1
1 If we were to try to guess the arguments, we would probably guess
1 wrong and then we might not encounter the bug.
1
1 * A complete input file, or set of input files, that will reproduce
1 the bug. It is generally most helpful to send the actual object
1 files provided that they are reasonably small. Say no more than
1 10K. For bigger files you can either make them available by FTP or
1 HTTP or else state that you are willing to send the object file(s)
1 to whomever requests them. (Note - your email will be going to a
1 mailing list, so we do not want to clog it up with large
1 attachments). But small attachments are best.
1
1 If the source files were assembled using 'gas' or compiled using
1 'gcc', then it may be OK to send the source files rather than the
1 object files. In this case, be sure to say exactly what version of
1 'gas' or 'gcc' was used to produce the object files. Also say how
1 'gas' or 'gcc' were configured.
1
1 * A description of what behavior you observe that you believe is
1 incorrect. For example, "It gets a fatal signal."
1
1 Of course, if the bug is that 'ld' gets a fatal signal, then we
1 will certainly notice it. But if the bug is incorrect output, we
1 might not notice unless it is glaringly wrong. You might as well
1 not give us a chance to make a mistake.
1
1 Even if the problem you experience is a fatal signal, you should
1 still say so explicitly. Suppose something strange is going on,
1 such as, your copy of 'ld' is out of sync, or you have encountered
1 a bug in the C library on your system. (This has happened!) Your
1 copy might crash and ours would not. If you told us to expect a
1 crash, then when ours fails to crash, we would know that the bug
1 was not happening for us. If you had not told us to expect a
1 crash, then we would not be able to draw any conclusion from our
1 observations.
1
1 * If you wish to suggest changes to the 'ld' source, send us context
1 diffs, as generated by 'diff' with the '-u', '-c', or '-p' option.
1 Always send diffs from the old file to the new file. If you even
1 discuss something in the 'ld' source, refer to it by context, not
1 by line number.
1
1 The line numbers in our development sources will not match those in
1 your sources. Your line numbers would convey no useful information
1 to us.
1
1 Here are some things that are not necessary:
1
1 * A description of the envelope of the bug.
1
1 Often people who encounter a bug spend a lot of time investigating
1 which changes to the input file will make the bug go away and which
1 changes will not affect it.
1
1 This is often time consuming and not very useful, because the way
1 we will find the bug is by running a single example under the
1 debugger with breakpoints, not by pure deduction from a series of
1 examples. We recommend that you save your time for something else.
1
1 Of course, if you can find a simpler example to report _instead_ of
1 the original one, that is a convenience for us. Errors in the
1 output will be easier to spot, running under the debugger will take
1 less time, and so on.
1
1 However, simplification is not vital; if you do not want to do
1 this, report the bug anyway and send us the entire test case you
1 used.
1
1 * A patch for the bug.
1
1 A patch for the bug does help us if it is a good one. But do not
1 omit the necessary information, such as the test case, on the
1 assumption that a patch is all we need. We might see problems with
1 your patch and decide to fix the problem another way, or we might
1 not understand it at all.
1
1 Sometimes with a program as complicated as 'ld' it is very hard to
1 construct an example that will make the program follow a certain
1 path through the code. If you do not send us the example, we will
1 not be able to construct one, so we will not be able to verify that
1 the bug is fixed.
1
1 And if we cannot understand what bug you are trying to fix, or why
1 your patch should be an improvement, we will not install it. A
1 test case will help us to understand.
1
1 * A guess about what the bug is or what it depends on.
1
1 Such guesses are usually wrong. Even we cannot guess right about
1 such things without first using the debugger to find the facts.
1