Help: Warn that paths should not be used in INTERFACE_ build properties.

1 files changed, 34 insertions, 0 deletions

diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst
index 13e2ba0a64..0d18fd7f82 100644
--- a/Help/manual/cmake-packages.7.rst
+++ b/Help/manual/cmake-packages.7.rst
@@ -260,6 +260,8 @@ The variables report the version of the package that was actually found.
 The ``<package>`` part of their name matches the argument given to the
 :command:`find_package` command.
 
+.. _`Creating Packages`:
+
 Creating Packages
 =================
 
@@ -369,6 +371,38 @@ attempt to use version 3 together with version 4.  Packages can choose to
 employ such a pattern if different major versions of the package are designed
 to be incompatible.
 
+Note that it is not advisable to populate any properties which may contain
+paths, such as :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and
+:prop_tgt:`INTERFACE_LINK_LIBRARIES`, with paths relevnt to dependencies.
+That would hard-code into installed packages the include directory or library
+paths for dependencies **as found on the machine the package was made on**.
+
+That is, code like this is incorrect for targets which will be used to
+generate config file packages:
+
+.. code-block:: cmake
+
+  target_link_libraries(ClimbingStats INTERFACE
+    ${Boost_LIBRARIES};${OtherDep_LIBRARIES}>
+  )
+  target_include_directories(ClimbingStats INTERFACE
+    $<INSTALL_INTERFACE:${Boost_INCLUDE_DIRS};${OtherDep_INCLUDE_DIRS}>
+  )
+
+Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>`
+which have their own :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and
+:prop_tgt:`IMPORTED_LOCATION` populated appropriately.  Those
+:ref:`IMPORTED targets <Imported Targets>` may then be
+used with the :command:`target_link_libraries` command for ``ClimbingStats``.
+
+That way, when a consumer uses the installed package, the
+consumer will run the appropriate :command:`find_package` command (via the
+find_dependency macro described below) to find
+the dependencies on their own machine and populate the
+:ref:`IMPORTED targets <Imported Targets>` with appropriate paths. Note that
+many modules currently shipped with CMake do not currently provide
+:ref:`IMPORTED targets <Imported Targets>`.
+
 A ``NAMESPACE`` with double-colons is specified when exporting the targets
 for installation.  This convention of double-colons gives CMake a hint that
 the name is an :prop_tgt:`IMPORTED` target when it is used by downstreams