[Cmake-commits] CMake branch, next, updated. v3.1.0-rc2-828-geab6e80
Brad King
brad.king at kitware.com
Tue Nov 25 10:00:50 EST 2014
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "CMake".
The branch, next has been updated
via eab6e80949d92bcc3cf78849a2636c1b4f1e613d (commit)
via bb1111eaa220eb534338410e2d1ffcf696f9ae44 (commit)
from 5f30c95edfb4f761c82d97b885528aa17107665d (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=eab6e80949d92bcc3cf78849a2636c1b4f1e613d
commit eab6e80949d92bcc3cf78849a2636c1b4f1e613d
Merge: 5f30c95 bb1111e
Author: Brad King <brad.king at kitware.com>
AuthorDate: Tue Nov 25 10:00:50 2014 -0500
Commit: CMake Topic Stage <kwrobot at kitware.com>
CommitDate: Tue Nov 25 10:00:50 2014 -0500
Merge topic 'improve-INTERFACE-property-docs' into next
bb1111ea Help: Warn that paths should not be used in INTERFACE_ build properties.
http://cmake.org/gitweb?p=cmake.git;a=commitdiff;h=bb1111eaa220eb534338410e2d1ffcf696f9ae44
commit bb1111eaa220eb534338410e2d1ffcf696f9ae44
Author: Stephen Kelly <steveire at gmail.com>
AuthorDate: Sat Nov 22 13:16:05 2014 +0100
Commit: Brad King <brad.king at kitware.com>
CommitDate: Tue Nov 25 10:00:35 2014 -0500
Help: Warn that paths should not be used in INTERFACE_ build properties.
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
-----------------------------------------------------------------------
Summary of changes:
hooks/post-receive
--
CMake
More information about the Cmake-commits
mailing list