diff options
| -rw-r--r-- | Help/command/target_include_directories.rst | 3 | ||||
| -rw-r--r-- | Help/command/target_link_libraries.rst | 3 | ||||
| -rw-r--r-- | Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt | 30 | ||||
| -rw-r--r-- | Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt | 23 | ||||
| -rw-r--r-- | Help/manual/cmake-buildsystem.7.rst | 4 | ||||
| -rw-r--r-- | Help/manual/cmake-packages.7.rst | 34 | ||||
| -rw-r--r-- | Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst | 3 | ||||
| -rw-r--r-- | Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst | 3 | ||||
| -rw-r--r-- | Help/prop_tgt/LINK_INTERFACE_LIBRARIES.rst | 3 | ||||
| -rw-r--r-- | Help/prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG.rst | 3 |
10 files changed, 109 insertions, 0 deletions
diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst index fd433a8..1d236ce 100644 --- a/Help/command/target_include_directories.rst +++ b/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 diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst index 39537a7..e6a82b6 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 <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 diff --git a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt new file mode 100644 index 0000000..33f7183 --- /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 + $<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>`. diff --git a/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt b/Help/include/INTERFACE_LINK_LIBRARIES_WARNING.txt new file mode 100644 index 0000000..ceefa4d --- /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 <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>`. diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 5df0d29..002f2c2 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 $<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 diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index 13e2ba0..0d18fd7 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 diff --git a/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_INCLUDE_DIRECTORIES.rst index 3ca12ff..1cfd7a8 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: $<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 diff --git a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst index f0d13ca..55b7b8d 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 c4c0964..2e859eb 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 1ed4029..7f2b5dd 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_<CONFIG>`` +.. include:: /include/INTERFACE_LINK_LIBRARIES_WARNING.txt |