* ld.texinfo: Add section on reporting bugs.

2 files changed, 246 insertions, 35 deletions

diff --git a/ld/ChangeLog b/ld/ChangeLog
index 90924fa..504eb8a 100644
--- a/ld/ChangeLog
+++ b/ld/ChangeLog
@@ -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.
 
diff --git a/ld/ld.texinfo b/ld/ld.texinfo
index 9e086d9..b532195 100644
--- a/ld/ld.texinfo
+++ b/ld/ld.texinfo
@@ -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