source: trunk/src/binutils/ld/ld.info-5@ 1036

This is ld.info, produced by makeinfo version 4.3 from ./ld.texinfo.

START-INFO-DIR-ENTRY
* Ld: (ld).                       The GNU linker.
END-INFO-DIR-ENTRY

   This file documents the GNU linker LD version 2.14.

   Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
2002, 2003 Free Software Foundation, Inc.


File: ld.info,  Node: WIN32,  Next: Xtensa,  Prev: TI COFF,  Up: Machine Dependent

`ld' and WIN32 (cygwin/mingw)
=============================

   This section describes some of the win32 specific `ld' issues.  See
*Note Command Line Options: Options for detailed decription of the
command line options mentioned here.

_import libraries_
     The standard Windows linker creates and uses so-called import
     libraries, which contains information for linking to dll's.  They
     are regular static archives and are handled as any other static
     archive.  The cygwin and mingw ports of `ld' have specific support
     for creating such libraries provided with the `--out-implib'
     command line option.

_exporting DLL symbols_
     The cygwin/mingw `ld' has several ways to export symbols for dll's.

    _using auto-export functionality_
          By default `ld' exports symbols with the auto-export
          functionality, which is controlled by the following command
          line options:

             * -export-all-symbols   [This is the default]

             * -exclude-symbols

             * -exclude-libs

          If, however, `--export-all-symbols' is not given explicitly
          on the command line, then the default auto-export behavior
          will be _disabled_ if either of the following are true:

             * A DEF file is used.

             * Any symbol in any object file was marked with the
               __declspec(dllexport) attribute.

    _using a DEF file_
          Another way of exporting symbols is using a DEF file.  A DEF
          file is an ASCII file containing definitions of symbols which
          should be exported when a dll is created.  Usually it is
          named `<dll name>.def' and is added as any other object file
          to the linker's command line.  The file's name must end in
          `.def' or `.DEF'.

               gcc -o <output> <objectfiles> <dll name>.def

          Using a DEF file turns off the normal auto-export behavior,
          unless the `--export-all-symbols' option is also used.

          Here is an example of a DEF file for a shared library called
          `xyz.dll':

               LIBRARY "xyz.dll" BASE=0x10000000
               
               EXPORTS
               foo
               bar
               _bar = bar

          This example defines a base address and three symbols.  The
          third symbol is an alias for the second.  For the complete
          format specification see ld/deffilep.y in the binutils
          sources.

          While linking a shared dll, `ld' is able to create a DEF file
          with the `--output-def <file>' command line option.

    _Using decorations_
          Another way of marking symbols for export is to modify the
          source code itself, so that when building the DLL each symbol
          to be exported is declared as:

               __declspec(dllexport) int a_variable
               __declspec(dllexport) void a_function(int with_args)

          All such symbols will be exported from the DLL.  If, however,
          any of the object files in the DLL contain symbols decorated
          in this way, then the normal auto-export behavior is
          disabled, unless the `--export-all-symbols' option is also
          used.

          Note that object files that wish to access these symbols must
          _not_ decorate them with dllexport.  Instead, they should use
          dllimport, instead:

               __declspec(dllimport) int a_variable
               __declspec(dllimport) void a_function(int with_args)

          This complicates the structure of library header files,
          because when included by the library itself the header must
          declare the variables and functions as dllexport, but when
          included by client code the header must declare them as
          dllimport.  There are a number of idioms that are typically
          used to do this; often client code can omit the __declspec()
          declaration completely.  See `--enable-auto-import' and
          `automatic data imports' for more imformation.

_automatic data imports_
     The standard Windows dll format supports data imports from dlls
     only by adding special decorations (dllimport/dllexport), which
     let the compiler produce specific assembler instructions to deal
     with this issue.  This increases the effort necessary to port
     existing Un*x code to these platforms, especially for large c++
     libraries and applications.  The auto-import feature, which was
     initially provided by Paul Sokolovsky, allows one to omit the
     decorations to archieve a behavior that conforms to that on
     POSIX/Un*x platforms. This feature is enabled with the
     `--enable-auto-import' command-line option, although it is enabled
     by default on cygwin/mingw.  The `--enable-auto-import' option
     itself now serves mainly to suppress any warnings that are
     ordinarily emitted when linked objects trigger the feature's use.

     auto-import of variables does not always work flawlessly without
     additional assistance.  Sometimes, you will see this message

     "variable '<var>' can't be auto-imported. Please read the
     documentation for ld's `--enable-auto-import' for details."

     The `--enable-auto-import' documentation explains why this error
     occurs, and several methods that can be used to overcome this
     difficulty.  One of these methods is the _runtime pseudo-relocs_
     feature, described below.

     For complex variables imported from DLLs (such as structs or
     classes), object files typically contain a base address for the
     variable and an offset (_addend_) within the variable-to specify a
     particular field or public member, for instance.  Unfortunately,
     the runtime loader used in win32 environments is incapable of
     fixing these references at runtime without the additional
     information supplied by dllimport/dllexport decorations.  The
     standard auto-import feature described above is unable to resolve
     these references.

     The `--enable-runtime-pseudo-relocs' switch allows these
     references to be resolved without error, while leaving the task of
     adjusting the references themselves (with their non-zero addends)
     to specialized code provided by the runtime environment.  Recent
     versions of the cygwin and mingw environments and compilers
     provide this runtime support; older versions do not.  However, the
     support is only necessary on the developer's platform; the
     compiled result will run without error on an older system.

     `--enable-runtime-pseudo-relocs' is not the default; it must be
     explicitly enabled as needed.

_direct linking to a dll_
     The cygwin/mingw ports of `ld' support the direct linking,
     including data symbols, to a dll without the usage of any import
     libraries.  This is much faster and uses much less memory than
     does the traditional import library method, expecially when
     linking large libraries or applications.  When `ld' creates an
     import lib, each function or variable exported from the dll is
     stored in its own bfd, even though a single bfd could contain many
     exports.  The overhead involved in storing, loading, and
     processing so many bfd's is quite large, and explains the
     tremendous time, memory, and storage needed to link against
     particularly large or complex libraries when using import libs.

     Linking directly to a dll uses no extra command-line switches
     other than `-L' and `-l', because `ld' already searches for a
     number of names to match each library.  All that is needed from
     the developer's perspective is an understanding of this search, in
     order to force ld to select the dll instead of an import library.

     For instance, when ld is called with the argument `-lxxx' it will
     attempt to find, in the first directory of its search path,

          libxxx.dll.a
          xxx.dll.a
          libxxx.a
          cygxxx.dll (*)
          libxxx.dll
          xxx.dll

     before moving on to the next directory in the search path.

     (*) Actually, this is not `cygxxx.dll' but in fact is
     `<prefix>xxx.dll', where `<prefix>' is set by the `ld' option
     `--dll-search-prefix=<prefix>'. In the case of cygwin, the
     standard gcc spec file includes `--dll-search-prefix=cyg', so in
     effect we actually search for `cygxxx.dll'.

     Other win32-based unix environments, such as mingw or pw32, may
     use other `<prefix>'es, although at present only cygwin makes use
     of this feature.  It was originally intended to help avoid name
     conflicts among dll's built for the various win32/un*x
     environments, so that (for example) two versions of a zlib dll
     could coexist on the same machine.

     The generic cygwin/mingw path layout uses a `bin' directory for
     applications and dll's and a `lib' directory for the import
     libraries (using cygwin nomenclature):

          bin/
                cygxxx.dll
          lib/
                libxxx.dll.a   (in case of dll's)
                libxxx.a       (in case of static archive)

     Linking directly to a dll without using the import library can be
     done two ways:

     1. Use the dll directly by adding the `bin' path to the link line
          gcc -Wl,-verbose  -o a.exe -L../bin/ -lxxx

     However, as the dll's often have version numbers appended to their
     names (`cygncurses-5.dll') this will often fail, unless one
     specifies `-L../bin -lncurses-5' to include the version.  Import
     libs are generally not versioned, and do not have this difficulty.

     2. Create a symbolic link from the dll to a file in the `lib'
     directory according to the above mentioned search pattern.  This
     should be used to avoid unwanted changes in the tools needed for
     making the app/dll.

          ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]

     Then you can link without any make environment changes.

          gcc -Wl,-verbose  -o a.exe -L../lib/ -lxxx

     This technique also avoids the version number problems, because
     the following is perfectly legal

          bin/
                cygxxx-5.dll
          lib/
                libxxx.dll.a -> ../bin/cygxxx-5.dll

     Linking directly to a dll without using an import lib will work
     even when auto-import features are exercised, and even when
     `--enable-runtime-pseudo-relocs' is used.

     Given the improvements in speed and memory usage, one might
     justifiably wonder why import libraries are used at all.  There
     are two reasons:

     1. Until recently, the link-directly-to-dll functionality did _not_
     work with auto-imported data.

     2. Sometimes it is necessary to include pure static objects within
     the import library (which otherwise contains only bfd's for
     indirection symbols that point to the exports of a dll).  Again,
     the import lib for the cygwin kernel makes use of this ability,
     and it is not possible to do this without an import lib.

     So, import libs are not going away.  But the ability to replace
     true import libs with a simple symbolic link to (or a copy of) a
     dll, in most cases, is a useful addition to the suite of tools
     binutils makes available to the win32 developer.  Given the
     massive improvements in memory requirements during linking, storage
     requirements, and linking speed, we expect that many developers
     will soon begin to use this feature whenever possible.

_symbol aliasing_

    _adding additional names_
          Sometimes, it is useful to export symbols with additional
          names.  A symbol `foo' will be exported as `foo', but it can
          also be exported as `_foo' by using special directives in the
          DEF file when creating the dll.  This will affect also the
          optional created import library.  Consider the following DEF
          file:

               LIBRARY "xyz.dll" BASE=0x61000000
               
               EXPORTS
               foo
               _foo = foo

          The line `_foo = foo' maps the symbol `foo' to `_foo'.

          Another method for creating a symbol alias is to create it in
          the source code using the "weak" attribute:

               void foo () { /* Do something.  */; }
               void _foo () __attribute__ ((weak, alias ("foo")));

          See the gcc manual for more information about attributes and
          weak symbols.

    _renaming symbols_
          Sometimes it is useful to rename exports.  For instance, the
          cygwin kernel does this regularly.  A symbol `_foo' can be
          exported as `foo' but not as `_foo' by using special
          directives in the DEF file. (This will also affect the import
          library, if it is created).  In the following example:

               LIBRARY "xyz.dll" BASE=0x61000000
               
               EXPORTS
               _foo = foo

          The line `_foo = foo' maps the exported symbol `foo' to
          `_foo'.

     Note: using a DEF file disables the default auto-export behavior,
     unless the `--export-all-symbols' command line option is used.
     If, however, you are trying to rename symbols, then you should list
     _all_ desired exports in the DEF file, including the symbols that
     are not being renamed, and do _not_ use the `--export-all-symbols'
     option.  If you list only the renamed symbols in the DEF file, and
     use `--export-all-symbols' to handle the other symbols, then the
     both the new names _and_ the original names for the the renamed
     symbols will be exported.  In effect, you'd be aliasing those
     symbols, not renaming them, which is probably not what you wanted.


File: ld.info,  Node: Xtensa,  Prev: WIN32,  Up: Machine Dependent

`ld' and Xtensa Processors
==========================

   The default `ld' behavior for Xtensa processors is to interpret
`SECTIONS' commands so that lists of explicitly named sections in a
specification with a wildcard file will be interleaved when necessary to
keep literal pools within the range of PC-relative load offsets.  For
example, with the command:

     SECTIONS
     {
       .text : {
         *(.literal .text)
       }
     }

`ld' may interleave some of the `.literal' and `.text' sections from
different object files to ensure that the literal pools are within the
range of PC-relative load offsets.  A valid interleaving might place
the `.literal' sections from an initial group of files followed by the
`.text' sections of that group of files.  Then, the `.literal' sections
from the rest of the files and the `.text' sections from the rest of
the files would follow.  The non-interleaved order can still be
specified as:

     SECTIONS
     {
       .text : {
         *(.literal) *(.text)
       }
     }

   The Xtensa version of `ld' enables the `--relax' option by default
to attempt to reduce space in the output image by combining literals
with identical values.  It also provides the `--no-relax' option to
disable this optimization.  When enabled, the relaxation algorithm
ensures that a literal will only be merged with another literal when
the new merged literal location is within the offset range of all of
its uses.

   The relaxation mechanism will also attempt to optimize
assembler-generated "longcall" sequences of `L32R'/`CALLXN' when the
target is known to fit into a `CALLN' instruction encoding.  The
current optimization converts the sequence into `NOP'/`CALLN' and
removes the literal referenced by the `L32R' instruction.


File: ld.info,  Node: BFD,  Next: Reporting Bugs,  Prev: Machine Dependent,  Up: Top

BFD
***

   The linker accesses object and archive files using the BFD libraries.
These libraries allow the linker to use the same routines to operate on
object files whatever the object file format.  A different object file
format can be supported simply by creating a new BFD back end and adding
it to the library.  To conserve runtime memory, however, the linker and
associated tools are usually configured to support only a subset of the
object file formats available.  You can use `objdump -i' (*note
objdump: (binutils.info)objdump.) to list all the formats available for
your configuration.

   As with most implementations, BFD is a compromise between several
conflicting requirements. The major factor influencing BFD design was
efficiency: any time used converting between formats is time which
would not have been spent had BFD not been involved. This is partly
offset by abstraction payback; since BFD simplifies applications and
back ends, more time and care may be spent optimizing algorithms for a
greater speed.

   One minor artifact of the BFD solution which you should bear in mind
is the potential for information loss.  There are two places where
useful information can be lost using the BFD mechanism: during
conversion and during output. *Note BFD information loss::.

* Menu:

* BFD outline::                 How it works: an outline of BFD


File: ld.info,  Node: BFD outline,  Up: BFD

How It Works: An Outline of BFD
===============================

   When an object file is opened, BFD subroutines automatically
determine the format of the input object file.  They then build a
descriptor in memory with pointers to routines that will be used to
access elements of the object file's data structures.

   As different information from the object files is required, BFD
reads from different sections of the file and processes them.  For
example, a very common operation for the linker is processing symbol
tables.  Each BFD back end provides a routine for converting between
the object file's representation of symbols and an internal canonical
format. When the linker asks for the symbol table of an object file, it
calls through a memory pointer to the routine from the relevant BFD
back end which reads and converts the table into a canonical form.  The
linker then operates upon the canonical form. When the link is finished
and the linker writes the output file's symbol table, another BFD back
end routine is called to take the newly created symbol table and
convert it into the chosen output format.

* Menu:

* BFD information loss::        Information Loss
* Canonical format::            The BFD canonical object-file format


File: ld.info,  Node: BFD information loss,  Next: Canonical format,  Up: BFD outline

Information Loss
----------------

   _Information can be lost during output._ The output formats
supported by BFD do not provide identical facilities, and information
which can be described in one form has nowhere to go in another format.
One example of this is alignment information in `b.out'. There is
nowhere in an `a.out' format file to store alignment information on the
contained data, so when a file is linked from `b.out' and an `a.out'
image is produced, alignment information will not propagate to the
output file. (The linker will still use the alignment information
internally, so the link is performed correctly).

   Another example is COFF section names. COFF files may contain an
unlimited number of sections, each one with a textual section name. If
the target of the link is a format which does not have many sections
(e.g., `a.out') or has sections without names (e.g., the Oasys format),
the link cannot be done simply. You can circumvent this problem by
describing the desired input-to-output section mapping with the linker
command language.

   _Information can be lost during canonicalization._ The BFD internal
canonical form of the external formats is not exhaustive; there are
structures in input formats for which there is no direct representation
internally.  This means that the BFD back ends cannot maintain all
possible data richness through the transformation between external to
internal and back to external formats.

   This limitation is only a problem when an application reads one
format and writes another.  Each BFD back end is responsible for
maintaining as much data as possible, and the internal BFD canonical
form has structures which are opaque to the BFD core, and exported only
to the back ends. When a file is read in one format, the canonical form
is generated for BFD and the application. At the same time, the back
end saves away any information which may otherwise be lost. If the data
is then written back in the same format, the back end routine will be
able to use the canonical form provided by the BFD core as well as the
information it prepared earlier.  Since there is a great deal of
commonality between back ends, there is no information lost when
linking or copying big endian COFF to little endian COFF, or `a.out' to
`b.out'.  When a mixture of formats is linked, the information is only
lost from the files whose format differs from the destination.


File: ld.info,  Node: Canonical format,  Prev: BFD information loss,  Up: BFD outline

The BFD canonical object-file format
------------------------------------

   The greatest potential for loss of information occurs when there is
the least overlap between the information provided by the source
format, that stored by the canonical format, and that needed by the
destination format. A brief description of the canonical form may help
you understand which kinds of data you can count on preserving across
conversions.

_files_
     Information stored on a per-file basis includes target machine
     architecture, particular implementation format type, a demand
     pageable bit, and a write protected bit.  Information like Unix
     magic numbers is not stored here--only the magic numbers' meaning,
     so a `ZMAGIC' file would have both the demand pageable bit and the
     write protected text bit set.  The byte order of the target is
     stored on a per-file basis, so that big- and little-endian object
     files may be used with one another.

_sections_
     Each section in the input file contains the name of the section,
     the section's original address in the object file, size and
     alignment information, various flags, and pointers into other BFD
     data structures.

_symbols_
     Each symbol contains a pointer to the information for the object
     file which originally defined it, its name, its value, and various
     flag bits.  When a BFD back end reads in a symbol table, it
     relocates all symbols to make them relative to the base of the
     section where they were defined.  Doing this ensures that each
     symbol points to its containing section.  Each symbol also has a
     varying amount of hidden private data for the BFD back end.  Since
     the symbol points to the original file, the private data format
     for that symbol is accessible.  `ld' can operate on a collection
     of symbols of wildly different formats without problems.

     Normal global and simple local symbols are maintained on output,
     so an output file (no matter its format) will retain symbols
     pointing to functions and to global, static, and common variables.
     Some symbol information is not worth retaining; in `a.out', type
     information is stored in the symbol table as long symbol names.
     This information would be useless to most COFF debuggers; the
     linker has command line switches to allow users to throw it away.

     There is one word of type information within the symbol, so if the
     format supports symbol type information within symbols (for
     example, COFF, IEEE, Oasys) and the type is simple enough to fit
     within one word (nearly everything but aggregates), the
     information will be preserved.

_relocation level_
     Each canonical BFD relocation record contains a pointer to the
     symbol to relocate to, the offset of the data to relocate, the
     section the data is in, and a pointer to a relocation type
     descriptor. Relocation is performed by passing messages through
     the relocation type descriptor and the symbol pointer. Therefore,
     relocations can be performed on output data using a relocation
     method that is only available in one of the input formats. For
     instance, Oasys provides a byte relocation format.  A relocation
     record requesting this relocation type would point indirectly to a
     routine to perform this, so the relocation may be performed on a
     byte being written to a 68k COFF file, even though 68k COFF has no
     such relocation type.

_line numbers_
     Object formats can contain, for debugging purposes, some form of
     mapping between symbols, source line numbers, and addresses in the
     output file.  These addresses have to be relocated along with the
     symbol information.  Each symbol with an associated list of line
     number records points to the first record of the list.  The head
     of a line number list consists of a pointer to the symbol, which
     allows finding out the address of the function whose line number
     is being described. The rest of the list is made up of pairs:
     offsets into the section and line numbers. Any format which can
     simply derive this information can pass it successfully between
     formats (COFF, IEEE and Oasys).


File: ld.info,  Node: Reporting Bugs,  Next: MRI,  Prev: BFD,  Up: Top

Reporting Bugs
**************

   Your bug reports play an essential role in making `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 `ld' work
better.  Bug reports are your contribution to the maintenance of `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


File: ld.info,  Node: Bug Criteria,  Next: Bug Reporting,  Up: Reporting Bugs

Have You Found a Bug?
=====================

   If you are not sure whether you have found a bug, here are some
guidelines:

   * If the linker gets a fatal signal, for any input whatever, that is
     a `ld' bug.  Reliable linkers never crash.

   * If `ld' produces an error message for valid input, that is a bug.

   * If `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.

   * If you are an experienced user of linkers, your suggestions for
     improvement of `ld' are welcome in any case.


File: ld.info,  Node: Bug Reporting,  Prev: Bug Criteria,  Up: Reporting Bugs

How to Report Bugs
==================

   A number of companies and individuals offer support for GNU
products.  If you obtained `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 `etc/SERVICE' in the GNU Emacs distribution.

   Otherwise, send bug reports for `ld' to `bug-binutils@gnu.org'.

   The fundamental principle of reporting bugs usefully is this:
*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?"  This cannot help us fix a bug, so it is basically useless.  We
respond by asking for enough details to enable us to investigate.  You
might as well expedite matters by sending them to begin with.

   To enable us to fix the bug, you should include all these things:

   * The version of `ld'.  `ld' announces it if you start it with the
     `--version' argument.

     Without this, we will not know whether there is any point in
     looking for the bug in the current version of `ld'.

   * Any patches you may have applied to the `ld' source, including any
     patches made to the `BFD' library.

   * The type of machine you are using, and the operating system name
     and version number.

   * What compiler (and its version) was used to compile `ld'--e.g.
     "`gcc-2.7'".

   * 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.

   * 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 provided that they are reasonably small.  Say no more than
     10K.  For bigger files you can either make them available by FTP
     or HTTP or else state that you are willing to send the object
     file(s) to whomever requests them.  (Note - your email will be
     going to a mailing list, so we do not want to clog it up with
     large attachments).  But small attachments are best.

     If the source files were assembled using `gas' or compiled using
     `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
     `gas' or `gcc' was used to produce the object files.  Also say how
     `gas' or `gcc' were configured.

   * 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 `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 `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.

   * If you wish to suggest changes to the `ld' source, send us context
     diffs, as generated by `diff' with the `-u', `-c', or `-p' option.
     Always send diffs from the old file to the new file.  If you even
     discuss something in the `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.

   Here are some things that are not necessary:

   * 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 _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.

   * 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 `ld' 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.

   * 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.


File: ld.info,  Node: MRI,  Next: GNU Free Documentation License,  Prev: Reporting Bugs,  Up: Top

MRI Compatible Script Files
***************************

   To aid users making the transition to GNU `ld' from the MRI linker,
`ld' can use MRI compatible linker scripts as an alternative to the
more general-purpose linker scripting language described in *Note
Scripts::.  MRI compatible linker scripts have a much simpler command
set than the scripting language otherwise used with `ld'.  GNU `ld'
supports the most commonly used MRI linker commands; these commands are
described here.

   In general, MRI scripts aren't of much use with the `a.out' object
file format, since it only has three sections and MRI scripts lack some
features to make use of them.

   You can specify a file containing an MRI-compatible script using the
`-c' command-line option.

   Each command in an MRI-compatible script occupies its own line; each
command line starts with the keyword that identifies the command (though
blank lines are also allowed for punctuation).  If a line of an
MRI-compatible script begins with an unrecognized keyword, `ld' issues
a warning message, but continues processing the script.

   Lines beginning with `*' are comments.

   You can write these commands using all upper-case letters, or all
lower case; for example, `chip' is the same as `CHIP'.  The following
list shows only the upper-case form of each command.

`ABSOLUTE SECNAME'
`ABSOLUTE SECNAME, SECNAME, ... SECNAME'
     Normally, `ld' includes in the output file all sections from all
     the input files.  However, in an MRI-compatible script, you can
     use the `ABSOLUTE' command to restrict the sections that will be
     present in your output program.  If the `ABSOLUTE' command is used
     at all in a script, then only the sections named explicitly in
     `ABSOLUTE' commands will appear in the linker output.  You can
     still use other input sections (whatever you select on the command
     line, or using `LOAD') to resolve addresses in the output file.

`ALIAS OUT-SECNAME, IN-SECNAME'
     Use this command to place the data from input section IN-SECNAME
     in a section called OUT-SECNAME in the linker output file.

     IN-SECNAME may be an integer.

`ALIGN SECNAME = EXPRESSION'
     Align the section called SECNAME to EXPRESSION.  The EXPRESSION
     should be a power of two.

`BASE EXPRESSION'
     Use the value of EXPRESSION as the lowest address (other than
     absolute addresses) in the output file.

`CHIP EXPRESSION'
`CHIP EXPRESSION, EXPRESSION'
     This command does nothing; it is accepted only for compatibility.

`END'
     This command does nothing whatever; it's only accepted for
     compatibility.

`FORMAT OUTPUT-FORMAT'
     Similar to the `OUTPUT_FORMAT' command in the more general linker
     language, but restricted to one of these output formats:

       1. S-records, if OUTPUT-FORMAT is `S'

       2. IEEE, if OUTPUT-FORMAT is `IEEE'

       3. COFF (the `coff-m68k' variant in BFD), if OUTPUT-FORMAT is
          `COFF'

`LIST ANYTHING...'
     Print (to the standard output file) a link map, as produced by the
     `ld' command-line option `-M'.

     The keyword `LIST' may be followed by anything on the same line,
     with no change in its effect.

`LOAD FILENAME'
`LOAD FILENAME, FILENAME, ... FILENAME'
     Include one or more object file FILENAME in the link; this has the
     same effect as specifying FILENAME directly on the `ld' command
     line.

`NAME OUTPUT-NAME'
     OUTPUT-NAME is the name for the program produced by `ld'; the
     MRI-compatible command `NAME' is equivalent to the command-line
     option `-o' or the general script language command `OUTPUT'.

`ORDER SECNAME, SECNAME, ... SECNAME'
`ORDER SECNAME SECNAME SECNAME'
     Normally, `ld' orders the sections in its output file in the order
     in which they first appear in the input files.  In an
     MRI-compatible script, you can override this ordering with the
     `ORDER' command.  The sections you list with `ORDER' will appear
     first in your output file, in the order specified.

`PUBLIC NAME=EXPRESSION'
`PUBLIC NAME,EXPRESSION'
`PUBLIC NAME EXPRESSION'
     Supply a value (EXPRESSION) for external symbol NAME used in the
     linker input files.

`SECT SECNAME, EXPRESSION'
`SECT SECNAME=EXPRESSION'
`SECT SECNAME EXPRESSION'
     You can use any of these three forms of the `SECT' command to
     specify the start address (EXPRESSION) for section SECNAME.  If
     you have more than one `SECT' statement for the same SECNAME, only
     the _first_ sets the start address.