ld-auto-import documentation update

["Ralf Habacker" <Ralf dot Habacker at freenet dot de>]

Hi all,

I have added some documentation for the cygwin/mingw ld auto-import feature. Is
there anyone, who could check and apply this ?
I've added the patch and the raw text (mostly) for easier verifying.

Regards
Ralf



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. They are regular static archives and could
be handled as any other static archive. 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
specific assembler instructions to deal with this issue. This increase the
needed porting efforts, especially for big c++ libraries and applications. The
auto-import feature, which was initial provided by Paul Sokolovsky, allows to
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.

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. This is
because bigger libaries, especially c++ libaries, gets very huge import libaries
(I have seen import libraries about 10 MB size).
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:

libxxx.dll.a
xxx.dll.a
libxxx.a
cygxxx.dll
libxxx.dll
xxx.dll

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


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

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


--------------------------------------------------------------------------------
-------------------------------


ChangeLog
2002-12-18  Ralf Habacker  <ralf.habacker@freenet.de>

	* ld.texinfo: added win32 machine depending section
	* gen-doc.texi: enable win32 machine depending section

Attachment: ld-doc-auto-import.patch
Description: Binary data