aboutsummaryrefslogtreecommitdiff
path: root/ld
diff options
context:
space:
mode:
authorNick Clifton <nickc@redhat.com>2003-01-14 11:25:58 +0000
committerNick Clifton <nickc@redhat.com>2003-01-14 11:25:58 +0000
commit0a5d968ed10526baa98e48b7d43af0614ffd7c6f (patch)
treef73be939c5eaa0a1a8866850f4b0f0ea8d315baa /ld
parent6ca37014df7b9b072e686b1858102fa24e9ef930 (diff)
downloadfsf-binutils-gdb-0a5d968ed10526baa98e48b7d43af0614ffd7c6f.zip
fsf-binutils-gdb-0a5d968ed10526baa98e48b7d43af0614ffd7c6f.tar.gz
fsf-binutils-gdb-0a5d968ed10526baa98e48b7d43af0614ffd7c6f.tar.bz2
(node WIN32): Some clarifications and formatting fixups.
Diffstat (limited to 'ld')
-rw-r--r--ld/ChangeLog5
-rw-r--r--ld/ld.texinfo71
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