You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
556 lines
25 KiB
HTML
556 lines
25 KiB
HTML
4 years ago
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
||
|
|
<html>
|
||
|
|
<!-- This file documents the GNU linker LD
|
||
|
|
(SiFive Binutils 2.32.0-2020.04.1)
|
||
|
|
version 2.32.
|
||
|
|
|
||
|
|
Copyright (C) 1991-2019 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.3
|
||
|
|
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". -->
|
||
|
|
<!-- Created by GNU Texinfo 6.4, http://www.gnu.org/software/texinfo/ -->
|
||
|
|
<head>
|
||
|
|
<title>WIN32 (LD)</title>
|
||
|
|
|
||
|
|
<meta name="description" content="WIN32 (LD)">
|
||
|
|
<meta name="keywords" content="WIN32 (LD)">
|
||
|
|
<meta name="resource-type" content="document">
|
||
|
|
<meta name="distribution" content="global">
|
||
|
|
<meta name="Generator" content="makeinfo">
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<link href="index.html#Top" rel="start" title="Top">
|
||
|
|
<link href="LD-Index.html#LD-Index" rel="index" title="LD Index">
|
||
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
||
|
|
<link href="Machine-Dependent.html#Machine-Dependent" rel="up" title="Machine Dependent">
|
||
|
|
<link href="Xtensa.html#Xtensa" rel="next" title="Xtensa">
|
||
|
|
<link href="TI-COFF.html#TI-COFF" rel="prev" title="TI COFF">
|
||
|
|
<style type="text/css">
|
||
|
|
<!--
|
||
|
|
a.summary-letter {text-decoration: none}
|
||
|
|
blockquote.indentedblock {margin-right: 0em}
|
||
|
|
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
|
||
|
|
blockquote.smallquotation {font-size: smaller}
|
||
|
|
div.display {margin-left: 3.2em}
|
||
|
|
div.example {margin-left: 3.2em}
|
||
|
|
div.lisp {margin-left: 3.2em}
|
||
|
|
div.smalldisplay {margin-left: 3.2em}
|
||
|
|
div.smallexample {margin-left: 3.2em}
|
||
|
|
div.smalllisp {margin-left: 3.2em}
|
||
|
|
kbd {font-style: oblique}
|
||
|
|
pre.display {font-family: inherit}
|
||
|
|
pre.format {font-family: inherit}
|
||
|
|
pre.menu-comment {font-family: serif}
|
||
|
|
pre.menu-preformatted {font-family: serif}
|
||
|
|
pre.smalldisplay {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smallexample {font-size: smaller}
|
||
|
|
pre.smallformat {font-family: inherit; font-size: smaller}
|
||
|
|
pre.smalllisp {font-size: smaller}
|
||
|
|
span.nolinebreak {white-space: nowrap}
|
||
|
|
span.roman {font-family: initial; font-weight: normal}
|
||
|
|
span.sansserif {font-family: sans-serif; font-weight: normal}
|
||
|
|
ul.no-bullet {list-style: none}
|
||
|
|
-->
|
||
|
|
</style>
|
||
|
|
|
||
|
|
|
||
|
|
</head>
|
||
|
|
|
||
|
|
<body lang="en">
|
||
|
|
<a name="WIN32"></a>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Next: <a href="Xtensa.html#Xtensa" accesskey="n" rel="next">Xtensa</a>, Previous: <a href="TI-COFF.html#TI-COFF" accesskey="p" rel="prev">TI COFF</a>, Up: <a href="Machine-Dependent.html#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LD-Index.html#LD-Index" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
<hr>
|
||
|
|
<a name="ld-and-WIN32-_0028cygwin_002fmingw_0029"></a>
|
||
|
|
<h3 class="section">4.16 <code>ld</code> and WIN32 (cygwin/mingw)</h3>
|
||
|
|
|
||
|
|
<p>This section describes some of the win32 specific <code>ld</code> issues.
|
||
|
|
See <a href="Options.html#Options">Command-line Options</a> for detailed description of the
|
||
|
|
command-line options mentioned here.
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dd><a name="index-import-libraries"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><em>import libraries</em></dt>
|
||
|
|
<dd><p>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 <code>ld</code> have specific
|
||
|
|
support for creating such libraries provided with the
|
||
|
|
‘<samp>--out-implib</samp>’ command-line option.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><em>exporting DLL symbols</em></dt>
|
||
|
|
<dd><a name="index-exporting-DLL-symbols"></a>
|
||
|
|
<p>The cygwin/mingw <code>ld</code> has several ways to export symbols for dll’s.
|
||
|
|
</p>
|
||
|
|
<dl compact="compact">
|
||
|
|
<dt><em>using auto-export functionality</em></dt>
|
||
|
|
<dd><a name="index-using-auto_002dexport-functionality"></a>
|
||
|
|
<p>By default <code>ld</code> exports symbols with the auto-export functionality,
|
||
|
|
which is controlled by the following command-line options:
|
||
|
|
</p>
|
||
|
|
<ul>
|
||
|
|
<li> –export-all-symbols [This is the default]
|
||
|
|
</li><li> –exclude-symbols
|
||
|
|
</li><li> –exclude-libs
|
||
|
|
</li><li> –exclude-modules-for-implib
|
||
|
|
</li><li> –version-script
|
||
|
|
</li></ul>
|
||
|
|
|
||
|
|
<p>When auto-export is in operation, <code>ld</code> will export all the non-local
|
||
|
|
(global and common) symbols it finds in a DLL, with the exception of a few
|
||
|
|
symbols known to belong to the system’s runtime and libraries. As it will
|
||
|
|
often not be desirable to export all of a DLL’s symbols, which may include
|
||
|
|
private functions that are not part of any public interface, the command-line
|
||
|
|
options listed above may be used to filter symbols out from the list for
|
||
|
|
exporting. The ‘<samp>--output-def</samp>’ option can be used in order to see the
|
||
|
|
final list of exported symbols with all exclusions taken into effect.
|
||
|
|
</p>
|
||
|
|
<p>If ‘<samp>--export-all-symbols</samp>’ 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:
|
||
|
|
</p>
|
||
|
|
<ul>
|
||
|
|
<li> A DEF file is used.
|
||
|
|
</li><li> Any symbol in any object file was marked with the __declspec(dllexport) attribute.
|
||
|
|
</li></ul>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
<dt><em>using a DEF file</em></dt>
|
||
|
|
<dd><a name="index-using-a-DEF-file"></a>
|
||
|
|
<p>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 ‘<samp><dll
|
||
|
|
name>.def</samp>’ and is added as any other object file to the linker’s
|
||
|
|
command line. The file’s name must end in ‘<samp>.def</samp>’ or ‘<samp>.DEF</samp>’.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">gcc -o <output> <objectfiles> <dll name>.def
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>Using a DEF file turns off the normal auto-export behavior, unless the
|
||
|
|
‘<samp>--export-all-symbols</samp>’ option is also used.
|
||
|
|
</p>
|
||
|
|
<p>Here is an example of a DEF file for a shared library called ‘<samp>xyz.dll</samp>’:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">LIBRARY "xyz.dll" BASE=0x20000000
|
||
|
|
|
||
|
|
EXPORTS
|
||
|
|
foo
|
||
|
|
bar
|
||
|
|
_bar = bar
|
||
|
|
another_foo = abc.dll.afoo
|
||
|
|
var1 DATA
|
||
|
|
doo = foo == foo2
|
||
|
|
eoo DATA == var1
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>This example defines a DLL with a non-default base address and seven
|
||
|
|
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 ‘<samp>abc.dll</samp>’. The final symbol
|
||
|
|
<code>var1</code> is declared to be a data object. The ‘<samp>doo</samp>’ symbol in
|
||
|
|
export library is an alias of ‘<samp>foo</samp>’, which gets the string name
|
||
|
|
in export table ‘<samp>foo2</samp>’. The ‘<samp>eoo</samp>’ symbol is an data export
|
||
|
|
symbol, which gets in export table the name ‘<samp>var1</samp>’.
|
||
|
|
</p>
|
||
|
|
<p>The optional <code>LIBRARY <name></code> command indicates the <em>internal</em>
|
||
|
|
name of the output DLL. If ‘<samp><name></samp>’ does not include a suffix,
|
||
|
|
the default library suffix, ‘<samp>.DLL</samp>’ is appended.
|
||
|
|
</p>
|
||
|
|
<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 ‘<samp><name></samp>’ does not include a suffix, the default
|
||
|
|
executable suffix, ‘<samp>.EXE</samp>’ is appended.
|
||
|
|
</p>
|
||
|
|
<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>
|
||
|
|
<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>
|
||
|
|
<p>The complete specification of an export symbol is:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">EXPORTS
|
||
|
|
( ( ( <name1> [ = <name2> ] )
|
||
|
|
| ( <name1> = <module-name> . <external-name>))
|
||
|
|
[ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] [== <name3>] ) *
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>Declares ‘<samp><name1></samp>’ as an exported symbol from the DLL, or declares
|
||
|
|
‘<samp><name1></samp>’ as an exported alias for ‘<samp><name2></samp>’; or declares
|
||
|
|
‘<samp><name1></samp>’ as a "forward" alias for the symbol
|
||
|
|
‘<samp><external-name></samp>’ in the DLL ‘<samp><module-name></samp>’.
|
||
|
|
Optionally, the symbol may be exported by the specified ordinal
|
||
|
|
‘<samp><integer></samp>’ alias. The optional ‘<samp><name3></samp>’ is the to be used
|
||
|
|
string in import/export table for the symbol.
|
||
|
|
</p>
|
||
|
|
<p>The optional keywords that follow the declaration indicate:
|
||
|
|
</p>
|
||
|
|
<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>
|
||
|
|
<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>
|
||
|
|
<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>
|
||
|
|
<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 using the GNU ld extension of linking directly to
|
||
|
|
the DLL without an import library.
|
||
|
|
</p>
|
||
|
|
<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"></a>
|
||
|
|
<p>While linking a shared dll, <code>ld</code> is able to create a DEF file
|
||
|
|
with the ‘<samp>--output-def <file></samp>’ command-line option.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><em>Using decorations</em></dt>
|
||
|
|
<dd><a name="index-Using-decorations"></a>
|
||
|
|
<p>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:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">__declspec(dllexport) int a_variable
|
||
|
|
__declspec(dllexport) void a_function(int with_args)
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<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 ‘<samp>--export-all-symbols</samp>’ option is also used.
|
||
|
|
</p>
|
||
|
|
<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:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">__declspec(dllimport) int a_variable
|
||
|
|
__declspec(dllimport) void a_function(int with_args)
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<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
|
||
|
|
‘<samp>--enable-auto-import</samp>’ and ‘<samp>automatic data imports</samp>’ for more
|
||
|
|
information.
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<a name="index-automatic-data-imports"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><em>automatic data imports</em></dt>
|
||
|
|
<dd><p>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 ‘<samp>--enable-auto-import</samp>’
|
||
|
|
command-line option, although it is enabled by default on cygwin/mingw.
|
||
|
|
The ‘<samp>--enable-auto-import</samp>’ option itself now serves mainly to
|
||
|
|
suppress any warnings that are ordinarily emitted when linked objects
|
||
|
|
trigger the feature’s use.
|
||
|
|
</p>
|
||
|
|
<p>auto-import of variables does not always work flawlessly without
|
||
|
|
additional assistance. Sometimes, you will see this message
|
||
|
|
</p>
|
||
|
|
<p>"variable ’<var>’ can’t be auto-imported. Please read the
|
||
|
|
documentation for ld’s <code>--enable-auto-import</code> for details."
|
||
|
|
</p>
|
||
|
|
<p>The ‘<samp>--enable-auto-import</samp>’ 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"></a>
|
||
|
|
<p>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>
|
||
|
|
<p>The ‘<samp>--enable-runtime-pseudo-relocs</samp>’ 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>
|
||
|
|
<p>‘<samp>--enable-runtime-pseudo-relocs</samp>’ is not the default; it must be explicitly
|
||
|
|
enabled as needed.
|
||
|
|
</p>
|
||
|
|
<a name="index-direct-linking-to-a-dll"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><em>direct linking to a dll</em></dt>
|
||
|
|
<dd><p>The cygwin/mingw ports of <code>ld</code> 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 <code>ld</code> 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>
|
||
|
|
<p>Linking directly to a dll uses no extra command-line switches other than
|
||
|
|
‘<samp>-L</samp>’ and ‘<samp>-l</samp>’, because <code>ld</code> 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>
|
||
|
|
|
||
|
|
<p>For instance, when ld is called with the argument ‘<samp>-lxxx</samp>’ it will attempt
|
||
|
|
to find, in the first directory of its search path,
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">libxxx.dll.a
|
||
|
|
xxx.dll.a
|
||
|
|
libxxx.a
|
||
|
|
xxx.lib
|
||
|
|
libxxx.lib
|
||
|
|
cygxxx.dll (*)
|
||
|
|
libxxx.dll
|
||
|
|
xxx.dll
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>before moving on to the next directory in the search path.
|
||
|
|
</p>
|
||
|
|
<p>(*) Actually, this is not ‘<samp>cygxxx.dll</samp>’ but in fact is ‘<samp><prefix>xxx.dll</samp>’,
|
||
|
|
where ‘<samp><prefix></samp>’ is set by the <code>ld</code> option
|
||
|
|
‘<samp>--dll-search-prefix=<prefix></samp>’. In the case of cygwin, the standard gcc spec
|
||
|
|
file includes ‘<samp>--dll-search-prefix=cyg</samp>’, so in effect we actually search for
|
||
|
|
‘<samp>cygxxx.dll</samp>’.
|
||
|
|
</p>
|
||
|
|
<p>Other win32-based unix environments, such as mingw or pw32, may use other
|
||
|
|
‘<samp><prefix></samp>’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>
|
||
|
|
<p>The generic cygwin/mingw path layout uses a ‘<samp>bin</samp>’ directory for
|
||
|
|
applications and dll’s and a ‘<samp>lib</samp>’ directory for the import
|
||
|
|
libraries (using cygwin nomenclature):
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">bin/
|
||
|
|
cygxxx.dll
|
||
|
|
lib/
|
||
|
|
libxxx.dll.a (in case of dll's)
|
||
|
|
libxxx.a (in case of static archive)
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>Linking directly to a dll without using the import library can be
|
||
|
|
done two ways:
|
||
|
|
</p>
|
||
|
|
<p>1. Use the dll directly by adding the ‘<samp>bin</samp>’ path to the link line
|
||
|
|
</p><div class="example">
|
||
|
|
<pre class="example">gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>However, as the dll’s often have version numbers appended to their names
|
||
|
|
(‘<samp>cygncurses-5.dll</samp>’) this will often fail, unless one specifies
|
||
|
|
‘<samp>-L../bin -lncurses-5</samp>’ to include the version. Import libs are generally
|
||
|
|
not versioned, and do not have this difficulty.
|
||
|
|
</p>
|
||
|
|
<p>2. Create a symbolic link from the dll to a file in the ‘<samp>lib</samp>’
|
||
|
|
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.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>Then you can link without any make environment changes.
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>This technique also avoids the version number problems, because the following is
|
||
|
|
perfectly legal
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">bin/
|
||
|
|
cygxxx-5.dll
|
||
|
|
lib/
|
||
|
|
libxxx.dll.a -> ../bin/cygxxx-5.dll
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>Linking directly to a dll without using an import lib will work
|
||
|
|
even when auto-import features are exercised, and even when
|
||
|
|
‘<samp>--enable-runtime-pseudo-relocs</samp>’ is used.
|
||
|
|
</p>
|
||
|
|
<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>
|
||
|
|
<p>1. Until recently, the link-directly-to-dll functionality did <em>not</em>
|
||
|
|
work with auto-imported data.
|
||
|
|
</p>
|
||
|
|
<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>
|
||
|
|
<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>
|
||
|
|
<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.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><em>symbol aliasing</em></dt>
|
||
|
|
<dd><dl compact="compact">
|
||
|
|
<dt><em>adding additional names</em></dt>
|
||
|
|
<dd><p>Sometimes, it is useful to export symbols with additional names.
|
||
|
|
A symbol ‘<samp>foo</samp>’ will be exported as ‘<samp>foo</samp>’, but it can also be
|
||
|
|
exported as ‘<samp>_foo</samp>’ 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:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">LIBRARY "xyz.dll" BASE=0x61000000
|
||
|
|
|
||
|
|
EXPORTS
|
||
|
|
foo
|
||
|
|
_foo = foo
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>The line ‘<samp>_foo = foo</samp>’ maps the symbol ‘<samp>foo</samp>’ to ‘<samp>_foo</samp>’.
|
||
|
|
</p>
|
||
|
|
<p>Another method for creating a symbol alias is to create it in the
|
||
|
|
source code using the "weak" attribute:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">void foo () { /* Do something. */; }
|
||
|
|
void _foo () __attribute__ ((weak, alias ("foo")));
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>See the gcc manual for more information about attributes and weak
|
||
|
|
symbols.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
<dt><em>renaming symbols</em></dt>
|
||
|
|
<dd><p>Sometimes it is useful to rename exports. For instance, the cygwin
|
||
|
|
kernel does this regularly. A symbol ‘<samp>_foo</samp>’ can be exported as
|
||
|
|
‘<samp>foo</samp>’ but not as ‘<samp>_foo</samp>’ by using special directives in the
|
||
|
|
DEF file. (This will also affect the import library, if it is
|
||
|
|
created). In the following example:
|
||
|
|
</p>
|
||
|
|
<div class="example">
|
||
|
|
<pre class="example">LIBRARY "xyz.dll" BASE=0x61000000
|
||
|
|
|
||
|
|
EXPORTS
|
||
|
|
_foo = foo
|
||
|
|
</pre></div>
|
||
|
|
|
||
|
|
<p>The line ‘<samp>_foo = foo</samp>’ maps the exported symbol ‘<samp>foo</samp>’ to
|
||
|
|
‘<samp>_foo</samp>’.
|
||
|
|
</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>Note: using a DEF file disables the default auto-export behavior,
|
||
|
|
unless the ‘<samp>--export-all-symbols</samp>’ 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
|
||
|
|
‘<samp>--export-all-symbols</samp>’ option. If you list only the
|
||
|
|
renamed symbols in the DEF file, and use ‘<samp>--export-all-symbols</samp>’
|
||
|
|
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"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><em>weak externals</em></dt>
|
||
|
|
<dd><p>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:
|
||
|
|
</p><ul>
|
||
|
|
<li> Definition is searched for in objects and libraries, historically
|
||
|
|
called lazy externals.
|
||
|
|
</li><li> Definition is searched for only in other objects, not in libraries.
|
||
|
|
This form is not presently implemented.
|
||
|
|
</li><li> No search; the symbol is an alias. This form is not presently
|
||
|
|
implemented.
|
||
|
|
</li></ul>
|
||
|
|
<p>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.
|
||
|
|
</p>
|
||
|
|
<a name="index-aligned-common-symbols"></a>
|
||
|
|
</dd>
|
||
|
|
<dt><em>aligned common symbols</em></dt>
|
||
|
|
<dd><p>As a GNU extension to the PE file format, it is possible to specify the
|
||
|
|
desired alignment for a common symbol. This information is conveyed from
|
||
|
|
the assembler or compiler to the linker by means of GNU-specific commands
|
||
|
|
carried in the object file’s ‘<samp>.drectve</samp>’ section, which are recognized
|
||
|
|
by <code>ld</code> and respected when laying out the common symbols. Native
|
||
|
|
tools will be able to process object files employing this GNU extension,
|
||
|
|
but will fail to respect the alignment instructions, and may issue noisy
|
||
|
|
warnings about unknown linker directives.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<div class="header">
|
||
|
|
<p>
|
||
|
|
Next: <a href="Xtensa.html#Xtensa" accesskey="n" rel="next">Xtensa</a>, Previous: <a href="TI-COFF.html#TI-COFF" accesskey="p" rel="prev">TI COFF</a>, Up: <a href="Machine-Dependent.html#Machine-Dependent" accesskey="u" rel="up">Machine Dependent</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="LD-Index.html#LD-Index" title="Index" rel="index">Index</a>]</p>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|