Help: Clarify TARGET_RUNTIME_DLLS behavior on imported targets
This generator expression does not report the locations of `.dll`
files on imported targets with the `UNKNWON` type, since their
`IMPORTED_LOCATION` refers to the import library and not the DLL.
Fixes: #22845
diff --git a/Help/command/add_library.rst b/Help/command/add_library.rst
index dfc6500..1235155 100644
--- a/Help/command/add_library.rst
+++ b/Help/command/add_library.rst
@@ -166,6 +166,8 @@
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 @@
: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.
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst
index 5d508cb..d3cbd49 100644
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -1068,7 +1068,7 @@
.. 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 @@
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
