\input texinfo
@setfilename ld.info
@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
-@c 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
+@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@syncodeindex ky cp
@c man begin INCLUDE
@include configdoc.texi
@c (configdoc.texi is generated by the Makefile)
-@include ldver.texi
+@include bfdver.texi
@c man end
@c @smallbook
@end ifinfo
@ifinfo
-This file documents the @sc{gnu} linker LD version @value{VERSION}.
+This file documents the @sc{gnu} linker LD
+@ifset VERSION_PACKAGE
+@value{VERSION_PACKAGE}
+@end ifset
+version @value{VERSION}.
Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000,
-2001, 2002, 2003, 2004 Free Software Foundation, Inc.
+2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@ignore
@iftex
@finalout
@setchapternewpage odd
-@settitle Using LD, the GNU linker
+@settitle The GNU linker
@titlepage
-@title Using ld
-@subtitle The GNU linker
+@title The GNU linker
@sp 1
-@subtitle @code{ld} version 2
+@subtitle @code{ld}
+@ifset VERSION_PACKAGE
+@subtitle @value{VERSION_PACKAGE}
+@end ifset
@subtitle Version @value{VERSION}
@author Steve Chamberlain
@author Ian Lance Taylor
{\parskip=0pt
\hfill Red Hat Inc\par
\hfill nickc\@credhat.com, doc\@redhat.com\par
-\hfill {\it Using LD, the GNU linker}\par
+\hfill {\it The GNU linker}\par
\hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par
}
\global\parindent=0pt % Steve likes it this way.
@vskip 0pt plus 1filll
@c man begin COPYRIGHT
Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
-2002, 2003, 2004 Free Software Foundation, Inc.
+2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
@ifnottex
@node Top
-@top Using ld
-This file documents the @sc{gnu} linker ld version @value{VERSION}.
+@top LD
+This file documents the @sc{gnu} linker ld
+@ifset VERSION_PACKAGE
+@value{VERSION_PACKAGE}
+@end ifset
+version @value{VERSION}.
This document is distributed under the terms of the GNU Free
Documentation License. A copy of the license is included in the
@ifset man
@c For the man only
-This man page does not describe the command language; see the
-@command{ld} entry in @code{info}, or the manual
-ld: the GNU linker, for full details on the command language and
-on other aspects of the GNU linker.
+This man page does not describe the command language; see the
+@command{ld} entry in @code{info} for full details on the command
+language and on other aspects of the GNU linker.
@end ifset
@ifclear SingleFormat
precede the option name; for example, @samp{-trace-symbol} and
@samp{--trace-symbol} are equivalent. Note---there is one exception to
this rule. Multiple letter options that start with a lower case 'o' can
-only be preceeded by two dashes. This is to reduce confusion with the
+only be preceded by two dashes. This is to reduce confusion with the
@samp{-o} option. So for example @samp{-omagic} sets the output file
name to @samp{magic} whereas @samp{--omagic} sets the NMAGIC flag on the
output.
dynamic object, then you will probably need to use this option when
linking the program itself.
-You can also use the version script to control what symbols should
+You can also use the dynamic list to control what symbols should
be added to the dynamic symbol table if the output format supports it.
-See the description of @samp{--version-script} in @ref{VERSION}.
+See the description of @samp{--dynamic-list}.
@ifclear SingleFormat
@cindex big-endian objects
object files.
@ifclear SingleFormat
The @sc{gnu} linker uses other mechanisms for this purpose: the
-@option{-b}, @option{--format}, @option{--oformat} options, the
+@option{-b}, @option{--format}, @option{--oformat} options, the
@code{TARGET} command in linker scripts, and the @code{GNUTARGET}
environment variable.
@end ifclear
@cindex retain relocations in final executable
@item -q
@itemx --emit-relocs
-Leave relocation sections and contents in fully linked exececutables.
+Leave relocation sections and contents in fully linked executables.
Post link analysis and optimization tools may need this information in
order to perform correct modifications of executables. This results
in larger executables.
specified by any preceding @samp{-L} options. Multiple @samp{-T}
options accumulate.
+@kindex -dT @var{script}
+@kindex --default-script=@var{script}
+@cindex script files
+@item -dT @var{scriptfile}
+@itemx --default-script=@var{scriptfile}
+Use @var{scriptfile} as the default linker script. @xref{Scripts}.
+
+This option is similar to the @option{--script} option except that
+processing of the script is delayed until after the rest of the
+command line has been processed. This allows options placed after the
+@option{--default-script} option on the command line to affect the
+behaviour of the linker script, which can be important when the linker
+command line cannot be directly controlled by the user. (eg because
+the command line is being constructed by another tool, such as
+@samp{gcc}).
+
@kindex -u @var{symbol}
@kindex --undefined=@var{symbol}
@cindex undefined symbol
@kindex -X
@kindex --discard-locals
@cindex local symbols, deleting
-@cindex L, deleting symbols beginning
@item -X
@itemx --discard-locals
-Delete all temporary local symbols. For most targets, this is all local
-symbols whose names begin with @samp{L}.
+Delete all temporary local symbols. (These symbols start with
+system-specific local label prefixes, typically @samp{.L} for ELF systems
+or @samp{L} for traditional a.out systems.)
@kindex -y @var{symbol}
@kindex --trace-symbol=@var{symbol}
Marks the object that its symbol table interposes before all symbols
but the primary executable.
+@item lazy
+When generating an executable or shared library, mark it to tell the
+dynamic linker to defer function call resolution to the point when
+the function is called (lazy binding), rather than at load time.
+Lazy binding is the default.
+
@item loadfltr
Marks the object that its filters be processed immediately at
runtime.
@item relro
Create an ELF @code{PT_GNU_RELRO} segment header in the object.
+@item max-page-size=@var{value}
+Set the emulation maximum page size to @var{value}.
+
+@item common-page-size=@var{value}
+Set the emulation common page size to @var{value}.
+
@end table
-Other keywords are ignored for Solaris compatibility.
+Other keywords are ignored for Solaris compatibility.
@kindex -(
@cindex groups of archives
option can be used with @option{-shared}. Doing so means that a
shared library is being created but that all of the library's external
references must be resolved by pulling in entries from static
-libraries.
+libraries.
@kindex -Bsymbolic
@item -Bsymbolic
within the shared library. This option is only meaningful on ELF
platforms which support shared libraries.
+@kindex -Bsymbolic-functions
+@item -Bsymbolic-functions
+When creating a shared library, bind references to global function
+symbols to the definition within the shared library, if any.
+This option is only meaningful on ELF platforms which support shared
+libraries.
+
+@kindex --dynamic-list=@var{dynamic-list-file}
+@item --dynamic-list=@var{dynamic-list-file}
+Specify the name of a dynamic list file to the linker. This is
+typically used when creating shared libraries to specify a list of
+global symbols whose references shouldn't be bound to the definition
+within the shared library, or creating dynamically linked executables
+to specify a list of symbols which should be added to the symbol table
+in the executable. This option is only meaningful on ELF platforms
+which support shared libraries.
+
+The format of the dynamic list is the same as the version node without
+scope and node name. See @ref{VERSION} for more information.
+
+@kindex --dynamic-list-data
+@item --dynamic-list-data
+Include all global data symbols to the dynamic list.
+
+@kindex --dynamic-list-cpp-new
+@item --dynamic-list-cpp-new
+Provide the builtin dynamic list for C++ operator new and delete. It
+is mainly useful for building shared libstdc++.
+
+@kindex --dynamic-list-cpp-typeinfo
+@item --dynamic-list-cpp-typeinfo
+Provide the builtin dynamic list for C++ runtime type identification.
+
@kindex --check-sections
@kindex --no-check-sections
@item --check-sections
@kindex --gc-sections
@kindex --no-gc-sections
@cindex garbage collection
-@item --no-gc-sections
-@itemx --gc-sections
+@item --gc-sections
+@itemx --no-gc-sections
Enable garbage collection of unused input sections. It is ignored on
targets that do not support this option. This option is not compatible
-with @samp{-r}. The default behaviour (of not performing this garbage
-collection) can be restored by specifying @samp{--no-gc-sections} on
-the command line.
+with @samp{-r} or @samp{--emit-relocs}. The default behaviour (of not
+performing this garbage collection) can be restored by specifying
+@samp{--no-gc-sections} on the command line.
+
+@kindex --print-gc-sections
+@kindex --no-print-gc-sections
+@cindex garbage collection
+@item --print-gc-sections
+@itemx --no-print-gc-sections
+List all sections removed by garbage collection. The listing is
+printed on stderr. This option is only effective if garbage
+collection has been enabled via the @samp{--gc-sections}) option. The
+default behaviour (of not listing the sections that are removed) can
+be restored by specifying @samp{--no-print-gc-sections} on the command
+line.
@cindex help
@cindex usage
is done even if the linker is creating a non-symbolic shared library.
The switch @option{--[no-]allow-shlib-undefined} controls the
behaviour for reporting unresolved references found in shared
-libraries being linked in.
+libraries being linked in.
@kindex --allow-multiple-definition
@kindex -z muldefs
the one that is available at load time, so the symbols might actually be
resolvable at load time. Plus there are some systems, (eg BeOS) where
undefined symbols in shared libraries is normal. (The kernel patches
-them at load time to select which function is most appropriate
+them at load time to select which function is most appropriate
for the current architecture. This is used for example to dynamically
select an appropriate memset function). Apparently it is also normal
for HPPA shared libraries to have undefined symbols.
runtime search path will be formed exclusively using the @option{-rpath}
options, ignoring the @option{-L} options. This can be useful when using
gcc, which adds many @option{-L} options which may be on NFS mounted
-filesystems.
+file systems.
For compatibility with other ELF linkers, if the @option{-R} option is
followed by a directory name, rather than a file name, it is treated as
runtime linker would do.
The linker uses the following search paths to locate required shared
-libraries.
+libraries:
@enumerate
@item
Any directories specified by @option{-rpath-link} options.
between @option{-rpath} and @option{-rpath-link} is that directories
specified by @option{-rpath} options are included in the executable and
used at runtime, whereas the @option{-rpath-link} option is only effective
-at link time. It is for the native linker only.
+at link time. Searching @option{-rpath} in this way is only supported
+by native linkers and cross linkers which have been configured with
+the @option{--with-sysroot} option.
@item
On an ELF system, if the @option{-rpath} and @code{rpath-link} options
were not used, search the contents of the environment variable
@kindex --warn-shared-textrel
@item --warn-shared-textrel
-Warn if the linker adds a DT_TEXTREL to a shared object.
+Warn if the linker adds a DT_TEXTREL to a shared object.
@kindex --warn-unresolved-symbols
@item --warn-unresolved-symbols
increasing the linker's memory requirements. Similarly reducing this
value can reduce the memory requirements at the expense of speed.
+@kindex --hash-style=@var{style}
+@item --hash-style=@var{style}
+Set the type of linker's hash table(s). @var{style} can be either
+@code{sysv} for classic ELF @code{.hash} section, @code{gnu} for
+new style GNU @code{.gnu.hash} section or @code{both} for both
+the classic ELF @code{.hash} and new style GNU @code{.gnu.hash}
+hash tables. The default is @code{sysv}.
+
@kindex --reduce-memory-overheads
@item --reduce-memory-overheads
This option reduces memory requirements at ld runtime, at the expense of
explicitly exported via DEF files or implicitly exported via function
attributes, the default is to not export anything else unless this
option is given. Note that the symbols @code{DllMain@@12},
-@code{DllEntryPoint@@0}, @code{DllMainCRTStartup@@12}, and
+@code{DllEntryPoint@@0}, @code{DllMainCRTStartup@@12}, and
@code{impure_ptr} will not be automatically
-exported. Also, symbols imported from other DLLs will not be
-re-exported, nor will symbols specifying the DLL's internal layout
-such as those beginning with @code{_head_} or ending with
-@code{_iname}. In addition, no symbols from @code{libgcc},
+exported. Also, symbols imported from other DLLs will not be
+re-exported, nor will symbols specifying the DLL's internal layout
+such as those beginning with @code{_head_} or ending with
+@code{_iname}. In addition, no symbols from @code{libgcc},
@code{libstd++}, @code{libmingw32}, or @code{crtX.o} will be exported.
Symbols whose names begin with @code{__rtti_} or @code{__builtin_} will
not be exported, to help with C++ DLLs. Finally, there is an
-extensive list of cygwin-private symbols that are not exported
+extensive list of cygwin-private symbols that are not exported
(obviously, this applies on when building DLLs for cygwin targets).
-These cygwin-excludes are: @code{_cygwin_dll_entry@@12},
+These cygwin-excludes are: @code{_cygwin_dll_entry@@12},
@code{_cygwin_crt0_common@@8}, @code{_cygwin_noncygwin_dll_entry@@12},
-@code{_fmode}, @code{_impure_ptr}, @code{cygwin_attach_dll},
+@code{_fmode}, @code{_impure_ptr}, @code{cygwin_attach_dll},
@code{cygwin_premain0}, @code{cygwin_premain1}, @code{cygwin_premain2},
-@code{cygwin_premain3}, and @code{environ}.
+@code{cygwin_premain3}, and @code{environ}.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --exclude-symbols
@kindex --large-address-aware
@item --large-address-aware
-If given, the appropriate bit in the ``Charateristics'' field of the COFF
+If given, the appropriate bit in the ``Characteristics'' field of the COFF
header is set to indicate that this executable supports virtual addresses
-greater than 2 gigabytes. This should be used in conjuction with the /3GB
+greater than 2 gigabytes. This should be used in conjunction with the /3GB
or /USERVA=@var{value} megabytes switch in the ``[operating systems]''
section of the BOOT.INI. Otherwise, this bit has no effect.
[This option is specific to PE targeted ports of the linker]
@kindex --dll-search-prefix
@item --dll-search-prefix @var{string}
When linking dynamically to a dll without an import library,
-search for @code{<string><basename>.dll} in preference to
+search for @code{<string><basename>.dll} in preference to
@code{lib<basename>.dll}. This behaviour allows easy distinction
between DLLs built for the various "subplatforms": native, cygwin,
uwin, pw, etc. For instance, cygwin DLLs typically use
-@code{--dll-search-prefix=cyg}.
+@code{--dll-search-prefix=cyg}.
[This option is specific to the i386 PE targeted port of the linker]
@kindex --enable-auto-import
@item --enable-auto-import
-Do sophisticated linking of @code{_symbol} to @code{__imp__symbol} for
-DATA imports from DLLs, and create the necessary thunking symbols when
+Do sophisticated linking of @code{_symbol} to @code{__imp__symbol} for
+DATA imports from DLLs, and create the necessary thunking symbols when
building the import libraries with those DATA exports. Note: Use of the
'auto-import' extension will cause the text section of the image file
to be made writable. This does not conform to the PE-COFF format
Using 'auto-import' generally will 'just work' -- but sometimes you may
see this message:
-"variable '<var>' can't be auto-imported. Please read the
+"variable '<var>' can't be auto-imported. Please read the
documentation for ld's @code{--enable-auto-import} for details."
-This message occurs when some (sub)expression accesses an address
-ultimately given by the sum of two constants (Win32 import tables only
+This message occurs when some (sub)expression accesses an address
+ultimately given by the sum of two constants (Win32 import tables only
allow one). Instances where this may occur include accesses to member
fields of struct variables imported from a DLL, as well as using a
constant index into an array variable imported from a DLL. Any
@item OUTPUT(@var{filename})
@kindex OUTPUT(@var{filename})
-@cindex output file name in linker scripot
+@cindex output file name in linker script
The @code{OUTPUT} command names the output file. Using
@code{OUTPUT(@var{filename})} in the linker script is exactly like using
@samp{-o @var{filename}} on the command line (@pxref{Options,,Command
@cindex discarding sections
@cindex sections, discarding
@cindex removing sections
-The linker will not create output section which do not have any
-contents. This is for convenience when referring to input sections that
-may or may not be present in any of the input files. For example:
+The linker will not create output sections with no contents. This is
+for convenience when referring to input sections that may or may not
+be present in any of the input files. For example:
@smallexample
-.foo @{ *(.foo) @}
+.foo : @{ *(.foo) @}
@end smallexample
@noindent
will only create a @samp{.foo} section in the output file if there is a
-@samp{.foo} section in at least one input file.
+@samp{.foo} section in at least one input file, and if the input
+sections are not all empty. Other link script directives that allocate
+space in an output section will also create the output section.
-If you use anything other than an input section description as an output
-section command, such as a symbol assignment, then the output section
-will always be created, even if there are no matching input sections.
+The linker will ignore address assignments (@pxref{Output Section Address})
+on discarded output sections, except when the linker script defines
+symbols in the output section. In that case the linker will obey
+the address assignments, possibly advancing dot even though the
+section is discarded.
@cindex /DISCARD/
The special output section name @samp{/DISCARD/} may be used to discard
an output section description sets the VMA (@pxref{Output Section
Address}).
-The linker will normally set the LMA equal to the VMA. You can change
-that by using the @code{AT} keyword. The expression @var{lma} that
-follows the @code{AT} keyword specifies the load address of the
-section.
+The expression @var{lma} that follows the @code{AT} keyword specifies
+the load address of the section.
Alternatively, with @samp{AT>@var{lma_region}} expression, you may
specify a memory region for the section's load address. @xref{MEMORY}.
Note that if the section has not had a VMA assigned to it then the
linker will use the @var{lma_region} as the VMA region as well.
+
+If neither @code{AT} nor @code{AT>} is specified for an allocatable
+section, the linker will set the LMA such that the difference between
+VMA and LMA for the section is the same as the preceding output
+section in the same region. If there is no preceding output section
+or the section is not allocatable, the linker will set the LMA equal
+to the VMA.
@xref{Output Section Region}.
@cindex ROM initialized data
NOCROSSREFS}.
For each section within the @code{OVERLAY}, the linker automatically
-defines two symbols. The symbol @code{__load_start_@var{secname}} is
+provides two symbols. The symbol @code{__load_start_@var{secname}} is
defined as the starting load address of the section. The symbol
@code{__load_stop_@var{secname}} is defined as the final load address of
the section. Any characters within @var{secname} which are not legal
This will define both @samp{.text0} and @samp{.text1} to start at
address 0x1000. @samp{.text0} will be loaded at address 0x4000, and
@samp{.text1} will be loaded immediately after @samp{.text0}. The
-following symbols will be defined: @code{__load_start_text0},
+following symbols will be defined if referenced: @code{__load_start_text0},
@code{__load_stop_text0}, @code{__load_start_text1},
@code{__load_stop_text1}.
@smallexample
@group
.text0 0x1000 : AT (0x4000) @{ o1/*.o(.text) @}
- __load_start_text0 = LOADADDR (.text0);
- __load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0);
+ PROVIDE (__load_start_text0 = LOADADDR (.text0));
+ PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0));
.text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @}
- __load_start_text1 = LOADADDR (.text1);
- __load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1);
+ PROVIDE (__load_start_text1 = LOADADDR (.text1));
+ PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1));
. = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
@end group
@end smallexample
could just as well have appeared in between @samp{1.1} and @samp{1.2}.
However, this would be a confusing way to write a version script.
-Node name can be omited, provided it is the only version node
+Node name can be omitted, provided it is the only version node
in the version script. Such version script doesn't assign any versions to
symbols, only selects which symbols will be globally visible out and which
won't.
@cindex holes
Assigning a value to @code{.} will cause the location counter to be
moved. This may be used to create holes in the output section. The
-location counter may never be moved backwards.
+location counter may not be moved backwards inside an output section,
+and may not be moved backwards outside of an output section if so
+doing creates areas with overlapping LMAs.
@smallexample
SECTIONS
the top page of memory).
@item system control instructions
-@command{ld} finds all @code{ldc.w, stc.w} instrcutions which use the
+@command{ld} finds all @code{ldc.w, stc.w} instructions which use the
32 bit absolute address form, but refer to the top page of memory, and
changes them to use 16 bit address form.
(That is: the linker turns @samp{ldc.w @code{@@}@var{aa}:32,ccr} into
case when a pointer to a function is taken. The pointer will in fact
point to the function trampoline.
+@cindex PIC_VENEER
+@kindex --pic-veneer
+The @samp{--pic-veneer} switch makes the linker use PIC sequences for
+ARM/Thumb interworking veneers, even if the rest of the binary
+is not PIC. This avoids problems on uClinux targets where
+@samp{--emit-relocs} is used to generate relocatable binaries.
+
@ifclear GENERIC
@lowersections
@end ifclear
@cindex ARM interworking support
@kindex --support-old-code
For the ARM, @command{ld} will generate code stubs to allow functions calls
-betweem ARM and Thumb code. These stubs only work with code that has
+between ARM and Thumb code. These stubs only work with code that has
been compiled and assembled with the @samp{-mthumb-interwork} command
line option. If it is necessary to link with old ARM object files or
libraries, which have not been compiled with the -mthumb-interwork
This option is enabled implicitly for SymbianOS, so there is no need to
specify it if you are using that target.
+@cindex VFP11_DENORM_FIX
+@kindex --vfp11-denorm-fix
+The @samp{--vfp11-denorm-fix} switch enables a link-time workaround for a
+bug in certain VFP11 coprocessor hardware, which sometimes allows
+instructions with denorm operands (which must be handled by support code)
+to have those operands overwritten by subsequent instructions before
+the support code can read the intended values.
+
+The bug may be avoided in scalar mode if you allow at least one
+intervening instruction between a VFP11 instruction which uses a register
+and another instruction which writes to the same register, or at least two
+intervening instructions if vector mode is in use. The bug only affects
+full-compliance floating-point mode: you do not need this workaround if
+you are using "runfast" mode. Please contact ARM for further details.
+
+If you know you are using buggy VFP11 hardware, you can
+enable this workaround by specifying the linker option
+@samp{--vfp-denorm-fix=scalar} if you are using the VFP11 scalar
+mode only, or @samp{--vfp-denorm-fix=vector} if you are using
+vector mode (the latter also works for scalar code). The default is
+@samp{--vfp-denorm-fix=none}.
+
+If the workaround is enabled, instructions are scanned for
+potentially-troublesome sequences, and a veneer is created for each
+such sequence which may trigger the erratum. The veneer consists of the
+first instruction of the sequence and a branch back to the subsequent
+instruction. The original instruction is then replaced with a branch to
+the veneer. The extra cycles required to call and return from the veneer
+are sufficient to avoid the erratum in both the scalar and vector cases.
+
+@cindex NO_ENUM_SIZE_WARNING
+@kindex --no-enum-size-warning
+The @samp{--no-enum-size-warning} switch prevents the linker from
+warning when linking object files that specify incompatible EABI
+enumeration size attributes. For example, with this switch enabled,
+linking of an object file using 32-bit enumeration values with another
+using enumeration values fitted into the smallest possible space will
+not be diagnosed.
+
@ifclear GENERIC
@lowersections
@end ifclear
@section @command{ld} and WIN32 (cygwin/mingw)
This section describes some of the win32 specific @command{ld} issues.
-See @ref{Options,,Command Line Options} for detailed decription of the
+See @ref{Options,,Command Line Options} for detailed description of the
command line options mentioned here.
@table @emph
name of the output DLL. If @samp{<name>} does not include a suffix,
the default library suffix, @samp{.DLL} is appended.
-When the .DEF file is used to build an application. rather than a
-library, the @code{NAME <name>} command shoud be used instead of
+When the .DEF file is used to build an application, rather than a
+library, the @code{NAME <name>} command should be used instead of
@code{LIBRARY}. If @samp{<name>} does not include a suffix, the default
executable suffix, @samp{.EXE} is appended.
of idioms that are typically used to do this; often client code can
omit the __declspec() declaration completely. See
@samp{--enable-auto-import} and @samp{automatic data imports} for more
-imformation.
+information.
@end table
@cindex automatic data imports
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
+decorations to achieve a behavior that conforms to that on POSIX/Un*x
platforms. This feature is enabled with the @samp{--enable-auto-import}
command-line option, although it is enabled by default on cygwin/mingw.
The @samp{--enable-auto-import} option itself now serves mainly to
The cygwin/mingw ports of @command{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
+traditional import library method, especially when linking large
libraries or applications. When @command{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
to find, in the first directory of its search path,
@example
-libxxx.dll.a
-xxx.dll.a
-libxxx.a
+libxxx.dll.a
+xxx.dll.a
+libxxx.a
+xxx.lib
cygxxx.dll (*)
-libxxx.dll
-xxx.dll
+libxxx.dll
+xxx.dll
@end example
before moving on to the next directory in the search path.
@samp{--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:
+wonder why import libraries are used at all. There are three reasons:
1. Until recently, the link-directly-to-dll functionality did @emph{not}
work with auto-imported data.
for the cygwin kernel makes use of this ability, and it is not
possible to do this without an import lib.
+3. Symbol aliases can only be resolved using an import lib. This is
+critical when linking against OS-supplied dll's (eg, the win32 API)
+in which symbols are usually exported as undecorated aliases of their
+stdcall-decorated assembly names.
+
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
+a dll, in many 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
individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
distribution.
+@ifset BUGURL
Otherwise, send bug reports for @command{ld} to
-@samp{bug-binutils@@gnu.org}.
+@value{BUGURL}.
+@end ifset
The fundamental principle of reporting bugs usefully is this:
@strong{report all the facts}. If you are not sure whether to state a
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 @command{ld} is out of synch, or you have encountered a bug in the
+copy of @command{ld} is out of sync, 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
projects / deliverable / binutils-gdb.git / blobdiff