ld: WIN32
1
1 4.17 'ld' and WIN32 (cygwin/mingw)
1 ==================================
1
1 This section describes some of the win32 specific 'ld' issues. See
1 ⇒Command Line Options Options. for detailed description of the
1 command line options mentioned here.
1
1 _import libraries_
1 The standard Windows linker creates and uses so-called import
1 libraries, which contains information for linking to dll's. They
1 are regular static archives and are handled as any other static
1 archive. The cygwin and mingw ports of 'ld' have specific support
1 for creating such libraries provided with the '--out-implib'
1 command line option.
1
1 _exporting DLL symbols_
1 The cygwin/mingw 'ld' has several ways to export symbols for dll's.
1
1 _using auto-export functionality_
1 By default 'ld' exports symbols with the auto-export
1 functionality, which is controlled by the following command
1 line options:
1
1 * -export-all-symbols [This is the default]
1 * -exclude-symbols
1 * -exclude-libs
1 * -exclude-modules-for-implib
1 * -version-script
1
1 When auto-export is in operation, 'ld' will export all the
1 non-local (global and common) symbols it finds in a DLL, with
1 the exception of a few symbols known to belong to the system's
1 runtime and libraries. As it will often not be desirable to
1 export all of a DLL's symbols, which may include private
1 functions that are not part of any public interface, the
1 command-line options listed above may be used to filter
1 symbols out from the list for exporting. The '--output-def'
1 option can be used in order to see the final list of exported
1 symbols with all exclusions taken into effect.
1
1 If '--export-all-symbols' is not given explicitly on the
1 command line, then the default auto-export behavior will be
1 _disabled_ if either of the following are true:
1
1 * A DEF file is used.
1 * Any symbol in any object file was marked with the
1 __declspec(dllexport) attribute.
1
1 _using a DEF file_
1 Another way of exporting symbols is using a DEF file. A DEF
1 file is an ASCII file containing definitions of symbols which
1 should be exported when a dll is created. Usually it is named
1 '<dll name>.def' and is added as any other object file to the
1 linker's command line. The file's name must end in '.def' or
1 '.DEF'.
1
1 gcc -o <output> <objectfiles> <dll name>.def
1
1 Using a DEF file turns off the normal auto-export behavior,
1 unless the '--export-all-symbols' option is also used.
1
1 Here is an example of a DEF file for a shared library called
1 'xyz.dll':
1
1 LIBRARY "xyz.dll" BASE=0x20000000
1
1 EXPORTS
1 foo
1 bar
1 _bar = bar
1 another_foo = abc.dll.afoo
1 var1 DATA
1 doo = foo == foo2
1 eoo DATA == var1
1
1 This example defines a DLL with a non-default base address and
1 seven symbols in the export table. The third exported symbol
1 '_bar' is an alias for the second. The fourth symbol,
1 'another_foo' is resolved by "forwarding" to another module
1 and treating it as an alias for 'afoo' exported from the DLL
1 'abc.dll'. The final symbol 'var1' is declared to be a data
1 object. The 'doo' symbol in export library is an alias of
1 'foo', which gets the string name in export table 'foo2'. The
1 'eoo' symbol is an data export symbol, which gets in export
1 table the name 'var1'.
1
1 The optional 'LIBRARY <name>' command indicates the _internal_
1 name of the output DLL. If '<name>' does not include a suffix,
1 the default library suffix, '.DLL' is appended.
1
1 When the .DEF file is used to build an application, rather
1 than a library, the 'NAME <name>' command should be used
1 instead of 'LIBRARY'. If '<name>' does not include a suffix,
1 the default executable suffix, '.EXE' is appended.
1
1 With either 'LIBRARY <name>' or 'NAME <name>' the optional
1 specification 'BASE = <number>' may be used to specify a
1 non-default base address for the image.
1
1 If neither 'LIBRARY <name>' nor 'NAME <name>' is specified, or
1 they specify an empty string, the internal name is the same as
1 the filename specified on the command line.
1
1 The complete specification of an export symbol is:
1
1 EXPORTS
1 ( ( ( <name1> [ = <name2> ] )
1 | ( <name1> = <module-name> . <external-name>))
1 [ @ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] [== <name3>] ) *
1
1 Declares '<name1>' as an exported symbol from the DLL, or
1 declares '<name1>' as an exported alias for '<name2>'; or
1 declares '<name1>' as a "forward" alias for the symbol
1 '<external-name>' in the DLL '<module-name>'. Optionally, the
1 symbol may be exported by the specified ordinal '<integer>'
1 alias. The optional '<name3>' is the to be used string in
1 import/export table for the symbol.
1
1 The optional keywords that follow the declaration indicate:
1
1 'NONAME': Do not put the symbol name in the DLL's export
1 table. It will still be exported by its ordinal alias (either
1 the value specified by the .def specification or, otherwise,
1 the value assigned by the linker). The symbol name, however,
1 does remain visible in the import library (if any), unless
1 'PRIVATE' is also specified.
1
1 'DATA': The symbol is a variable or object, rather than a
1 function. The import lib will export only an indirect
1 reference to 'foo' as the symbol '_imp__foo' (ie, 'foo' must
1 be resolved as '*_imp__foo').
1
1 'CONSTANT': Like 'DATA', but put the undecorated 'foo' as well
1 as '_imp__foo' into the import library. Both refer to the
1 read-only import address table's pointer to the variable, not
1 to the variable itself. This can be dangerous. If the user
1 code fails to add the 'dllimport' attribute and also fails to
1 explicitly add the extra indirection that the use of the
1 attribute enforces, the application will behave unexpectedly.
1
1 'PRIVATE': Put the symbol in the DLL's export table, but do
1 not put it into the static import library used to resolve
1 imports at link time. The symbol can still be imported using
1 the 'LoadLibrary/GetProcAddress' API at runtime or by using
1 the GNU ld extension of linking directly to the DLL without an
1 import library.
1
1 See ld/deffilep.y in the binutils sources for the full
1 specification of other DEF file statements
1
1 While linking a shared dll, 'ld' is able to create a DEF file
1 with the '--output-def <file>' command line option.
1
1 _Using decorations_
1 Another way of marking symbols for export is to modify the
1 source code itself, so that when building the DLL each symbol
1 to be exported is declared as:
1
1 __declspec(dllexport) int a_variable
1 __declspec(dllexport) void a_function(int with_args)
1
1 All such symbols will be exported from the DLL. If, however,
1 any of the object files in the DLL contain symbols decorated
1 in this way, then the normal auto-export behavior is disabled,
1 unless the '--export-all-symbols' option is also used.
1
1 Note that object files that wish to access these symbols must
1 _not_ decorate them with dllexport. Instead, they should use
1 dllimport, instead:
1
1 __declspec(dllimport) int a_variable
1 __declspec(dllimport) void a_function(int with_args)
1
1 This complicates the structure of library header files,
1 because when included by the library itself the header must
1 declare the variables and functions as dllexport, but when
1 included by client code the header must declare them as
1 dllimport. There are a number of idioms that are typically
1 used to do this; often client code can omit the __declspec()
1 declaration completely. See '--enable-auto-import' and
1 'automatic data imports' for more information.
1
1 _automatic data imports_
1 The standard Windows dll format supports data imports from dlls
1 only by adding special decorations (dllimport/dllexport), which let
1 the compiler produce specific assembler instructions to deal with
1 this issue. This increases the effort necessary to port existing
1 Un*x code to these platforms, especially for large c++ libraries
1 and applications. The auto-import feature, which was initially
1 provided by Paul Sokolovsky, allows one to omit the decorations to
1 achieve a behavior that conforms to that on POSIX/Un*x platforms.
1 This feature is enabled with the '--enable-auto-import'
1 command-line option, although it is enabled by default on
1 cygwin/mingw. The '--enable-auto-import' option itself now serves
1 mainly to suppress any warnings that are ordinarily emitted when
1 linked objects trigger the feature's use.
1
1 auto-import of variables does not always work flawlessly without
1 additional assistance. Sometimes, you will see this message
1
1 "variable '<var>' can't be auto-imported. Please read the
1 documentation for ld's '--enable-auto-import' for details."
1
1 The '--enable-auto-import' documentation explains why this error
1 occurs, and several methods that can be used to overcome this
1 difficulty. One of these methods is the _runtime pseudo-relocs_
1 feature, described below.
1
1 For complex variables imported from DLLs (such as structs or
1 classes), object files typically contain a base address for the
1 variable and an offset (_addend_) within the variable-to specify a
1 particular field or public member, for instance. Unfortunately,
1 the runtime loader used in win32 environments is incapable of
1 fixing these references at runtime without the additional
1 information supplied by dllimport/dllexport decorations. The
1 standard auto-import feature described above is unable to resolve
1 these references.
1
1 The '--enable-runtime-pseudo-relocs' switch allows these references
1 to be resolved without error, while leaving the task of adjusting
1 the references themselves (with their non-zero addends) to
1 specialized code provided by the runtime environment. Recent
1 versions of the cygwin and mingw environments and compilers provide
1 this runtime support; older versions do not. However, the support
1 is only necessary on the developer's platform; the compiled result
1 will run without error on an older system.
1
1 '--enable-runtime-pseudo-relocs' is not the default; it must be
1 explicitly enabled as needed.
1
1 _direct linking to a dll_
1 The cygwin/mingw ports of 'ld' support the direct linking,
1 including data symbols, to a dll without the usage of any import
1 libraries. This is much faster and uses much less memory than does
1 the traditional import library method, especially when linking
1 large libraries or applications. When 'ld' creates an import lib,
1 each function or variable exported from the dll is stored in its
1 own bfd, even though a single bfd could contain many exports. The
1 overhead involved in storing, loading, and processing so many bfd's
1 is quite large, and explains the tremendous time, memory, and
1 storage needed to link against particularly large or complex
1 libraries when using import libs.
1
1 Linking directly to a dll uses no extra command-line switches other
1 than '-L' and '-l', because 'ld' already searches for a number of
1 names to match each library. All that is needed from the
1 developer's perspective is an understanding of this search, in
1 order to force ld to select the dll instead of an import library.
1
1 For instance, when ld is called with the argument '-lxxx' it will
1 attempt to find, in the first directory of its search path,
1
1 libxxx.dll.a
1 xxx.dll.a
1 libxxx.a
1 xxx.lib
1 cygxxx.dll (*)
1 libxxx.dll
1 xxx.dll
1
1 before moving on to the next directory in the search path.
1
1 (*) Actually, this is not 'cygxxx.dll' but in fact is
1 '<prefix>xxx.dll', where '<prefix>' is set by the 'ld' option
1 '--dll-search-prefix=<prefix>'. In the case of cygwin, the
1 standard gcc spec file includes '--dll-search-prefix=cyg', so in
1 effect we actually search for 'cygxxx.dll'.
1
1 Other win32-based unix environments, such as mingw or pw32, may use
1 other '<prefix>'es, although at present only cygwin makes use of
1 this feature. It was originally intended to help avoid name
1 conflicts among dll's built for the various win32/un*x
1 environments, so that (for example) two versions of a zlib dll
1 could coexist on the same machine.
1
1 The generic cygwin/mingw path layout uses a 'bin' directory for
1 applications and dll's and a 'lib' directory for the import
1 libraries (using cygwin nomenclature):
1
1 bin/
1 cygxxx.dll
1 lib/
1 libxxx.dll.a (in case of dll's)
1 libxxx.a (in case of static archive)
1
1 Linking directly to a dll without using the import library can be
1 done two ways:
1
1 1. Use the dll directly by adding the 'bin' path to the link line
1 gcc -Wl,-verbose -o a.exe -L../bin/ -lxxx
1
1 However, as the dll's often have version numbers appended to their
1 names ('cygncurses-5.dll') this will often fail, unless one
1 specifies '-L../bin -lncurses-5' to include the version. Import
1 libs are generally not versioned, and do not have this difficulty.
1
1 2. Create a symbolic link from the dll to a file in the 'lib'
1 directory according to the above mentioned search pattern. This
1 should be used to avoid unwanted changes in the tools needed for
1 making the app/dll.
1
1 ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
1
1 Then you can link without any make environment changes.
1
1 gcc -Wl,-verbose -o a.exe -L../lib/ -lxxx
1
1 This technique also avoids the version number problems, because the
1 following is perfectly legal
1
1 bin/
1 cygxxx-5.dll
1 lib/
1 libxxx.dll.a -> ../bin/cygxxx-5.dll
1
1 Linking directly to a dll without using an import lib will work
1 even when auto-import features are exercised, and even when
1 '--enable-runtime-pseudo-relocs' is used.
1
1 Given the improvements in speed and memory usage, one might
1 justifiably wonder why import libraries are used at all. There are
1 three reasons:
1
1 1. Until recently, the link-directly-to-dll functionality did
1 _not_ work with auto-imported data.
1
1 2. Sometimes it is necessary to include pure static objects within
1 the import library (which otherwise contains only bfd's for
1 indirection symbols that point to the exports of a dll). Again,
1 the import lib for the cygwin kernel makes use of this ability, and
1 it is not possible to do this without an import lib.
1
1 3. Symbol aliases can only be resolved using an import lib. This
1 is critical when linking against OS-supplied dll's (eg, the win32
1 API) in which symbols are usually exported as undecorated aliases
1 of their stdcall-decorated assembly names.
1
1 So, import libs are not going away. But the ability to replace
1 true import libs with a simple symbolic link to (or a copy of) a
1 dll, in many cases, is a useful addition to the suite of tools
1 binutils makes available to the win32 developer. Given the massive
1 improvements in memory requirements during linking, storage
1 requirements, and linking speed, we expect that many developers
1 will soon begin to use this feature whenever possible.
1
1 _symbol aliasing_
1 _adding additional names_
1 Sometimes, it is useful to export symbols with additional
1 names. A symbol 'foo' will be exported as 'foo', but it can
1 also be exported as '_foo' by using special directives in the
1 DEF file when creating the dll. This will affect also the
1 optional created import library. Consider the following DEF
1 file:
1
1 LIBRARY "xyz.dll" BASE=0x61000000
1
1 EXPORTS
1 foo
1 _foo = foo
1
1 The line '_foo = foo' maps the symbol 'foo' to '_foo'.
1
1 Another method for creating a symbol alias is to create it in
1 the source code using the "weak" attribute:
1
1 void foo () { /* Do something. */; }
1 void _foo () __attribute__ ((weak, alias ("foo")));
1
1 See the gcc manual for more information about attributes and
1 weak symbols.
1
1 _renaming symbols_
1 Sometimes it is useful to rename exports. For instance, the
1 cygwin kernel does this regularly. A symbol '_foo' can be
1 exported as 'foo' but not as '_foo' by using special
1 directives in the DEF file. (This will also affect the import
1 library, if it is created). In the following example:
1
1 LIBRARY "xyz.dll" BASE=0x61000000
1
1 EXPORTS
1 _foo = foo
1
1 The line '_foo = foo' maps the exported symbol 'foo' to
1 '_foo'.
1
1 Note: using a DEF file disables the default auto-export behavior,
1 unless the '--export-all-symbols' command line option is used. If,
1 however, you are trying to rename symbols, then you should list
1 _all_ desired exports in the DEF file, including the symbols that
1 are not being renamed, and do _not_ use the '--export-all-symbols'
1 option. If you list only the renamed symbols in the DEF file, and
1 use '--export-all-symbols' to handle the other symbols, then the
1 both the new names _and_ the original names for the renamed symbols
1 will be exported. In effect, you'd be aliasing those symbols, not
1 renaming them, which is probably not what you wanted.
1
1 _weak externals_
1 The Windows object format, PE, specifies a form of weak symbols
1 called weak externals. When a weak symbol is linked and the symbol
1 is not defined, the weak symbol becomes an alias for some other
1 symbol. There are three variants of weak externals:
1 * Definition is searched for in objects and libraries,
1 historically called lazy externals.
1 * Definition is searched for only in other objects, not in
1 libraries. This form is not presently implemented.
1 * No search; the symbol is an alias. This form is not presently
1 implemented.
1 As a GNU extension, weak symbols that do not specify an alternate
1 symbol are supported. If the symbol is undefined when linking, the
1 symbol uses a default value.
1
1 _aligned common symbols_
1 As a GNU extension to the PE file format, it is possible to specify
1 the desired alignment for a common symbol. This information is
1 conveyed from the assembler or compiler to the linker by means of
1 GNU-specific commands carried in the object file's '.drectve'
1 section, which are recognized by 'ld' and respected when laying out
1 the common symbols. Native tools will be able to process object
1 files employing this GNU extension, but will fail to respect the
1 alignment instructions, and may issue noisy warnings about unknown
1 linker directives.
1