Help: Document that SHARED libraries must export a symbol (#15775)

CMake assumes that a SHARED library compiled on Windows will export a LIB file.
This is not actually the case on Visual C++ if the library does not export any
symbols, and causes incremental builds to break if the user specifies SHARED
anyway.  (Users should use MODULE libraries instead.)

1 files changed, 6 insertions, 1 deletions

diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst
index 357aae9..bc633e6 100644
--- a/Help/manual/cmake-buildsystem.7.rst
+++ b/Help/manual/cmake-buildsystem.7.rst
@@ -80,6 +80,10 @@ regardless of the library type.  The ``MODULE`` library type is
 dissimilar in that it is generally not linked to -- it is not used in
 the right-hand-side of the :command:`target_link_libraries` command.
 It is a type which is loaded as a plugin using runtime techniques.
+If the library does not export any unmanaged symbols (e.g. Windows
+resource DLL, C++/CLI DLL), it is required that the library not be a
+``SHARED`` library because CMake expects ``SHARED`` libraries to export
+at least one symbol.
 
 .. code-block:: cmake
 
@@ -781,7 +785,8 @@ An *archive* output artifact of a buildsystem target may be:
 
 * On DLL platforms: the import library file (e.g. ``.lib``) of a shared
   library target created by the :command:`add_library` command
-  with the ``SHARED`` option.
+  with the ``SHARED`` option.  This file is only guaranteed to exist if
+  the library exports at least one unmanaged symbol.
 
 * On DLL platforms: the import library file (e.g. ``.lib``) of an
   executable target created by the :command:`add_executable` command