diff options
| -rw-r--r-- | ld/ChangeLog | 5 | ||||
| -rw-r--r-- | ld/ld.texinfo | 71 |
2 files changed, 68 insertions, 8 deletions
diff --git a/ld/ChangeLog b/ld/ChangeLog index 52b2467..bc2406a 100644 --- a/ld/ChangeLog +++ b/ld/ChangeLog @@ -1,3 +1,8 @@ +2002-01-14 Charles Wilson <cwilson@ece.gatech.edu> + + * ld/ld.texinfo (node WIN32): Some clarifications + and formatting fixups. + 2003-01-09 Chris Demetriou <cgd@broadcom.com> * ldmain.c (get_emulation): Sort -mipsNN checks in the usual diff --git a/ld/ld.texinfo b/ld/ld.texinfo index 8485024..b85c6bf 100644 --- a/ld/ld.texinfo +++ b/ld/ld.texinfo @@ -4480,11 +4480,20 @@ The cygwin/mingw @command{ld} has several ways to export symbols for dll's. By default @command{ld} exports symbols with the auto-export functionality, which is controlled by the following command line options: -@example ---export-all-symbols [This is the default] ---exclude-symbols ---exclude-libs -@end example +@itemize +@item --export-all-symbols [This is the default] +@item --exclude-symbols +@item --exclude-libs +@end itemize + +If, however, @samp{--export-all-symbols} is not given explicitly on the +command line, then the default auto-export behavior will be @emph{disabled} +if either of the following are true: + +@itemize +@item A DEF file is used. +@item Any symbol in any object file was marked with the __declspec(dllexport) attribute. +@end itemize @item using a DEF file @cindex using a DEF file @@ -4492,12 +4501,15 @@ 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{<dll name>.def} and is added as any other object file to the linker's -command line. +command line. The file's name must end in @samp{.def} or @samp{.DEF}. @example gcc -o <output> <objectfiles> <dll name>.def @end example +Using a DEF file turns off the normal auto-export behavior, unless the +@samp{--export-all-symbols} option is also used. + Here is an example of a DEF file for a shared library called @samp{xyz.dll}: @example @@ -4516,6 +4528,40 @@ specification see ld/deffilep.y in the binutils sources. @cindex creating a DEF file While linking a shared dll, @command{ld} is able to create a DEF file with the @samp{--output-def <file>} command line option. + +@item Using decorations +@cindex Using decorations +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: + +@example +__declspec(dllexport) int a_variable +__declspec(dllexport) void a_function(int with_args) +@end example + +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{--export-all-symbols} option is also used. + +Note that object files that wish to access these symbols must @emph{not} +decorate them with dllexport. Instead, they should use dllimport, +instead: + +@example +__declspec(dllimport) int a_variable +__declspec(dllimport) void a_function(int with_args) +@end example + +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{--enable-auto-import} and @samp{automatic data imports} for more +imformation. @end table @cindex automatic data imports @@ -4734,8 +4780,17 @@ The line @samp{_foo = foo} maps the exported symbol @samp{foo} to @samp{_foo}. @end table -Note: using a DEF file overrides any other symbol defining except you are -using the @samp{--export-all-symbols} command line options. +Note: using a DEF file disables the default auto-export behavior, +unless the @samp{--export-all-symbols} command line option is used. +If, however, you are trying to rename symbols, then you should list +@emph{all} desired exports in the DEF file, including the symbols +that are not being renamed, and do @emph{not} use the +@samp{--export-all-symbols} option. If you list only the +renamed symbols in the DEF file, and use @samp{--export-all-symbols} +to handle the other symbols, then the both the new names @emph{and} +the original names for the the renamed symbols will be exported. +In effect, you'd be aliasing those symbols, not renaming them, +which is probably not what you wanted. @end table @ifclear GENERIC |