diff options
| -rw-r--r-- | ld/ChangeLog | 2 | ||||
| -rw-r--r-- | ld/ld.texinfo | 279 |
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 |