Merge topic 'doc-TARGET_RUNTIME_DLLS' into release-3.22

001870d451 Help: Clarify TARGET_RUNTIME_DLLS behavior on imported targets

Acked-by: Kitware Robot <[email protected]>
Acked-by: Robert Maynard <[email protected]>
Merge-request: !6700

Help/command/add_library.rst

@@ -166,6 +166,8 @@ itself and is not included as a target in the generated buildsystem.
   call are ``PRIVATE`` to the interface library and do not appear in its
   :prop_tgt:`INTERFACE_SOURCES` target property.
 
+.. _`add_library imported libraries`:
+
 Imported Libraries
 ^^^^^^^^^^^^^^^^^^
 
@@ -205,7 +207,8 @@ The ``<type>`` must be one of:
     :prop_tgt:`IMPORTED_IMPLIB_<CONFIG>`) specifies the location of the
     DLL import library file (``.lib`` or ``.dll.a``) on disk, and the
     ``IMPORTED_LOCATION`` is the location of the ``.dll`` runtime
-    library (and is optional).
+    library (and is optional, but needed by the :genex:`TARGET_RUNTIME_DLLS`
+    generator expression).
 
   Additional usage requirements may be specified in ``INTERFACE_*`` properties.
 

Help/manual/cmake-generator-expressions.7.rst

@@ -1068,7 +1068,7 @@ which is just the string ``tgt``.
 
   .. code-block:: cmake
 
-    find_package(foo REQUIRED)
+    find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT)
 
     add_executable(exe main.c)
     target_link_libraries(exe PRIVATE foo::foo foo::bar)
@@ -1077,6 +1077,15 @@ which is just the string ``tgt``.
       COMMAND_EXPAND_LISTS
       )
 
+  .. note::
+
+    :ref:`Imported Targets` are supported only if they know the location
+    of their ``.dll`` files.  An imported ``SHARED`` or ``MODULE`` library
+    must have :prop_tgt:`IMPORTED_LOCATION` set to its ``.dll`` file.  See
+    the :ref:`add_library imported libraries <add_library imported libraries>`
+    section for details.  Many :ref:`Find Modules` produce imported targets
+    with the ``UNKNOWN`` type and therefore will be ignored.
+
 .. genex:: $<INSTALL_PREFIX>
 
   Content of the install prefix when the target is exported via