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

Help/command/target_include_directories.rst

@@ -54,3 +54,6 @@ installation prefix.  For example:
     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
     $<INSTALL_INTERFACE:include/mylib>  # <prefix>/include/mylib
   )
+
+.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
+.. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt

Help/command/target_link_libraries.rst

@@ -49,6 +49,9 @@ CMake will also propagate :ref:`usage requirements <Target Usage Requirements>`
 from linked library targets.  Usage requirements of dependencies affect
 compilation of sources in the ``<target>``.
 
+.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES`
+.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt
+
 If an ``<item>`` is a library in a Mac OX framework, the ``Headers``
 directory of the framework will also be processed as a
 :ref:`usage requirement <Target Usage Requirements>`.  This has the same

Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt

@@ -0,0 +1,30 @@
+
+Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the
+|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies.
+That would hard-code into installed packages the include directory paths
+for dependencies **as found on the machine the package was made on**.
+
+The ``INSTALL_INTERFACE`` of the |INTERFACE_PROPERTY_LINK| is only
+suitable for specifying the required include directories of the target itself,
+not its dependencies.
+
+That is, code like this is incorrect for targets which will be used to
+generate :manual:`cmake-packages(7)`:
+
+.. code-block:: cmake
+
+  target_include_directories(mylib INTERFACE
+    $<INSTALL_INTERFACE:${Boost_INCLUDE_DIRS};${OtherDep_INCLUDE_DIRS}>
+  )
+
+Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>`
+which have their own |INTERFACE_PROPERTY_LINK| populated
+appropriately.  Those :ref:`IMPORTED targets <Imported Targets>` may then be
+used with the :command:`target_link_libraries` command for ``mylib``.
+
+That way, when a consumer uses the installed package, the
+consumer will run the appropriate :command:`find_package` command to find
+the dependencies on their own machine and populate the
+:ref:`IMPORTED targets <Imported Targets>` with appropriate paths.  See
+:ref:`Creating Packages` for more.  Note that many modules currently shipped
+with CMake do not currently provide :ref:`IMPORTED targets <Imported Targets>`.

Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt

@@ -0,0 +1,23 @@
+
+Note that it is not advisable to populate the
+|INTERFACE_PROPERTY_LINK| of a target with paths for dependencies.
+That would hard-code into installed packages the include directory 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 :manual:`cmake-packages(7)`:
+
+.. code-block:: cmake
+
+  target_link_libraries(mylib INTERFACE
+    ${Boost_LIBRARIES};${OtherDep_LIBRARIES}
+  )
+
+Dependencies must provide their own :ref:`IMPORTED targets <Imported Targets>`
+which have their own :prop_tgt:`IMPORTED_LOCATION` populated
+appropriately.  That way, when a consumer uses the installed package, the
+consumer will run the appropriate :command:`find_package` command to find
+the dependencies on their own machine and populate the
+:ref:`IMPORTED targets <Imported Targets>` with appropriate paths.  See
+:ref:`Creating Packages` for more.  Note that many modules currently shipped
+with CMake do not currently provide :ref:`IMPORTED targets <Imported Targets>`.

Help/manual/cmake-buildsystem.7.rst

@@ -272,6 +272,10 @@ be specified in the order ``lib3`` ``lib1`` ``lib2``:
   target_include_directories(myExe
     PRIVATE $<TARGET_PROPERTY:lib3,INTERFACE_INCLUDE_DIRECTORIES>)
 
+Note that care must be taken when specifying usage requirements for targets
+which will be exported for installation using the :command:`install(EXPORT)`
+command.  See :ref:`Creating Packages` for more.
+
 .. _`Compatible Interface Properties`:
 
 Compatible Interface Properties

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

Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst

@@ -21,3 +21,6 @@ installation prefix.  For example:
     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include/mylib>
     $<INSTALL_INTERFACE:include/mylib>  # <prefix>/include/mylib
   )
+
+.. |INTERFACE_PROPERTY_LINK| replace:: ``INTERFACE_INCLUDE_DIRECTORIES``
+.. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt

Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst

@@ -16,3 +16,6 @@ Contents of ``INTERFACE_LINK_LIBRARIES`` may use "generator expressions"
 with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
+
+.. |INTERFACE_PROPERTY_LINK| replace:: ``INTERFACE_LINK_LIBRARIES``
+.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt

Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst

@@ -23,3 +23,6 @@ property if policy :policy:`CMP0022` is ``NEW``.
 
 This property is deprecated.  Use :prop_tgt:`INTERFACE_LINK_LIBRARIES`
 instead.
+
+.. |INTERFACE_PROPERTY_LINK| replace:: ``LINK_INTERFACE_LIBRARIES``
+.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt

Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst

@@ -12,3 +12,6 @@ property if policy :policy:`CMP0022` is ``NEW``.
 
 This property is deprecated.  Use :prop_tgt:`INTERFACE_LINK_LIBRARIES`
 instead.
+
+.. |INTERFACE_PROPERTY_LINK| replace:: ``LINK_INTERFACE_LIBRARIES_<CONFIG>``
+.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt