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

This commit is contained in:
Stephen Kelly 2014-11-22 13:16:05 +01:00 committed by Brad King
parent 96691d126b
commit bb1111eaa2
10 changed files with 109 additions and 0 deletions

View File

@ -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

View File

@ -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

View File

@ -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>`.

View File

@ -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>`.

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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

View File

@ -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