From bb1111eaa220eb534338410e2d1ffcf696f9ae44 Mon Sep 17 00:00:00 2001 From: Stephen Kelly Date: Sat, 22 Nov 2014 13:16:05 +0100 Subject: [PATCH] Help: Warn that paths should not be used in INTERFACE_ build properties. --- Help/command/target_include_directories.rst | 3 ++ Help/command/target_link_libraries.rst | 3 ++ .../INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt | 30 ++++++++++++++++ .../INTERFACE_LINK_LIBRARIES_WARNING.txt | 23 +++++++++++++ Help/manual/cmake-buildsystem.7.rst | 4 +++ Help/manual/cmake-packages.7.rst | 34 +++++++++++++++++++ .../INTERFACE_INCLUDE_DIRECTORIES.rst | 3 ++ Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst | 3 ++ Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst | 3 ++ .../LINK_INTERFACE_LIBRARIES_CONFIG.rst | 3 ++ 10 files changed, 109 insertions(+) create mode 100644 Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt create mode 100644 Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index fd433a87c..1d236ce31 100644 --- a/Help/command/target_include_directories.rst +++ b/Help/command/target_include_directories.rst @@ -54,3 +54,6 @@ installation prefix. For example: $ $ # /include/mylib ) + +.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` +.. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index 39537a703..e6a82b617 100644 --- a/Help/command/target_link_libraries.rst +++ b/Help/command/target_link_libraries.rst @@ -49,6 +49,9 @@ CMake will also propagate :ref:`usage requirements ` from linked library targets. Usage requirements of dependencies affect compilation of sources in the ````. +.. |INTERFACE_PROPERTY_LINK| replace:: :prop_tgt:`INTERFACE_LINK_LIBRARIES` +.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt + If an ```` is a library in a Mac OX framework, the ``Headers`` directory of the framework will also be processed as a :ref:`usage requirement `. This has the same diff --git a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt new file mode 100644 index 000000000..33f71837e --- /dev/null +++ b/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 + $ + ) + +Dependencies must provide their own :ref:`IMPORTED targets ` +which have their own |INTERFACE_PROPERTY_LINK| populated +appropriately. Those :ref:`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 ` with appropriate paths. See +:ref:`Creating Packages` for more. Note that many modules currently shipped +with CMake do not currently provide :ref:`IMPORTED targets `. diff --git a/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt b/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt new file mode 100644 index 000000000..ceefa4d2b --- /dev/null +++ b/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 ` +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 ` with appropriate paths. See +:ref:`Creating Packages` for more. Note that many modules currently shipped +with CMake do not currently provide :ref:`IMPORTED targets `. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 5df0d2987..002f2c2e8 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -272,6 +272,10 @@ be specified in the order ``lib3`` ``lib1`` ``lib2``: target_include_directories(myExe PRIVATE $) +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 diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index 13e2ba0a6..0d18fd7f8 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 ```` 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 + $ + ) + +Dependencies must provide their own :ref:`IMPORTED targets ` +which have their own :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` and +:prop_tgt:`IMPORTED_LOCATION` populated appropriately. Those +:ref:`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 ` with appropriate paths. Note that +many modules currently shipped with CMake do not currently provide +:ref:`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 diff --git a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst index 3ca12ffb1..1cfd7a85f 100644 --- a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst +++ b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst @@ -21,3 +21,6 @@ installation prefix. For example: $ $ # /include/mylib ) + +.. |INTERFACE_PROPERTY_LINK| replace:: ``INTERFACE_INCLUDE_DIRECTORIES`` +.. include:: /include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst index f0d13ca81..55b7b8d40 100644 --- a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst +++ b/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 diff --git a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst index c4c0964db..2e859ebf7 100644 --- a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst +++ b/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 diff --git a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst b/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst index 1ed402925..7f2b5dd94 100644 --- a/Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst +++ b/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_`` +.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt