| <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.13"> |
| <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 Toolchain for the A-profile Architecture 9.2-2019.12 (arm-9.10)) |
| version 2.33.1. |
| |
| 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''.--> |
| <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; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="WIN32"></a> |
| <p> |
| 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> |
| </div> |
| |
| <h3 class="section">4.16 <samp><span class="command">ld</span></samp> and WIN32 (cygwin/mingw)</h3> |
| |
| <p>This section describes some of the win32 specific <samp><span class="command">ld</span></samp> 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-772"></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 <samp><span class="command">ld</span></samp> have specific |
| support for creating such libraries provided with the |
| ‘<samp><span class="samp">--out-implib</span></samp>’ command-line option. |
| |
| <br><dt><em>exporting DLL symbols</em><dd><a name="index-exporting-DLL-symbols-773"></a>The cygwin/mingw <samp><span class="command">ld</span></samp> 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-774"></a>By default <samp><span class="command">ld</span></samp> 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 |
| <li>–exclude-modules-for-implib |
| <li>–version-script |
| </ul> |
| |
| <p>When auto-export is in operation, <samp><span class="command">ld</span></samp> 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><span class="samp">--output-def</span></samp>’ option can be used in order to see the |
| final list of exported symbols with all exclusions taken into effect. |
| |
| <p>If ‘<samp><span class="samp">--export-all-symbols</span></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: |
| |
| <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-775"></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 ‘<samp><span class="samp"><dll |
| name>.def</span></samp>’ and is added as any other object file to the linker's |
| command line. The file's name must end in ‘<samp><span class="samp">.def</span></samp>’ or ‘<samp><span class="samp">.DEF</span></samp>’. |
| |
| <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 |
| ‘<samp><span class="samp">--export-all-symbols</span></samp>’ option is also used. |
| |
| <p>Here is an example of a DEF file for a shared library called ‘<samp><span class="samp">xyz.dll</span></samp>’: |
| |
| <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> |
| <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><span class="samp">abc.dll</span></samp>’. The final symbol |
| <code>var1</code> is declared to be a data object. The ‘<samp><span class="samp">doo</span></samp>’ symbol in |
| export library is an alias of ‘<samp><span class="samp">foo</span></samp>’, which gets the string name |
| in export table ‘<samp><span class="samp">foo2</span></samp>’. The ‘<samp><span class="samp">eoo</span></samp>’ symbol is an data export |
| symbol, which gets in export table the name ‘<samp><span class="samp">var1</span></samp>’. |
| |
| <p>The optional <code>LIBRARY <name></code> command indicates the <em>internal</em> |
| name of the output DLL. If ‘<samp><span class="samp"><name></span></samp>’ does not include a suffix, |
| the default library suffix, ‘<samp><span class="samp">.DLL</span></samp>’ 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 ‘<samp><span class="samp"><name></span></samp>’ does not include a suffix, the default |
| executable suffix, ‘<samp><span class="samp">.EXE</span></samp>’ 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] [== <name3>] ) * |
| </pre> |
| <p>Declares ‘<samp><span class="samp"><name1></span></samp>’ as an exported symbol from the DLL, or declares |
| ‘<samp><span class="samp"><name1></span></samp>’ as an exported alias for ‘<samp><span class="samp"><name2></span></samp>’; or declares |
| ‘<samp><span class="samp"><name1></span></samp>’ as a "forward" alias for the symbol |
| ‘<samp><span class="samp"><external-name></span></samp>’ in the DLL ‘<samp><span class="samp"><module-name></span></samp>’. |
| Optionally, the symbol may be exported by the specified ordinal |
| ‘<samp><span class="samp"><integer></span></samp>’ alias. The optional ‘<samp><span class="samp"><name3></span></samp>’ is the to be used |
| string in import/export table for the symbol. |
| |
| <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 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-776"></a>While linking a shared dll, <samp><span class="command">ld</span></samp> is able to create a DEF file |
| with the ‘<samp><span class="samp">--output-def <file></span></samp>’ command-line option. |
| |
| <br><dt><em>Using decorations</em><dd><a name="index-Using-decorations-777"></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 ‘<samp><span class="samp">--export-all-symbols</span></samp>’ 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 |
| ‘<samp><span class="samp">--enable-auto-import</span></samp>’ and ‘<samp><span class="samp">automatic data imports</span></samp>’ for more |
| information. |
| </dl> |
| |
| <p><a name="index-automatic-data-imports-778"></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 ‘<samp><span class="samp">--enable-auto-import</span></samp>’ |
| command-line option, although it is enabled by default on cygwin/mingw. |
| The ‘<samp><span class="samp">--enable-auto-import</span></samp>’ 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 ‘<samp><span class="samp">--enable-auto-import</span></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-779"></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 ‘<samp><span class="samp">--enable-runtime-pseudo-relocs</span></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>‘<samp><span class="samp">--enable-runtime-pseudo-relocs</span></samp>’ is not the default; it must be explicitly |
| enabled as needed. |
| |
| <p><a name="index-direct-linking-to-a-dll-780"></a><br><dt><em>direct linking to a dll</em><dd>The cygwin/mingw ports of <samp><span class="command">ld</span></samp> 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 <samp><span class="command">ld</span></samp> 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 |
| ‘<samp><span class="samp">-L</span></samp>’ and ‘<samp><span class="samp">-l</span></samp>’, because <samp><span class="command">ld</span></samp> 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 ‘<samp><span class="samp">-lxxx</span></samp>’ 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 |
| libxxx.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 ‘<samp><span class="samp">cygxxx.dll</span></samp>’ but in fact is ‘<samp><span class="samp"><prefix>xxx.dll</span></samp>’, |
| where ‘<samp><span class="samp"><prefix></span></samp>’ is set by the <samp><span class="command">ld</span></samp> option |
| ‘<samp><span class="samp">--dll-search-prefix=<prefix></span></samp>’. In the case of cygwin, the standard gcc spec |
| file includes ‘<samp><span class="samp">--dll-search-prefix=cyg</span></samp>’, so in effect we actually search for |
| ‘<samp><span class="samp">cygxxx.dll</span></samp>’. |
| |
| <p>Other win32-based unix environments, such as mingw or pw32, may use other |
| ‘<samp><span class="samp"><prefix></span></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>The generic cygwin/mingw path layout uses a ‘<samp><span class="samp">bin</span></samp>’ directory for |
| applications and dll's and a ‘<samp><span class="samp">lib</span></samp>’ 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 ‘<samp><span class="samp">bin</span></samp>’ 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 |
| (‘<samp><span class="samp">cygncurses-5.dll</span></samp>’) this will often fail, unless one specifies |
| ‘<samp><span class="samp">-L../bin -lncurses-5</span></samp>’ 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 ‘<samp><span class="samp">lib</span></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. |
| |
| <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 |
| ‘<samp><span class="samp">--enable-runtime-pseudo-relocs</span></samp>’ 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 ‘<samp><span class="samp">foo</span></samp>’ will be exported as ‘<samp><span class="samp">foo</span></samp>’, but it can also be |
| exported as ‘<samp><span class="samp">_foo</span></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: |
| |
| <pre class="example"> LIBRARY "xyz.dll" BASE=0x61000000 |
| |
| EXPORTS |
| foo |
| _foo = foo |
| </pre> |
| <p>The line ‘<samp><span class="samp">_foo = foo</span></samp>’ maps the symbol ‘<samp><span class="samp">foo</span></samp>’ to ‘<samp><span class="samp">_foo</span></samp>’. |
| |
| <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 ‘<samp><span class="samp">_foo</span></samp>’ can be exported as |
| ‘<samp><span class="samp">foo</span></samp>’ but not as ‘<samp><span class="samp">_foo</span></samp>’ 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 ‘<samp><span class="samp">_foo = foo</span></samp>’ maps the exported symbol ‘<samp><span class="samp">foo</span></samp>’ to |
| ‘<samp><span class="samp">_foo</span></samp>’. |
| </dl> |
| |
| <p>Note: using a DEF file disables the default auto-export behavior, |
| unless the ‘<samp><span class="samp">--export-all-symbols</span></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><span class="samp">--export-all-symbols</span></samp>’ option. If you list only the |
| renamed symbols in the DEF file, and use ‘<samp><span class="samp">--export-all-symbols</span></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-781"></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. |
| |
| <p><a name="index-aligned-common-symbols-782"></a><br><dt><em>aligned common symbols</em><dd>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><span class="samp">.drectve</span></samp>’ section, which are recognized |
| by <samp><span class="command">ld</span></samp> 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. |
| |
| </dl> |
| |
| </body></html> |
| |