[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.1 Options Specific to i386 PE Targets

The i386 PE linker supports the `-shared' option, which causes the output to be a dynamically linked library (DLL) instead of a normal executable. You should name the output *.dll when you use this option. In addition, the linker fully supports the standard *.def files, which may be specified on the linker command line like an object file (in fact, it should precede archives it exports symbols from, to ensure that they get linked in, just like a normal object file).

In addition to the options common to all targets, the i386 PE linker support additional command line options that are specific to the i386 PE target. Options that take values may be separated from their values by either a space or an equals sign.

--add-stdcall-alias
If given, symbols with a stdcall suffix (@nn) will be exported as-is and also with the suffix stripped. [This option is specific to the i386 PE targeted port of the linker]

--base-file file
Use file as the name of a file in which to save the base addresses of all the relocations needed for generating DLLs with `dlltool'. [This is an i386 PE specific option]

--dll
Create a DLL instead of a regular executable. You may also use `-shared' or specify a LIBRARY in a given .def file. [This option is specific to the i386 PE targeted port of the linker]

--enable-stdcall-fixup
--disable-stdcall-fixup
If the link finds a symbol that it cannot resolve, it will attempt to do "fuzzy linking" by looking for another defined symbol that differs only in the format of the symbol name (cdecl vs stdcall) and will resolve that symbol by linking to the match. For example, the undefined symbol _foo might be linked to the function _foo@12, or the undefined symbol _bar@16 might be linked to the function _bar. When the linker does this, it prints a warning, since it normally should have failed to link, but sometimes import libraries generated from third-party dlls may need this feature to be usable. If you specify `--enable-stdcall-fixup', this feature is fully enabled and warnings are not printed. If you specify `--disable-stdcall-fixup', this feature is disabled and such mismatches are considered to be errors. [This option is specific to the i386 PE targeted port of the linker]

--export-all-symbols
If given, all global symbols in the objects used to build a DLL will be exported by the DLL. Note that this is the default if there otherwise wouldn't be any exported symbols. When symbols are explicitly exported via DEF files or implicitly exported via function attributes, the default is to not export anything else unless this option is given. Note that the symbols DllMain@12, DllEntryPoint@0, DllMainCRTStartup@12, and impure_ptr will not be automatically exported. Also, symbols imported from other DLLs will not be re-exported, nor will symbols specifying the DLL's internal layout such as those beginning with _head_ or ending with _iname. In addition, no symbols from libgcc, libstd++, libmingw32, or crtX.o will be exported. Symbols whose names begin with __rtti_ or __builtin_ will not be exported, to help with C++ DLLs. Finally, there is an extensive list of cygwin-private symbols that are not exported (obviously, this applies on when building DLLs for cygwin targets). These cygwin-excludes are: _cygwin_dll_entry@12, _cygwin_crt0_common@8, _cygwin_noncygwin_dll_entry@12, _fmode, _impure_ptr, cygwin_attach_dll, cygwin_premain0, cygwin_premain1, cygwin_premain2, cygwin_premain3, and environ. [This option is specific to the i386 PE targeted port of the linker]

--exclude-symbols symbol,symbol,...
Specifies a list of symbols which should not be automatically exported. The symbol names may be delimited by commas or colons. [This option is specific to the i386 PE targeted port of the linker]

--exclude-libs lib,lib,...
Specifies a list of archive libraries from which symbols should not be automatically exported. The library names may be delimited by commas or colons. Specifying --exclude-libs ALL excludes symbols in all archive libraries from automatic export. Symbols explicitly listed in a .def file are still exported, regardless of this option. [This option is specific to the i386 PE targeted port of the linker]

--file-alignment
Specify the file alignment. Sections in the file will always begin at file offsets which are multiples of this number. This defaults to 512. [This option is specific to the i386 PE targeted port of the linker]

--heap reserve
--heap reserve,commit
Specify the amount of memory to reserve (and optionally commit) to be used as heap for this program. The default is 1Mb reserved, 4K committed. [This option is specific to the i386 PE targeted port of the linker]

--image-base value
Use value as the base address of your program or dll. This is the lowest memory location that will be used when your program or dll is loaded. To reduce the need to relocate and improve performance of your dlls, each should have a unique base address and not overlap any other dlls. The default is 0x400000 for executables, and 0x10000000 for dlls. [This option is specific to the i386 PE targeted port of the linker]

--kill-at
If given, the stdcall suffixes (@nn) will be stripped from symbols before they are exported. [This option is specific to the i386 PE targeted port of the linker]

--major-image-version value
Sets the major number of the "image version". Defaults to 1. [This option is specific to the i386 PE targeted port of the linker]

--major-os-version value
Sets the major number of the "os version". Defaults to 4. [This option is specific to the i386 PE targeted port of the linker]

--major-subsystem-version value
Sets the major number of the "subsystem version". Defaults to 4. [This option is specific to the i386 PE targeted port of the linker]

--minor-image-version value
Sets the minor number of the "image version". Defaults to 0. [This option is specific to the i386 PE targeted port of the linker]

--minor-os-version value
Sets the minor number of the "os version". Defaults to 0. [This option is specific to the i386 PE targeted port of the linker]

--minor-subsystem-version value
Sets the minor number of the "subsystem version". Defaults to 0. [This option is specific to the i386 PE targeted port of the linker]

--output-def file
The linker will create the file file which will contain a DEF file corresponding to the DLL the linker is generating. This DEF file (which should be called *.def) may be used to create an import library with dlltool or may be used as a reference to automatically or implicitly exported symbols. [This option is specific to the i386 PE targeted port of the linker]

--out-implib file
The linker will create the file file which will contain an import lib corresponding to the DLL the linker is generating. This import lib (which should be called *.dll.a or *.a may be used to link clients against the generated DLL; this behavior makes it possible to skip a separate dlltool import library creation step. [This option is specific to the i386 PE targeted port of the linker]

--enable-auto-image-base
Automatically choose the image base for DLLs, unless one is specified using the --image-base argument. By using a hash generated from the dllname to create unique image bases for each DLL, in-memory collisions and relocations which can delay program execution are avoided. [This option is specific to the i386 PE targeted port of the linker]

--disable-auto-image-base
Do not automatically generate a unique image base. If there is no user-specified image base (--image-base) then use the platform default. [This option is specific to the i386 PE targeted port of the linker]

--dll-search-prefix string
When linking dynamically to a dll without an import library, search for <string><basename>.dll in preference to lib<basename>.dll. This behavior allows easy distinction between DLLs built for the various "subplatforms": native, cygwin, uwin, pw, etc. For instance, cygwin DLLs typically use --dll-search-prefix=cyg. [This option is specific to the i386 PE targeted port of the linker]

--enable-auto-import
Do sophisticated linking of _symbol to __imp__symbol for DATA imports from DLLs, and create the necessary thunking symbols when building the import libraries with those DATA exports. This generally will 'just work' -- but sometimes you may see this message:

"variable '<var>' can't be auto-imported. Please read the documentation for ld's --enable-auto-import for details."

This message occurs when some (sub)expression accesses an address ultimately given by the sum of two constants (Win32 import tables only allow one). Instances where this may occur include accesses to member fields of struct variables imported from a DLL, as well as using a constant index into an array variable imported from a DLL. Any multiword variable (arrays, structs, long long, etc) may trigger this error condition. However, regardless of the exact data type of the offending exported variable, ld will always detect it, issue the warning, and exit.

There are several ways to address this difficulty, regardless of the data type of the exported variable:

One way is to use --enable-runtime-pseudo-reloc switch. This leaves the task of adjusting references in your client code for runtime environment, so this method works only when runtime environtment supports this feature.

A second solution is to force one of the 'constants' to be a variable -- that is, unknown and un-optimizable at compile time. For arrays, there are two possibilities: a) make the indexee (the array's address) a variable, or b) make the 'constant' index a variable. Thus:

 
extern type extern_array[];
extern_array[1] --> 
   { volatile type *t=extern_array; t[1] }

or

 
extern type extern_array[];
extern_array[1] --> 
   { volatile int t=1; extern_array[t] }

For structs (and most other multiword data types) the only option is to make the struct itself (or the long long, or the ...) variable:

 
extern struct s extern_struct;
extern_struct.field --> 
   { volatile struct s *t=&extern_struct; t->field }

or

 
extern long long extern_ll;
extern_ll -->
  { volatile long long * local_ll=&extern_ll; *local_ll }

A third method of dealing with this difficulty is to abandon 'auto-import' for the offending symbol and mark it with __declspec(dllimport). However, in practice that requires using compile-time #defines to indicate whether you are building a DLL, building client code that will link to the DLL, or merely building/linking to a static library. In making the choice between the various methods of resolving the 'direct address with constant offset' problem, you should consider typical real-world usage:

Original:
 
--foo.h
extern int arr[];
--foo.c
#include "foo.h"
void main(int argc, char **argv){
  printf("%d\n",arr[1]);
}

Solution 1:
 
--foo.h
extern int arr[];
--foo.c
#include "foo.h"
void main(int argc, char **argv){
  /* This workaround is for win32 and cygwin; do not "optimize" */
  volatile int *parr = arr;
  printf("%d\n",parr[1]);
}

Solution 2:
 
--foo.h
/* Note: auto-export is assumed (no __declspec(dllexport)) */
#if (defined(_WIN32) || defined(__CYGWIN__)) && \
  !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
#define FOO_IMPORT __declspec(dllimport)
#else
#define FOO_IMPORT
#endif
extern FOO_IMPORT int arr[];
--foo.c
#include "foo.h"
void main(int argc, char **argv){
  printf("%d\n",arr[1]);
}

A fourth way to avoid this problem is to re-code your library to use a functional interface rather than a data interface for the offending variables (e.g. set_foo() and get_foo() accessor functions). [This option is specific to the i386 PE targeted port of the linker]

--disable-auto-import
Do not attempt to do sophisticalted linking of _symbol to __imp__symbol for DATA imports from DLLs. [This option is specific to the i386 PE targeted port of the linker]

--enable-runtime-pseudo-reloc
If your code contains expressions described in --enable-auto-import section, that is, DATA imports from DLL with non-zero offset, this switch will create a vector of 'runtime pseudo relocations' which can be used by runtime environment to adjust references to such data in your client code. [This option is specific to the i386 PE targeted port of the linker]

--disable-runtime-pseudo-reloc
Do not create pseudo relocations for non-zero offset DATA imports from DLLs. This is the default. [This option is specific to the i386 PE targeted port of the linker]

--enable-extra-pe-debug
Show additional debug info related to auto-import symbol thunking. [This option is specific to the i386 PE targeted port of the linker]

--section-alignment
Sets the section alignment. Sections in memory will always begin at addresses which are a multiple of this number. Defaults to 0x1000. [This option is specific to the i386 PE targeted port of the linker]

--stack reserve
--stack reserve,commit
Specify the amount of memory to reserve (and optionally commit) to be used as stack for this program. The default is 2Mb reserved, 4K committed. [This option is specific to the i386 PE targeted port of the linker]

--subsystem which
--subsystem which:major
--subsystem which:major.minor
Specifies the subsystem under which your program will execute. The legal values for which are native, windows, console, and posix. You may optionally set the subsystem version also. [This option is specific to the i386 PE targeted port of the linker]


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated by Guillaume Rousse on December, 12 2004 using texi2html