Click above to get retro games delivered to your door ever month!

Command Line Options
====================

   The linker supports a plethora of command-line options, but in actual
practice few of them are used in any particular context.  For instance,
a frequent use of `ld' is to link standard Unix object files on a
standard, supported Unix system.  On such a system, to link a file
`hello.o':

     ld -o OUTPUT /lib/crt0.o hello.o -lc

   This tells `ld' to produce a file called OUTPUT as the result of
linking the file `/lib/crt0.o' with `hello.o' and the library `libc.a',
which will come from the standard search directories.  (See the
discussion of the `-l' option below.)

   The command-line options to `ld' may be specified in any order, and
may be repeated at will.  Repeating most options with a different
argument will either have no further effect, or override prior
occurrences (those further to the left on the command line) of that
option.  Options which may be meaningfully specified more than once are
noted in the descriptions below.

   Non-option arguments are objects files which are to be linked
together.  They may follow, precede, or be mixed in with command-line
options, except that an object file argument may not be placed between
an option and its argument.

   Usually the linker is invoked with at least one object file, but you
can specify other forms of binary input files using `-l', `-R', and the
script command language.  If *no* binary input files at all are
specified, the linker does not produce any output, and issues the
message `No input files'.

   If the linker can not recognize the format of an object file, it will
assume that it is a linker script.  A script specified in this way
augments the main linker script used for the link (either the default
linker script or the one specified by using `-T').  This feature
permits the linker to link against a file which appears to be an object
or an archive, but actually merely defines some symbol values, or uses
`INPUT' or `GROUP' to load other objects.  Commands:.   

   For options whose names are a single letter, option arguments must
either follow the option letter without intervening whitespace, or be
given as separate arguments immediately following the option that
requires them.

   For options whose names are multiple letters, either one dash or two
can precede the option name; for example, `--oformat' and `-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, `--oformat srec' and `--oformat=srec' are equivalent.
Unique abbreviations of the names of multiple-letter options are
accepted.

`-aKEYWORD'
     This option is supported for HP/UX compatibility.  The KEYWORD
     argument must be one of the strings `archive', `shared', or
     `default'.  `-aarchive' is functionally equivalent to `-Bstatic',
     and the other two keywords are functionally equivalent to
     `-Bdynamic'.  This option may be used any number of times.

`-AARCHITECTURE'
`--architecture=ARCHITECTURE'
     In the current release of `ld', this option is useful only for the
     Intel 960 family of architectures.  In that `ld' configuration, the
     ARCHITECTURE argument identifies the particular architecture in
     the 960 family, enabling some safeguards and modifying the
     archive-library search path.  *Note `ld' and the Intel 960 family:
     i960, for details.

     Future releases of `ld' may support similar functionality for
     other architecture families.

`-b INPUT-FORMAT'
`--format=INPUT-FORMAT'
     `ld' may be configured to support more than one kind of object
     file.  If your `ld' is configured this way, you can use the `-b'
     option to specify the binary format for input object files that
     follow this option on the command line.  Even when `ld' is
     configured to support alternative object formats, you don't
     usually need to specify this, as `ld' should be configured to
     expect as a default input format the most usual format on each
     machine.  INPUT-FORMAT is a text string, the name of a particular
     format supported by the BFD libraries.  (You can list the
     available binary formats with `objdump -i'.) BFD:.   

     You may want to use this option if you are linking files with an
     unusual binary format.  You can also use `-b' to switch formats
     explicitly (when linking object files of different formats), by
     including `-b INPUT-FORMAT' before each group of object files in a
     particular format.

     The default format is taken from the environment variable
     `GNUTARGET'.  Environment:.  You can also define the input   
     format from a script, using the command `TARGET'; see Option
     Commands:

`-c MRI-COMMANDFILE'
`--mri-script=MRI-COMMANDFILE'
     For compatibility with linkers produced by MRI, `ld' accepts script
     files written in an alternate, restricted command language,
     described in MRI Compatible Script Files: MRI Introduce    
     MRI script files with the option `-c'; use the `-T' option to run
     linker scripts written in the general-purpose `ld' scripting
     language.  If MRI-CMDFILE does not exist, `ld' looks for it in the
     directories specified by any `-L' options.

`-d'
`-dc'
`-dp'
     These three options are equivalent; multiple forms are supported
     for compatibility with other linkers.  They assign space to common
     symbols even if a relocatable output file is specified (with
     `-r').  The script command `FORCE_COMMON_ALLOCATION' has the same
     effect.  Option Commands:.   

`-e ENTRY'
`--entry=ENTRY'
     Use ENTRY as the explicit symbol for beginning execution of your
     program, rather than the default entry point. Entry Point:,   
     for a discussion of defaults and other ways of specifying the
     entry point.

`-E'
`-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 some uses of `dlopen'.

`-F'
`-FFORMAT'
     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 `ld' uses for this
     purpose (the `-b' or `-format' options for input files, `-oformat'
     option or the `TARGET' command in linker scripts for output files,
     the `GNUTARGET' environment variable) are more flexible, but `ld'
     accepts the `-F' option for compatibility with scripts written to
     call the old linker.

`--force-exe-suffix'
     Make sure that an output file has a .exe suffix.

     If a successfully built fully linked output file does not have a
     `.exe' or `.dll' suffix, this option forces the linker to copy the
     output file to one of the same name with a `.exe' suffix. This
     option is useful when using unmodified Unix makefiles on a
     Microsoft Windows host, since some versions of Windows won't run
     an image unless it ends in a `.exe' suffix.

`-g'
     Ignored.  Provided for compatibility with other tools.

`-GVALUE'
`--gpsize=VALUE'
     Set the maximum size of objects to be optimized using the GP
     register to SIZE.  This is only meaningful for object file formats
     such as MIPS ECOFF which supports putting large and small objects
     into different sections.  This is ignored for other object file
     formats.

`-hNAME'
`-soname=NAME'
     When creating an ELF shared object, set the internal DT_SONAME
     field to the specified name.  When an executable is linked with a
     shared object which has a DT_SONAME field, then when the
     executable is run the dynamic linker will attempt to load the
     shared object specified by the DT_SONAME field rather than the
     using the file name given to the linker.

`-i'
     Perform an incremental link (same as option `-r').

`-lARCHIVE'
`--library=ARCHIVE'
     Add archive file ARCHIVE to the list of files to link.  This
     option may be used any number of times.  `ld' will search its
     path-list for occurrences of `libARCHIVE.a' for every ARCHIVE
     specified.  File extensions other than `.a' may be used on certain
     systems.

`-LSEARCHDIR'
`--library-path=SEARCHDIR'
     Add path SEARCHDIR to the list of paths that `ld' will search for
     archive libraries and `ld' control scripts.  You may use this
     option any number of times.  The directories are searched in the
     order in which they are specified on the command line.
     Directories specified on the command line are searched before the
     default directories.  All `-L' options apply to all `-l' options,
     regardless of the order in which the options appear.

     The default set of paths searched (without being specified with
     `-L') depends on which emulation mode `ld' is using, and in some
     cases also on how it was configured.  Environment:.   

     The paths can also be specified in a link script with the
     `SEARCH_DIR' command.  Directories specified this way are searched
     at the point in which the linker script appears in the command
     line.

`-mEMULATION'
     Emulate the EMULATION linker.  You can list the available
     emulations with the `--verbose' or `-V' options.  The default
     depends on how your `ld' was configured.

`-M'
`--print-map'
     Print (to the standard output) a link map--diagnostic information
     about where symbols are mapped by `ld', and information on global
     common storage allocation.

`-n'
`--nmagic'
     Set the text segment to be read only, and mark the output as
     `NMAGIC' if possible.

`-N'
`--omagic'
     Set the text and data sections to be readable and writable.  Also,
     do not page-align the data segment.  If the output format supports
     Unix style magic numbers, mark the output as `OMAGIC'.

`-o OUTPUT'
`--output=OUTPUT'
     Use OUTPUT as the name for the program produced by `ld'; if this
     option is not specified, the name `a.out' is used by default.  The
     script command `OUTPUT' can also specify the output file name.

`-r'
`--relocateable'
     Generate relocatable output--i.e., generate an output file that
     can in turn serve as input to `ld'.  This is often called "partial
     linking".  As a side effect, in environments that support standard
     Unix magic numbers, this option also sets the output file's magic
     number to `OMAGIC'.  If this option is not specified, an absolute
     file is produced.  When linking C++ programs, this option *will
     not* resolve references to constructors; to do that, use `-Ur'.

     This option does the same thing as `-i'.

`-R FILENAME'
`--just-symbols=FILENAME'
     Read symbol names and their addresses from FILENAME, but do not
     relocate it or include it in the output.  This allows your output
     file to refer symbolically to absolute locations of memory defined
     in other programs.  You may use this option more than once.

     For compatibility with other ELF linkers, if the `-R' option is
     followed by a directory name, rather than a file name, it is
     treated as the `-rpath' option.

`-s'
`--strip-all'
     Omit all symbol information from the output file.

`-S'
`--strip-debug'
     Omit debugger symbol information (but not all symbols) from the
     output file.

`-t'
`--trace'
     Print the names of the input files as `ld' processes them.

`-T COMMANDFILE'
`--script=COMMANDFILE'
     Read link commands from the file COMMANDFILE.  These commands
     replace `ld''s default link script (rather than adding to it), so
     COMMANDFILE must specify everything necessary to describe the
     target format.  Commands:.  If COMMANDFILE does not exist,   
     `ld' looks for it in the directories specified by any preceding
     `-L' options.  Multiple `-T' options accumulate.

`-u SYMBOL'
`--undefined=SYMBOL'
     Force SYMBOL to be entered in the output file as an undefined
     symbol.  Doing this may, for example, trigger linking of
     additional modules from standard libraries.  `-u' may be repeated
     with different option arguments to enter additional undefined
     symbols.

`-v'
`--version'
`-V'
     Display the version number for `ld'.  The `-V' option also lists
     the supported emulations.

`-x'
`--discard-all'
     Delete all local symbols.

`-X'
`--discard-locals'
     Delete all temporary local symbols.  For most targets, this is all
     local symbols whose names begin with `L'.

`-y SYMBOL'
`--trace-symbol=SYMBOL'
     Print the name of each linked file in which SYMBOL appears.  This
     option may be given any number of times.  On many systems it is
     necessary to prepend an underscore.

     This option is useful when you have an undefined symbol in your
     link but don't know where the reference is coming from.

`-Y PATH'
     Add PATH to the default library search path.  This option exists
     for Solaris compatibility.

`-z KEYWORD'
     This option is ignored for Solaris compatibility.

`-( ARCHIVES -)'
`--start-group ARCHIVES --end-group'
     The ARCHIVES should be a list of archive files.  They may be
     either explicit file names, or `-l' options.

     The specified archives are searched repeatedly until no new
     undefined references are created.  Normally, an archive is
     searched only once in the order that it is specified on the
     command line.  If a symbol in that archive is needed to resolve an
     undefined symbol referred to by an object in an archive that
     appears later on the command line, the linker would not be able to
     resolve that reference.  By grouping the archives, they all be
     searched repeatedly until all possible references are resolved.

     Using this option has a significant performance cost.  It is best
     to use it only when there are unavoidable circular references
     between two or more archives.

`-assert KEYWORD'
     This option is ignored for SunOS compatibility.

`-Bdynamic'
`-dy'
`-call_shared'
     Link against dynamic libraries.  This is only meaningful on
     platforms for which shared libraries are supported.  This option
     is normally the default on such platforms.  The different variants
     of this option are for compatibility with various systems.  You
     may use this option multiple times on the command line: it affects
     library searching for `-l' options which follow it.

`-Bstatic'
`-dn'
`-non_shared'
`-static'
     Do not link against shared libraries.  This is only meaningful on
     platforms for which shared libraries are supported.  The different
     variants of this option are for compatibility with various
     systems.  You may use this option multiple times on the command
     line: it affects library searching for `-l' options which follow
     it.

`-Bsymbolic'
     When creating a shared library, bind references to global symbols
     to the definition within the shared library, if any.  Normally, it
     is possible for a program linked against a shared library to
     override the definition within the shared library.  This option is
     only meaningful on ELF platforms which support shared libraries.

`--cref'
     Output a cross reference table.  If a linker map file is being
     generated, the cross reference table is printed to the map file.
     Otherwise, it is printed on the standard output.

     The format of the table is intentionally simple, so that it may be
     easily processed by a script if necessary.  The symbols are
     printed out, sorted by name.  For each symbol, a list of file
     names is given.  If the symbol is defined, the first file listed
     is the location of the definition.  The remaining files contain
     references to the symbol.

`--defsym SYMBOL=EXPRESSION'