aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2021-10-14 09:06:50 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2021-10-14 09:06:50 +0200
commit4ae6c2fe91d8dc5bdb7f6d9808b097dde8a8265f (patch)
tree06ae11143ba24415188afc1e0352d29e5278ef1d
parentc08bf939d0d9ee475f5553135ad4dbe3e5684f3b (diff)
Move symbol exporting documentation from NEWS to manual
-rw-r--r--NEWS30
-rw-r--r--doc/manual.cli46
2 files changed, 49 insertions, 27 deletions
diff --git a/NEWS b/NEWS
index 48664e2..9f655ac 100644
--- a/NEWS
+++ b/NEWS
@@ -119,33 +119,9 @@ Version 0.14.0
* Support for automatic DLL symbol exporting.
- The bin.def module (automatically loaded by the c and cxx modules for the
- *-win32-msvc targets) provides a rule for generating symbol-exporting .def
- files. This allows automatically exporting all symbols for all the Windows
- targets/compilers using the following setup (showing for cxx in this
- example):
-
- lib{foo}: libul{foo}: {hxx cxx}{**} ...
-
- lib{foo}: def{foo}: include = ($cxx.target.system == 'win32-msvc')
- def{foo}: libul{foo}
-
- if ($cxx.target.system == 'mingw32')
- cxx.loptions += -Wl,--export-all-symbols
-
- That is, we use the .def file generation for MSVC (including when building
- with Clang) and the built-in support (--export-all-symbols) for MinGW.
-
- Note that it is also possible to use the .def file generation for MinGW.
- In this case we need to explicitly load the bin.def module (which should
- be done after loading c or cxx) and can use the following setup:
-
- using bin.def # In root.build after loading c/cxx.
-
- lib{foo}: libul{foo}: {hxx cxx}{**} ...
-
- lib{foo}: def{foo}: include = ($cxx.target.class == 'windows')
- def{foo}: libul{foo}
+ It is now possible to automatically generate a .def file that exports all
+ symbols from a Windows DLL. See "Automatic DLL Symbol Exporting" in the
+ manual for details.
* Initial Emscripten compiler support.
diff --git a/doc/manual.cli b/doc/manual.cli
index d63e887..e941b6b 100644
--- a/doc/manual.cli
+++ b/doc/manual.cli
@@ -6640,6 +6640,52 @@ otherwise share the same header search paths, for example, as a family of
libraries), then the whitelist may not be effective.
+\h#cc-auto-symexport|Automatic DLL Symbol Exporting|
+
+The \c{bin.def} module (automatically loaded by the \c{c} and \c{cxx} modules
+for the \c{*-win32-msvc} targets) provides a rule for generating
+symbol-exporting \c{.def} files. This allows automatically exporting all
+symbols for all the Windows targets/compilers using the following arrangement
+(showing for \c{cxx} in this example):
+
+\
+lib{foo}: libul{foo}: {hxx cxx}{**} ...
+
+lib{foo}: def{foo}: include = ($cxx.target.system == 'win32-msvc')
+def{foo}: libul{foo}
+
+if ($cxx.target.system == 'mingw32')
+ cxx.loptions += -Wl,--export-all-symbols
+\
+
+That is, we use the \c{.def} file approach for MSVC (including when building
+with Clang) and the built-in support (\c{--export-all-symbols}) for MinGW.
+
+Note that it is also possible to use the \c{.def} file approach for MinGW. In
+this case we need to explicitly load the \c{bin.def} module (which should be
+done after loading \c{c} or \c{cxx}) and can use the following arrangement:
+
+\
+# root.build
+
+using cxx
+using bin.def
+\
+
+\
+lib{foo}: libul{foo}: {hxx cxx}{**} ...
+
+lib{foo}: def{foo}: include = ($cxx.target.class == 'windows')
+def{foo}: libul{foo}
+\
+
+Note also that this only deals with exporting of the symbols from a DLL. In
+order to work, code that uses such a DLL should be able to import the symbols
+without explicit \c{__declspec(dllimport)} declarations. This works thanks
+to the symbol auto-importing support in Windows linkers. Note, however, that
+auto-importing only works for functions and not for global variables.
+
+
\h#cc-gcc|GCC Compiler Toolchain|
The GCC compiler id is \c{gcc}.