espressif/binutils-gdb
1
0
Fork 0
mirror of https://github.com/espressif/binutils-gdb.git synced 2025-06-05 06:23:58 +08:00
Code Issues Packages Projects Releases Wiki Activity

* ld.texinfo: Add section on reporting bugs.

Browse Source
This commit is contained in:
Ian Lance Taylor
1996-11-01 19:54:52 +00:00
parent 9a5acea834
commit 9fde46a42f
2 changed files with 246 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
ld/ChangeLog
View File

@ -1,5 +1,7 @@
Fri Nov 1 10:01:27 1996 Ian Lance Taylor <ian@cygnus.com>
* ld.texinfo: Add section on reporting bugs.
* scripttempl/m68kcoff.sc: Make sure the etext and __CTOR_LIST__
symbols are correctly aligned.

279
ld/ld.texinfo
View File

@ -109,6 +109,7 @@ This file documents the @sc{gnu} linker ld.
@end ifclear
@c Following blank line required for remaining bug in makeinfo conds/menus
* Reporting Bugs:: Reporting Bugs
* MRI:: MRI Compatible Script Files
* Index:: Index
@end menu
@ -210,7 +211,7 @@ option that requires them.
For options whose names are multiple letters, either one dash or two can
precede the option name; for example, @samp{--oformat} and
@samp{-oformat} are equivalent. Arguments to multiple-letter options
@samp{--oformat} are equivalent. Arguments to multiple-letter options
must either be separated from the option name by an equals sign, or be
given as separate arguments immediately following the option that
requires them. For example, @samp{--oformat srec} and
@ -318,9 +319,9 @@ entry point.
@cindex dynamic symbol table
@kindex -E
@kindex -export-dynamic
@kindex --export-dynamic
@item -E
@itemx -export-dynamic
@itemx --export-dynamic
When creating a dynamically linked executable, add all symbols to the
dynamic symbol table. Normally, the dynamic symbol table contains only
symbols which are used by a dynamic object. This option is needed for
@ -333,7 +334,7 @@ some uses of @code{dlopen}.
Ignored. Some older linkers used this option throughout a compilation
toolchain for specifying object-file format for both input and output
object files. The mechanisms @code{ld} uses for this purpose (the
@samp{-b} or @samp{-format} options for input files, @samp{-oformat}
@samp{-b} or @samp{--format} options for input files, @samp{--oformat}
option or the @code{TARGET} command in linker scripts for output files,
the @code{GNUTARGET} environment variable) are more flexible, but
@code{ld} accepts the @samp{-F} option for compatibility with scripts
@ -714,8 +715,8 @@ Link big-endian objects. This affects the default output format.
Link little-endian objects. This affects the default output format.
@cindex MIPS embedded PIC code
@kindex -embedded-relocs
@item -embedded-relocs
@kindex --embedded-relocs
@item --embedded-relocs
This option is only meaningful when linking MIPS embedded PIC code,
generated by the -membedded-pic option to the @sc{gnu} compiler and
assembler. It causes the linker to create a table which may be used at
@ -758,11 +759,11 @@ errors during the link process; it exits without writing an output file
when it issues any error whatsoever.
@ifclear SingleFormat
@kindex -oformat
@item -oformat @var{output-format}
@kindex --oformat
@item --oformat @var{output-format}
@code{ld} may be configured to support more than one kind of object
file. If your @code{ld} is configured this way, you can use the
@samp{-oformat} option to specify the binary format for the output
@samp{--oformat} option to specify the binary format for the output
object file. Even when @code{ld} is configured to support alternative
object formats, you don't usually need to specify this, as @code{ld}
should be configured to produce as a default output format the most
@ -802,8 +803,8 @@ in the program, such as relaxing address modes and synthesizing new
instructions in the output object file.
@ifset GENERIC
On platforms where this is not supported, @samp{-relax} is accepted, but
ignored.
On platforms where this is not supported, @samp{--relax} is accepted,
but ignored.
@end ifset
@cindex retaining specified symbols
@ -819,10 +820,10 @@ symbol name per line. This option is especially useful in environments
where a large global symbol table is accumulated gradually, to conserve
run-time memory.
@samp{-retain-symbols-file} does @emph{not} discard undefined symbols,
@samp{--retain-symbols-file} does @emph{not} discard undefined symbols,
or symbols needed for relocations.
You may only specify @samp{-retain-symbols-file} once in the command
You may only specify @samp{--retain-symbols-file} once in the command
line. It overrides @samp{-s} and @samp{-S}.
@ifset GENERIC
@ -939,9 +940,9 @@ many relocations.
Compute and display statistics about the operation of the linker, such
as execution time and memory usage.
@kindex -traditional-format
@kindex --traditional-format
@cindex traditional format
@item -traditional-format
@item --traditional-format
For some targets, the output of @code{ld} is different in some ways from
the output of some existing linker. This switch requests @code{ld} to
use the traditional format instead.
@ -951,7 +952,7 @@ For example, on SunOS, @code{ld} combines duplicate entries in the
symbol string table. This can reduce the size of an output file with
full debugging information by over 30 percent. Unfortunately, the SunOS
@code{dbx} program can not read the resulting program (@code{gdb} has no
trouble). The @samp{-traditional-format} switch tells @code{ld} to not
trouble). The @samp{--traditional-format} switch tells @code{ld} to not
combine duplicate entries.
@kindex -Tbss @var{org}
@ -1164,16 +1165,16 @@ variable @code{GNUTARGET}.
@kindex GNUTARGET
@cindex default input format
@code{GNUTARGET} determines the input-file object format if you don't
use @samp{-b} (or its synonym @samp{-format}). Its value should be one
use @samp{-b} (or its synonym @samp{--format}). Its value should be one
of the BFD names for an input format (@pxref{BFD}). If there is no
@code{GNUTARGET} in the environment, @code{ld} uses the natural format
of the target. If @code{GNUTARGET} is set to @code{default} then BFD attempts to discover the
input format by examining binary input files; this method often
succeeds, but there are potential ambiguities, since there is no method
of ensuring that the magic number used to specify object-file formats is
unique. However, the configuration procedure for BFD on each system
places the conventional format for that system first in the search-list,
so ambiguities are resolved in favor of convention.
of the target. If @code{GNUTARGET} is set to @code{default} then BFD
attempts to discover the input format by examining binary input files;
this method often succeeds, but there are potential ambiguities, since
there is no method of ensuring that the magic number used to specify
object-file formats is unique. However, the configuration procedure for
BFD on each system places the conventional format for that system first
in the search-list, so ambiguities are resolved in favor of convention.
@end ifset
@node Commands
@ -2822,9 +2823,9 @@ When @code{ld} is configured to support multiple object code formats,
you can use this command to specify a particular output format.
@var{bfdname} is one of the names used by the BFD back-end routines
(@pxref{BFD}). The effect is identical to the effect of the
@samp{-oformat} command-line option. This selection affects only
the output file; the related command @code{TARGET} affects primarily
input files.
@samp{--oformat} command-line option. This selection affects only the
output file; the related command @code{TARGET} affects primarily input
files.
@end ifclear
@kindex SEARCH_DIR ( @var{path} )
@ -2847,7 +2848,7 @@ process.
@item TARGET ( @var{format} )
When @code{ld} is configured to support multiple object code formats,
you can use this command to change the input-file object code format
(like the command-line option @samp{-b} or its synonym @samp{-format}).
(like the command-line option @samp{-b} or its synonym @samp{--format}).
The argument @var{format} is one of the strings used by BFD to name
binary formats. If @code{TARGET} is specified but @code{OUTPUT_FORMAT}
is not, the last @code{TARGET} argument is also used as the default
@ -2905,7 +2906,7 @@ functionality are not listed.
@cindex H8/300 support
For the H8/300, @code{ld} can perform these global optimizations when
you specify the @samp{-relax} command-line option.
you specify the @samp{--relax} command-line option.
@table @emph
@cindex relaxing on H8/300
@ -2983,12 +2984,12 @@ the 960 architecture family allows combination of target architectures; each
use will add another pair of name variants to search for when @w{@samp{-l}}
specifies a library.
@cindex @code{-relax} on i960
@cindex @code{--relax} on i960
@cindex relaxing on i960
@code{ld} supports the @samp{-relax} option for the i960 family. If you
specify @samp{-relax}, @code{ld} finds all @code{balx} and @code{calx}
instructions whose targets are within 24 bits, and turns them into
24-bit program-counter relative @code{bal} and @code{cal}
@code{ld} supports the @samp{--relax} option for the i960 family. If
you specify @samp{--relax}, @code{ld} finds all @code{balx} and
@code{calx} instructions whose targets are within 24 bits, and turns
them into 24-bit program-counter relative @code{bal} and @code{cal}
instructions, respectively. @code{ld} also turns @code{cal}
instructions into @code{bal} instructions when it determines that the
target subroutine is a leaf routine (that is, the target subroutine does
@ -3042,6 +3043,215 @@ conversion and during output. @xref{BFD information loss}.
@include bfdsumm.texi
@end ifclear
@node Reporting Bugs
@chapter Reporting Bugs
@cindex bugs in @code{ld}
@cindex reporting bugs in @code{ld}
Your bug reports play an essential role in making @code{ld} reliable.
Reporting a bug may help you by bringing a solution to your problem, or
it may not. But in any case the principal function of a bug report is
to help the entire community by making the next version of @code{ld}
work better. Bug reports are your contribution to the maintenance of
@code{ld}.
In order for a bug report to serve its purpose, you must include the
information that enables us to fix the bug.
@menu
* Bug Criteria:: Have you found a bug?
* Bug Reporting:: How to report bugs
@end menu
@node Bug Criteria
@section Have you found a bug?
@cindex bug criteria
If you are not sure whether you have found a bug, here are some guidelines:
@itemize @bullet
@cindex fatal signal
@cindex linker crash
@cindex crash of linker
@item
If the linker gets a fatal signal, for any input whatever, that is a
@code{ld} bug. Reliable linkers never crash.
@cindex error on valid input
@item
If @code{ld} produces an error message for valid input, that is a bug.
@cindex invalid input
@item
If @code{ld} does not produce an error message for invalid input, that
may be a bug. In the general case, the linker can not verify that
object files are correct.
@item
If you are an experienced user of linkers, your suggestions for
improvement of @code{ld} are welcome in any case.
@end itemize
@node Bug Reporting
@section How to report bugs
@cindex bug reports
@cindex @code{ld} bugs, reporting
A number of companies and individuals offer support for @sc{gnu}
products. If you obtained @code{ld} from a support organization, we
recommend you contact that organization first.
You can find contact information for many support companies and
individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
distribution.
In any event, we also recommend that you send bug reports for @code{ld}
to @samp{bug-gnu-utils@@prep.ai.mit.edu}.
The fundamental principle of reporting bugs usefully is this:
@strong{report all the facts}. If you are not sure whether to state a
fact or leave it out, state it!
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 a symbol 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 linker 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.
Keep in mind that the purpose of a bug report is to enable us to fix the bug if
it is new to us. Therefore, always write your bug reports on the assumption
that the bug has not been reported previously.
Sometimes people give a few sketchy facts and ask, ``Does this ring a
bell?'' Those bug reports are useless, and we urge everyone to
@emph{refuse to respond to them} except to chide the sender to report
bugs properly.
To enable us to fix the bug, you should include all these things:
@itemize @bullet
@item
The version of @code{ld}. @code{ld} announces it if you start it with
the @samp{--version} argument.
Without this, we will not know whether there is any point in looking for
the bug in the current version of @code{ld}.
@item
Any patches you may have applied to the @code{ld} source, including any
patches made to the @code{BFD} library.
@item
The type of machine you are using, and the operating system name and
version number.
@item
What compiler (and its version) was used to compile @code{ld}---e.g.
``@code{gcc-2.7}''.
@item
The command arguments you gave the linker to link your example and
observe the bug. To guarantee you will not omit something important,
list them all. A copy of the Makefile (or the output from make) is
sufficient.
If we were to try to guess the arguments, we would probably guess wrong
and then we might not encounter the bug.
@item
A complete input file, or set of input files, that will reproduce the
bug. It is generally most helpful to send the actual object files,
uuencoded if necessary to get them through the mail system. Making them
available for anonymous FTP is not as good, but may be the only
reasonable choice for large object files.
If the source files were assembled using @code{gas} or compiled using
@code{gcc}, then it may be OK to send the source files rather than the
object files. In this case, be sure to say exactly what version of
@code{gas} or @code{gcc} was used to produce the object files. Also say
how @code{gas} or @code{gcc} were configured.
@item
A description of what behavior you observe that you believe is
incorrect. For example, ``It gets a fatal signal.''
Of course, if the bug is that @code{ld} 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.
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 @code{ld} 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.
@item
If you wish to suggest changes to the @code{ld} source, send us context
diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or
@samp{-p} option. Always send diffs from the old file to the new file.
If you even discuss something in the @code{ld} source, refer to it by
context, not by line number.
The line numbers in our development sources will not match those in your
sources. Your line numbers would convey no useful information to us.
@end itemize
Here are some things that are not necessary:
@itemize @bullet
@item
A description of the envelope of the bug.
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.
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.
Of course, if you can find a simpler example to report @emph{instead}
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.
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.
@item
A patch for the bug.
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.
Sometimes with a program as complicated as @code{@value{AS}} 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.
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.
@item
A guess about what the bug is or what it depends on.
Such guesses are usually wrong. Even we cannot guess right about such
things without first using the debugger to find the facts.
@end itemize
@node MRI
@appendix MRI Compatible Script Files
@cindex MRI compatibility
@ -3175,7 +3385,6 @@ If you have more than one @code{SECT} statement for the same
@var{secname}, only the @emph{first} sets the start address.
@end table
@node Index
@unnumbered Index