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.)

2 files changed, 12 insertions, 1 deletions

diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst
index fe7735c6b5..5033e1869d 100644
--- a/Help/command/add_library.rst
+++ b/Help/command/add_library.rst
@@ -36,6 +36,12 @@ property is set to ``ON`` automatically.
 A ``SHARED`` library may be marked with the :prop_tgt:`FRAMEWORK`
 target property to create an OS X Framework.
 
+If a library does not export any symbols, it must not be declared as a
+``SHARED`` library.  For example, a Windows resource DLL or a managed C++/CLI
+DLL that exports no unmanaged symbols would need to be a ``MODULE`` library.
+This is because CMake expects a ``SHARED`` library to always have an
+associated import library on Windows.
+
 By default the library file will be created in the build tree directory
 corresponding to the source tree directory in which the command was
 invoked.  See documentation of the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY`,
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst
index 357aae9f35..bc633e6ec6 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