431 lines
22 KiB
HTML
431 lines
22 KiB
HTML
<html lang="en">
|
|
<head>
|
|
<title>WIN32 - Untitled</title>
|
|
<meta http-equiv="Content-Type" content="text/html">
|
|
<meta name="description" content="Untitled">
|
|
<meta name="generator" content="makeinfo 4.7">
|
|
<link title="Top" rel="start" href="index.html#Top">
|
|
<link rel="up" href="Machine-Dependent.html#Machine-Dependent" title="Machine Dependent">
|
|
<link rel="prev" href="TI-COFF.html#TI-COFF" title="TI COFF">
|
|
<link rel="next" href="Xtensa.html#Xtensa" title="Xtensa">
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
|
<!--
|
|
This file documents the GNU linker LD
|
|
(GNU Binutils)
|
|
version 2.19.
|
|
|
|
Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000,
|
|
2001, 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
|
|
or any later version published by the Free Software Foundation;
|
|
with no Invariant Sections, with no Front-Cover Texts, and with no
|
|
Back-Cover Texts. A copy of the license is included in the
|
|
section entitled ``GNU Free Documentation License''.-->
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
|
<style type="text/css"><!--
|
|
pre.display { font-family:inherit }
|
|
pre.format { font-family:inherit }
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
|
pre.smallexample { font-size:smaller }
|
|
pre.smalllisp { font-size:smaller }
|
|
span.sc { font-variant:small-caps }
|
|
span.roman { font-family: serif; font-weight: normal; }
|
|
--></style>
|
|
</head>
|
|
<body>
|
|
<div class="node">
|
|
<p>
|
|
<a name="WIN32"></a>Next: <a rel="next" accesskey="n" href="Xtensa.html#Xtensa">Xtensa</a>,
|
|
Previous: <a rel="previous" accesskey="p" href="TI-COFF.html#TI-COFF">TI COFF</a>,
|
|
Up: <a rel="up" accesskey="u" href="Machine-Dependent.html#Machine-Dependent">Machine Dependent</a>
|
|
<hr><br>
|
|
</div>
|
|
|
|
<h3 class="section">4.13 <span class="command">ld</span> and WIN32 (cygwin/mingw)</h3>
|
|
|
|
<p>This section describes some of the win32 specific <span class="command">ld</span> issues.
|
|
See <a href="Options.html#Options">Command Line Options</a> for detailed description of the
|
|
command line options mentioned here.
|
|
|
|
|
|
<a name="index-import-libraries-614"></a>
|
|
<dl><dt><em>import libraries</em><dd>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 <span class="command">ld</span> have specific
|
|
support for creating such libraries provided with the
|
|
<span class="samp">--out-implib</span> command line option.
|
|
|
|
<br><dt><em>exporting DLL symbols</em><dd><a name="index-exporting-DLL-symbols-615"></a>The cygwin/mingw <span class="command">ld</span> has several ways to export symbols for dll's.
|
|
|
|
<dl>
|
|
<dt><em>using auto-export functionality</em><dd><a name="index-using-auto_002dexport-functionality-616"></a>By default <span class="command">ld</span> exports symbols with the auto-export functionality,
|
|
which is controlled by the following command line options:
|
|
|
|
<ul>
|
|
<li>–export-all-symbols [This is the default]
|
|
<li>–exclude-symbols
|
|
<li>–exclude-libs
|
|
</ul>
|
|
|
|
<p>If, however, <span class="samp">--export-all-symbols</span> is not given explicitly on the
|
|
command line, then the default auto-export behavior will be <em>disabled</em>
|
|
if either of the following are true:
|
|
|
|
<ul>
|
|
<li>A DEF file is used.
|
|
<li>Any symbol in any object file was marked with the __declspec(dllexport) attribute.
|
|
</ul>
|
|
|
|
<br><dt><em>using a DEF file</em><dd><a name="index-using-a-DEF-file-617"></a>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 <span class="samp"><dll
|
|
name>.def</span> and is added as any other object file to the linker's
|
|
command line. The file's name must end in <span class="samp">.def</span> or <span class="samp">.DEF</span>.
|
|
|
|
<pre class="example"> gcc -o <output> <objectfiles> <dll name>.def
|
|
</pre>
|
|
<p>Using a DEF file turns off the normal auto-export behavior, unless the
|
|
<span class="samp">--export-all-symbols</span> option is also used.
|
|
|
|
<p>Here is an example of a DEF file for a shared library called <span class="samp">xyz.dll</span>:
|
|
|
|
<pre class="example"> LIBRARY "xyz.dll" BASE=0x20000000
|
|
|
|
EXPORTS
|
|
foo
|
|
bar
|
|
_bar = bar
|
|
another_foo = abc.dll.afoo
|
|
var1 DATA
|
|
</pre>
|
|
<p>This example defines a DLL with a non-default base address and five
|
|
symbols in the export table. The third exported symbol <code>_bar</code> is an
|
|
alias for the second. The fourth symbol, <code>another_foo</code> is resolved
|
|
by "forwarding" to another module and treating it as an alias for
|
|
<code>afoo</code> exported from the DLL <span class="samp">abc.dll</span>. The final symbol
|
|
<code>var1</code> is declared to be a data object.
|
|
|
|
<p>The optional <code>LIBRARY <name></code> command indicates the <em>internal</em>
|
|
name of the output DLL. If <span class="samp"><name></span> does not include a suffix,
|
|
the default library suffix, <span class="samp">.DLL</span> is appended.
|
|
|
|
<p>When the .DEF file is used to build an application, rather than a
|
|
library, the <code>NAME <name></code> command should be used instead of
|
|
<code>LIBRARY</code>. If <span class="samp"><name></span> does not include a suffix, the default
|
|
executable suffix, <span class="samp">.EXE</span> is appended.
|
|
|
|
<p>With either <code>LIBRARY <name></code> or <code>NAME <name></code> the optional
|
|
specification <code>BASE = <number></code> may be used to specify a
|
|
non-default base address for the image.
|
|
|
|
<p>If neither <code>LIBRARY <name></code> nor <code>NAME <name></code> is specified,
|
|
or they specify an empty string, the internal name is the same as the
|
|
filename specified on the command line.
|
|
|
|
<p>The complete specification of an export symbol is:
|
|
|
|
<pre class="example"> EXPORTS
|
|
( ( ( <name1> [ = <name2> ] )
|
|
| ( <name1> = <module-name> . <external-name>))
|
|
[ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) *
|
|
</pre>
|
|
<p>Declares <span class="samp"><name1></span> as an exported symbol from the DLL, or declares
|
|
<span class="samp"><name1></span> as an exported alias for <span class="samp"><name2></span>; or declares
|
|
<span class="samp"><name1></span> as a "forward" alias for the symbol
|
|
<span class="samp"><external-name></span> in the DLL <span class="samp"><module-name></span>.
|
|
Optionally, the symbol may be exported by the specified ordinal
|
|
<span class="samp"><integer></span> alias.
|
|
|
|
<p>The optional keywords that follow the declaration indicate:
|
|
|
|
<p><code>NONAME</code>: Do not put the symbol name in the DLL's export table. It
|
|
will still be exported by its ordinal alias (either the value specified
|
|
by the .def specification or, otherwise, the value assigned by the
|
|
linker). The symbol name, however, does remain visible in the import
|
|
library (if any), unless <code>PRIVATE</code> is also specified.
|
|
|
|
<p><code>DATA</code>: The symbol is a variable or object, rather than a function.
|
|
The import lib will export only an indirect reference to <code>foo</code> as
|
|
the symbol <code>_imp__foo</code> (ie, <code>foo</code> must be resolved as
|
|
<code>*_imp__foo</code>).
|
|
|
|
<p><code>CONSTANT</code>: Like <code>DATA</code>, but put the undecorated <code>foo</code> as
|
|
well as <code>_imp__foo</code> into the import library. Both refer to the
|
|
read-only import address table's pointer to the variable, not to the
|
|
variable itself. This can be dangerous. If the user code fails to add
|
|
the <code>dllimport</code> attribute and also fails to explicitly add the
|
|
extra indirection that the use of the attribute enforces, the
|
|
application will behave unexpectedly.
|
|
|
|
<p><code>PRIVATE</code>: Put the symbol in the DLL's export table, but do not put
|
|
it into the static import library used to resolve imports at link time. The
|
|
symbol can still be imported using the <code>LoadLibrary/GetProcAddress</code>
|
|
API at runtime or by by using the GNU ld extension of linking directly to
|
|
the DLL without an import library.
|
|
|
|
<p>See ld/deffilep.y in the binutils sources for the full specification of
|
|
other DEF file statements
|
|
|
|
<p><a name="index-creating-a-DEF-file-618"></a>While linking a shared dll, <span class="command">ld</span> is able to create a DEF file
|
|
with the <span class="samp">--output-def <file></span> command line option.
|
|
|
|
<br><dt><em>Using decorations</em><dd><a name="index-Using-decorations-619"></a>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:
|
|
|
|
<pre class="example"> __declspec(dllexport) int a_variable
|
|
__declspec(dllexport) void a_function(int with_args)
|
|
</pre>
|
|
<p>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 <span class="samp">--export-all-symbols</span> option is also used.
|
|
|
|
<p>Note that object files that wish to access these symbols must <em>not</em>
|
|
decorate them with dllexport. Instead, they should use dllimport,
|
|
instead:
|
|
|
|
<pre class="example"> __declspec(dllimport) int a_variable
|
|
__declspec(dllimport) void a_function(int with_args)
|
|
</pre>
|
|
<p>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
|
|
<span class="samp">--enable-auto-import</span> and <span class="samp">automatic data imports</span> for more
|
|
information.
|
|
</dl>
|
|
|
|
<p><a name="index-automatic-data-imports-620"></a><br><dt><em>automatic data imports</em><dd>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 achieve a behavior that conforms to that on POSIX/Un*x
|
|
platforms. This feature is enabled with the <span class="samp">--enable-auto-import</span>
|
|
command-line option, although it is enabled by default on cygwin/mingw.
|
|
The <span class="samp">--enable-auto-import</span> option itself now serves mainly to
|
|
suppress any warnings that are ordinarily emitted when linked objects
|
|
trigger the feature's use.
|
|
|
|
<p>auto-import of variables does not always work flawlessly without
|
|
additional assistance. Sometimes, you will see this message
|
|
|
|
<p>"variable '<var>' can't be auto-imported. Please read the
|
|
documentation for ld's <code>--enable-auto-import</code> for details."
|
|
|
|
<p>The <span class="samp">--enable-auto-import</span> documentation explains why this error
|
|
occurs, and several methods that can be used to overcome this difficulty.
|
|
One of these methods is the <em>runtime pseudo-relocs</em> feature, described
|
|
below.
|
|
|
|
<p><a name="index-runtime-pseudo_002drelocation-621"></a>For complex variables imported from DLLs (such as structs or classes),
|
|
object files typically contain a base address for the variable and an
|
|
offset (<em>addend</em>) 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.
|
|
|
|
<p>The <span class="samp">--enable-runtime-pseudo-relocs</span> 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.
|
|
|
|
<p><span class="samp">--enable-runtime-pseudo-relocs</span> is not the default; it must be explicitly
|
|
enabled as needed.
|
|
|
|
<p><a name="index-direct-linking-to-a-dll-622"></a><br><dt><em>direct linking to a dll</em><dd>The cygwin/mingw ports of <span class="command">ld</span> 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, especially when linking large
|
|
libraries or applications. When <span class="command">ld</span> 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.
|
|
|
|
<p>Linking directly to a dll uses no extra command-line switches other than
|
|
<span class="samp">-L</span> and <span class="samp">-l</span>, because <span class="command">ld</span> 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.
|
|
|
|
<p>For instance, when ld is called with the argument <span class="samp">-lxxx</span> it will attempt
|
|
to find, in the first directory of its search path,
|
|
|
|
<pre class="example"> libxxx.dll.a
|
|
xxx.dll.a
|
|
libxxx.a
|
|
xxx.lib
|
|
cygxxx.dll (*)
|
|
libxxx.dll
|
|
xxx.dll
|
|
</pre>
|
|
<p>before moving on to the next directory in the search path.
|
|
|
|
<p>(*) Actually, this is not <span class="samp">cygxxx.dll</span> but in fact is <span class="samp"><prefix>xxx.dll</span>,
|
|
where <span class="samp"><prefix></span> is set by the <span class="command">ld</span> option
|
|
<span class="samp">--dll-search-prefix=<prefix></span>. In the case of cygwin, the standard gcc spec
|
|
file includes <span class="samp">--dll-search-prefix=cyg</span>, so in effect we actually search for
|
|
<span class="samp">cygxxx.dll</span>.
|
|
|
|
<p>Other win32-based unix environments, such as mingw or pw32, may use other
|
|
<span class="samp"><prefix></span>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.
|
|
|
|
<p>The generic cygwin/mingw path layout uses a <span class="samp">bin</span> directory for
|
|
applications and dll's and a <span class="samp">lib</span> directory for the import
|
|
libraries (using cygwin nomenclature):
|
|
|
|
<pre class="example"> bin/
|
|
cygxxx.dll
|
|
lib/
|
|
libxxx.dll.a (in case of dll's)
|
|
libxxx.a (in case of static archive)
|
|
</pre>
|
|
<p>Linking directly to a dll without using the import library can be
|
|
done two ways:
|
|
|
|
<p>1. Use the dll directly by adding the <span class="samp">bin</span> path to the link line
|
|
<pre class="example"> gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx
|
|
</pre>
|
|
<p>However, as the dll's often have version numbers appended to their names
|
|
(<span class="samp">cygncurses-5.dll</span>) this will often fail, unless one specifies
|
|
<span class="samp">-L../bin -lncurses-5</span> to include the version. Import libs are generally
|
|
not versioned, and do not have this difficulty.
|
|
|
|
<p>2. Create a symbolic link from the dll to a file in the <span class="samp">lib</span>
|
|
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.
|
|
|
|
<pre class="example"> ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
|
|
</pre>
|
|
<p>Then you can link without any make environment changes.
|
|
|
|
<pre class="example"> gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx
|
|
</pre>
|
|
<p>This technique also avoids the version number problems, because the following is
|
|
perfectly legal
|
|
|
|
<pre class="example"> bin/
|
|
cygxxx-5.dll
|
|
lib/
|
|
libxxx.dll.a -> ../bin/cygxxx-5.dll
|
|
</pre>
|
|
<p>Linking directly to a dll without using an import lib will work
|
|
even when auto-import features are exercised, and even when
|
|
<span class="samp">--enable-runtime-pseudo-relocs</span> is used.
|
|
|
|
<p>Given the improvements in speed and memory usage, one might justifiably
|
|
wonder why import libraries are used at all. There are three reasons:
|
|
|
|
<p>1. Until recently, the link-directly-to-dll functionality did <em>not</em>
|
|
work with auto-imported data.
|
|
|
|
<p>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.
|
|
|
|
<p>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.
|
|
|
|
<p>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 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
|
|
will soon begin to use this feature whenever possible.
|
|
|
|
<br><dt><em>symbol aliasing</em><dd>
|
|
<dl>
|
|
<dt><em>adding additional names</em><dd>Sometimes, it is useful to export symbols with additional names.
|
|
A symbol <span class="samp">foo</span> will be exported as <span class="samp">foo</span>, but it can also be
|
|
exported as <span class="samp">_foo</span> 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:
|
|
|
|
<pre class="example"> LIBRARY "xyz.dll" BASE=0x61000000
|
|
|
|
EXPORTS
|
|
foo
|
|
_foo = foo
|
|
</pre>
|
|
<p>The line <span class="samp">_foo = foo</span> maps the symbol <span class="samp">foo</span> to <span class="samp">_foo</span>.
|
|
|
|
<p>Another method for creating a symbol alias is to create it in the
|
|
source code using the "weak" attribute:
|
|
|
|
<pre class="example"> void foo () { /* Do something. */; }
|
|
void _foo () __attribute__ ((weak, alias ("foo")));
|
|
</pre>
|
|
<p>See the gcc manual for more information about attributes and weak
|
|
symbols.
|
|
|
|
<br><dt><em>renaming symbols</em><dd>Sometimes it is useful to rename exports. For instance, the cygwin
|
|
kernel does this regularly. A symbol <span class="samp">_foo</span> can be exported as
|
|
<span class="samp">foo</span> but not as <span class="samp">_foo</span> by using special directives in the
|
|
DEF file. (This will also affect the import library, if it is
|
|
created). In the following example:
|
|
|
|
<pre class="example"> LIBRARY "xyz.dll" BASE=0x61000000
|
|
|
|
EXPORTS
|
|
_foo = foo
|
|
</pre>
|
|
<p>The line <span class="samp">_foo = foo</span> maps the exported symbol <span class="samp">foo</span> to
|
|
<span class="samp">_foo</span>.
|
|
</dl>
|
|
|
|
<p>Note: using a DEF file disables the default auto-export behavior,
|
|
unless the <span class="samp">--export-all-symbols</span> command line option is used.
|
|
If, however, you are trying to rename symbols, then you should list
|
|
<em>all</em> desired exports in the DEF file, including the symbols
|
|
that are not being renamed, and do <em>not</em> use the
|
|
<span class="samp">--export-all-symbols</span> option. If you list only the
|
|
renamed symbols in the DEF file, and use <span class="samp">--export-all-symbols</span>
|
|
to handle the other symbols, then the both the new names <em>and</em>
|
|
the original names for the renamed symbols will be exported.
|
|
In effect, you'd be aliasing those symbols, not renaming them,
|
|
which is probably not what you wanted.
|
|
|
|
<p><a name="index-weak-externals-623"></a><br><dt><em>weak externals</em><dd>The Windows object format, PE, specifies a form of weak symbols called
|
|
weak externals. When a weak symbol is linked and the symbol is not
|
|
defined, the weak symbol becomes an alias for some other symbol. There
|
|
are three variants of weak externals:
|
|
<ul>
|
|
<li>Definition is searched for in objects and libraries, historically
|
|
called lazy externals.
|
|
<li>Definition is searched for only in other objects, not in libraries.
|
|
This form is not presently implemented.
|
|
<li>No search; the symbol is an alias. This form is not presently
|
|
implemented.
|
|
</ul>
|
|
As a GNU extension, weak symbols that do not specify an alternate symbol
|
|
are supported. If the symbol is undefined when linking, the symbol
|
|
uses a default value.
|
|
</dl>
|
|
|
|
</body></html>
|
|
|