@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
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
@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
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
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
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
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
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
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.
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}
@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
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} )
@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
@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
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
@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
@var{secname}, only the @emph{first} sets the start address.
@end table
-
@node Index
@unnumbered Index
projects / binutils-gdb.git / commitdiff