Re: ld-auto-import documentation update

[Charles Wilson <cwilson at ece dot gatech dot edu>]

Ralf --
  comments and suggested changes interposed throughout.  You're right, 
the documentation of this subject could stand to be improved from what 
exists now, and your changes make a good start in that direction.

--Chuck


Ralf Habacker wrote:

> Node:WIN32, Previous:TI COFF, Up:Machine Dependent
> --------------------------------------------------------------------------------
>
> ld and WIN32 (cygwin/mingw)
> This section describes some of the win32 specific ld issuses.
>
> import libaries
> Standard windows linker creates and uses so called import libraries, which
> contains stuff for linking to dll's. 
Stuff?  STUFF?  Let's be a *little* less colloquial, okay?

> They are regular static archives and could
> be handled as any other static archive. 
could be?  they *are*.  (below: 'chas' typo?)

> The cygwin/mingw ports of chas specific
> support for creating such libraries provided with the --out-implib command line
> option.
> automatic data imports
> The standard windows dll format supports data imports from dlls only by adding
> special decorations (dllimport/dllexport), which lets the compiler produce
decorations (plural) --> let (not lets).  (subject verb agreement)

> specific assembler instructions to deal with this issue. This increase the
increases

> needed porting efforts, especially for big c++ libraries and applications. The
> auto-import feature, which was initial provided by Paul Sokolovsky, allows to
...allows one to omit the decorations to achieve a behavior that 
conforms to that on posix/unix platforms...
not
...allows to skit this decoration to archive a behavior more like ld on 
other platforms does...

> skip this decoration to archive a behavior more like ld on other platforms does
> This feature could be performed with the --enable-auto-import command-line
> option.
^^^^ blech.

"This feature is enabled by the --enable-auto-import command-line 
option, although it is enabled by default on cygwin/mingw.  The 
--enable-auto-import option itself now serves mainly to supporess any 
warnings that are ordinarily emitted when linked objects trigger the 
feature's use."

You also need a section that talks about runtime pseudo-relocs (e.g. and 
why it is needed.  For instance:

auto-import of variables does not always work flawlessly without 
additional assistance.  Sometimes, you will see this message

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

The --enable-auto-import documentation explains why this error occrus, 
and several methods that can be used to overcome this difficulty.  One 
of these methods is the 'runtime pseudo-relocs' feature, described below.

runtime pseudo-relocs
For complex variables imported from DLLs (such as structs or classes), 
object files typically contain a base address for the variable and an 
offset (`addend') 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 dllimort/dllexport 
decorations.  The standard auto-import feature described above is unable 
to resolve these references.

The --enable-runtime-pseudo-relocs 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 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 'old' system.

--enable-runtime-pseudo-relocs is not the default; it must be explicitly 
enabled as needed.

> direct linking to a dll
> The cygwin/mingw port of ld supports direct linking (including data symbols) to
> a dll without the usage of any import libraries. 

> Using this features saves very
> much linking time and memory in case of bigger libaries or applications. 
Blech.  "This is much faster and uses much less memory than does the 
traditional importlib method, especially when linking large libraries or 
applications."{


> This is
> because bigger libaries, especially c++ libaries, gets very huge import libaries
> (I have seen import libraries about 10 MB size).
Actually, that's not really *why*.  The "why" is:

When ld 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.

> Linking directly to a dll could be done with the already known command line
> options -L and -l.   This is because ld has built in support for
> several library names. See below, where xxx means the basic library
> name like "png" for the png library:

Linking directly to a dll uses no extra command line switches other than 
-L and -l, because ld 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.

For instance, when ld is called with the argument '-lxxx', it will 
attempt to find, in the first directory of its search path,

> libxxx.dll.a
> xxx.dll.a
> libxxx.a
> cygxxx.dll(*)


> libxxx.dll
> xxx.dll
before moving on to the next directory in the search path.

(*) Actually, '<prefix>xxx.dll' where <prefix> is set by the ld option 
'--dll-search-prefix=<prefix>'.  In the case of cygwin, the standard gcc 
spec file includes '--dll-search-prefix=cyg', so in effect we actually 
search for 'cygxxx.dll'

Other win32-based unix environments, such as mingw or pw32, may use 
other <prefix>es, although at present only cygwin makes use of this 
feature.  It was originally intended to help avoid name conflicts among 
dlls built for the various win32/unix environments, so that (for 
example) two versions of a zlib dll could coexist on the same machine.

> The generic cygwin/mingw path layout uses a bin directory for applications and
> dll's and a lib directory for the import libraries

(using cygwin nomenclature):


> bin/
> 	cygxxx.dll
>
> lib/
> 	libxxx.dll.a   (in case of dll's)
> 	libxxx.a       (in case of static archive)
>
> Linking to a dll could be done by two ways:
>
> 1. use the dll directly by adding the bin path to the link line
>
>
> gcc -Wl,-verbose  -o a.exe -L../bin/ -lxxx
However, as the dlls often have version numbers appended to their names 
('cygncurses-5.dll') this will often fail, unless one specifies 
'-L../bin/ -lncurses-5' to include the version.  Import libs are 
generally not versioned, and do not have this difficulty.

> 2. create a symbolic link from the dll to a file in the lib dir according to the
> above mentioned search pattern. This should be used to avoid unwanted changes in
> the tools needed for making the app/dll.
>
>
> ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
>
> Then you can link without any make environment changes.
> gcc -Wl,-verbose  -o a.exe -L../lib/ -lxxx

This technique also avoids the version number problems, because the 
following is perfectly legal:

bin/cygncurses-5.dll
lib/libncurses.dll.a -> bin/cygncurses-5.dll

--Chuck