Merge topic 'improve-INTERFACE-property-docs'
bb1111eaHelp: Warn that paths should not be used in INTERFACE_ build properties.96691d12Help: Fix typo in genex in documentation.f8f02451Help: Use a property-specific command instead of the generic one.8609a884Help: Make remaining build property docs consistent.bcface39Help: Link to target_link_libraries from target properies.e12926e7Help: Format the LINK_INTERFACE_LIBRARIES target properies.c8540e94Help: Unify the help text of INTERFACE_ build properties.
This commit is contained in:
Brad King
CMake Topic Stage
commit
90cfed51f6
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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>`.
|
||||
|
|
@ -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>`.
|
||||
|
|
@ -270,7 +270,11 @@ be specified in the order ``lib3`` ``lib1`` ``lib2``:
|
|||
|
||||
target_link_libraries(myExe lib1 lib2 lib3)
|
||||
target_include_directories(myExe
|
||||
PRIVATE $<TARGET_PROPERTY:INTERFACE_INCLUDE_DIRECTORIES:lib3>)
|
||||
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`:
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -0,0 +1,16 @@
|
|||
|
||||
List of public |property_name| requirements for a library.
|
||||
|
||||
Targets may populate this property to publish the |property_name|
|
||||
required to compile against the headers for the target. The |command_name|
|
||||
command populates this property with values given to the ``PUBLIC`` and
|
||||
``INTERFACE`` keywords. Projects may also get and set the property directly.
|
||||
|
||||
When target dependencies are specified using :command:`target_link_libraries`,
|
||||
CMake will read this property from all target dependencies to determine the
|
||||
build properties of the consumer.
|
||||
|
||||
Contents of |PROPERTY_INTERFACE_NAME| 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.
|
||||
|
|
@ -1,15 +1,9 @@
|
|||
INTERFACE_COMPILE_DEFINITIONS
|
||||
-----------------------------
|
||||
|
||||
List of public compile definitions for a library.
|
||||
|
||||
Targets may populate this property to publish the compile definitions
|
||||
required to compile against the headers for the target. Consuming
|
||||
targets can add entries to their own :prop_tgt:`COMPILE_DEFINITIONS`
|
||||
property such as ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_DEFINITIONS>``
|
||||
to use the compile definitions specified in the interface of ``foo``.
|
||||
|
||||
Contents of ``INTERFACE_COMPILE_DEFINITIONS`` 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.
|
||||
.. |property_name| replace:: compile definitions
|
||||
.. |command_name| replace:: :command:`target_compile_definitions`
|
||||
.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_COMPILE_DEFINITIONS``
|
||||
.. |PROPERTY_LINK| replace:: :prop_tgt:`COMPILE_DEFINITIONS`
|
||||
.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_DEFINITIONS>``
|
||||
.. include:: INTERFACE_BUILD_PROPERTY.txt
|
||||
|
|
|
|||
|
|
@ -1,16 +1,12 @@
|
|||
INTERFACE_COMPILE_FEATURES
|
||||
--------------------------
|
||||
|
||||
List of public compile requirements for a library.
|
||||
.. |property_name| replace:: compile features
|
||||
.. |command_name| replace:: :command:`target_compile_features`
|
||||
.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_COMPILE_FEATURES``
|
||||
.. |PROPERTY_LINK| replace:: :prop_tgt:`COMPILE_FEATURES`
|
||||
.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_FEATURES>``
|
||||
.. include:: INTERFACE_BUILD_PROPERTY.txt
|
||||
|
||||
Targets may populate this property to publish the compiler features
|
||||
required to compile against the headers for the target. Consuming
|
||||
targets can add entries to their own :prop_tgt:`COMPILE_FEATURES`
|
||||
property such as ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_FEATURES>``
|
||||
to require the features specified in the interface of ``foo``.
|
||||
|
||||
Contents of ``INTERFACE_COMPILE_FEATURES`` may use "generator expressions"
|
||||
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
|
||||
manual for available expressions. See the
|
||||
:manual:`cmake-compile-features(7)` manual for information on compile
|
||||
See the :manual:`cmake-compile-features(7)` manual for information on compile
|
||||
features.
|
||||
|
|
|
|||
|
|
@ -1,15 +1,9 @@
|
|||
INTERFACE_COMPILE_OPTIONS
|
||||
-------------------------
|
||||
|
||||
List of interface options to pass to the compiler.
|
||||
|
||||
Targets may populate this property to publish the compile options
|
||||
required to compile against the headers for the target. Consuming
|
||||
targets can add entries to their own :prop_tgt:`COMPILE_OPTIONS` property
|
||||
such as ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_OPTIONS>`` to use the
|
||||
compile options specified in the interface of ``foo``.
|
||||
|
||||
Contents of ``INTERFACE_COMPILE_OPTIONS`` 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.
|
||||
.. |property_name| replace:: compile options
|
||||
.. |command_name| replace:: :command:`target_compile_options`
|
||||
.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_COMPILE_OPTIONS``
|
||||
.. |PROPERTY_LINK| replace:: :prop_tgt:`COMPILE_OPTIONS`
|
||||
.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_COMPILE_OPTIONS>``
|
||||
.. include:: INTERFACE_BUILD_PROPERTY.txt
|
||||
|
|
|
|||
|
|
@ -1,22 +1,12 @@
|
|||
INTERFACE_INCLUDE_DIRECTORIES
|
||||
-----------------------------
|
||||
|
||||
List of public include directories for a library.
|
||||
|
||||
The :command:`target_include_directories` command populates this property
|
||||
with values given to the ``PUBLIC`` and ``INTERFACE`` keywords. Projects
|
||||
may also get and set the property directly.
|
||||
|
||||
Targets may populate this property to publish the include directories
|
||||
required to compile against the headers for the target. Consuming
|
||||
targets can add entries to their own :prop_tgt:`INCLUDE_DIRECTORIES`
|
||||
property such as ``$<TARGET_PROPERTY:foo,INTERFACE_INCLUDE_DIRECTORIES>``
|
||||
to use the include directories specified in the interface of ``foo``.
|
||||
|
||||
Contents of ``INTERFACE_INCLUDE_DIRECTORIES`` 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.
|
||||
.. |property_name| replace:: include directories
|
||||
.. |command_name| replace:: :command:`target_include_directories`
|
||||
.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_INCLUDE_DIRECTORIES``
|
||||
.. |PROPERTY_LINK| replace:: :prop_tgt:`INCLUDE_DIRECTORIES`
|
||||
.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_INCLUDE_DIRECTORIES>``
|
||||
.. include:: INTERFACE_BUILD_PROPERTY.txt
|
||||
|
||||
Include directories usage requirements commonly differ between the build-tree
|
||||
and the install-tree. The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE``
|
||||
|
|
@ -27,7 +17,10 @@ installation prefix. For example:
|
|||
|
||||
.. code-block:: cmake
|
||||
|
||||
set_property(TARGET mylib APPEND PROPERTY INTERFACE_INCLUDE_DIRECTORIES
|
||||
target_include_directories(mylib INTERFACE
|
||||
$<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
|
||||
|
|
|
|||
|
|
@ -4,7 +4,8 @@ INTERFACE_LINK_LIBRARIES
|
|||
List public interface libraries for a library.
|
||||
|
||||
This property contains the list of transitive link dependencies. When
|
||||
the target is linked into another target the libraries listed (and
|
||||
the target is linked into another target using the
|
||||
:command:`target_link_libraries` command, the libraries listed (and
|
||||
recursively their link interface libraries) will be provided to the
|
||||
other target also. This property is overridden by the
|
||||
:prop_tgt:`LINK_INTERFACE_LIBRARIES` or
|
||||
|
|
@ -15,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
|
||||
|
|
|
|||
|
|
@ -1,13 +1,16 @@
|
|||
INTERFACE_SOURCES
|
||||
-----------------
|
||||
|
||||
List of interface sources to pass to the compiler.
|
||||
List of interface sources to compile into consuming targets.
|
||||
|
||||
Targets may populate this property to publish the sources
|
||||
for consuming targets to compile. Consuming
|
||||
targets can add entries to their own :prop_tgt:`SOURCES` property
|
||||
such as ``$<TARGET_PROPERTY:foo,INTERFACE_SOURCES>`` to use the
|
||||
sources specified in the interface of ``foo``.
|
||||
for consuming targets to compile. The :command:`target_sources` command
|
||||
populates this property with values given to the ``PUBLIC`` and
|
||||
``INTERFACE`` keywords. Projects may also get and set the property directly.
|
||||
|
||||
When target dependencies are specified using :command:`target_link_libraries`,
|
||||
CMake will read this property from all target dependencies to determine the
|
||||
sources of the consumer.
|
||||
|
||||
Contents of ``INTERFACE_SOURCES`` may use "generator expressions"
|
||||
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
|
||||
|
|
|
|||
|
|
@ -5,8 +5,14 @@ List of public system include directories for a library.
|
|||
|
||||
Targets may populate this property to publish the include directories
|
||||
which contain system headers, and therefore should not result in
|
||||
compiler warnings. Consuming targets will then mark the same include
|
||||
directories as system headers.
|
||||
compiler warnings. The :command:`target_include_directories(SYSTEM)`
|
||||
command signature populates this property with values given to the
|
||||
``PUBLIC`` and ``INTERFACE`` keywords. Projects may also get and set the
|
||||
property directly.
|
||||
|
||||
When target dependencies are specified using :command:`target_link_libraries`,
|
||||
CMake will read this property from all target dependencies to mark the
|
||||
same include directories as containing system headers.
|
||||
|
||||
Contents of ``INTERFACE_SYSTEM_INCLUDE_DIRECTORIES`` may use "generator
|
||||
expressions" with the syntax ``$<...>``. See the
|
||||
|
|
|
|||
|
|
@ -5,18 +5,24 @@ List public interface libraries for a shared library or executable.
|
|||
|
||||
By default linking to a shared library target transitively links to
|
||||
targets with which the library itself was linked. For an executable
|
||||
with exports (see the ENABLE_EXPORTS property) no default transitive
|
||||
link dependencies are used. This property replaces the default
|
||||
with exports (see the :prop_tgt:`ENABLE_EXPORTS` target property) no
|
||||
default transitive link dependencies are used. This property replaces the default
|
||||
transitive link dependencies with an explicit list. When the target
|
||||
is linked into another target the libraries listed (and recursively
|
||||
is linked into another target using the :command:`target_link_libraries`
|
||||
command, the libraries listed (and recursively
|
||||
their link interface libraries) will be provided to the other target
|
||||
also. If the list is empty then no transitive link dependencies will
|
||||
be incorporated when this target is linked into another target even if
|
||||
the default set is non-empty. This property is initialized by the
|
||||
value of the variable CMAKE_LINK_INTERFACE_LIBRARIES if it is set when
|
||||
a target is created. This property is ignored for STATIC libraries.
|
||||
value of the :variable:`CMAKE_LINK_INTERFACE_LIBRARIES` variable if it is
|
||||
set when a target is created. This property is ignored for ``STATIC``
|
||||
libraries.
|
||||
|
||||
This property is overridden by the INTERFACE_LINK_LIBRARIES property if
|
||||
policy CMP0022 is NEW.
|
||||
This property is overridden by the :prop_tgt:`INTERFACE_LINK_LIBRARIES`
|
||||
property if policy :policy:`CMP0022` is ``NEW``.
|
||||
|
||||
This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead.
|
||||
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
|
||||
|
|
|
|||
|
|
@ -4,10 +4,14 @@ LINK_INTERFACE_LIBRARIES_<CONFIG>
|
|||
Per-configuration list of public interface libraries for a target.
|
||||
|
||||
This is the configuration-specific version of
|
||||
LINK_INTERFACE_LIBRARIES. If set, this property completely overrides
|
||||
the generic property for the named configuration.
|
||||
:prop_tgt:`LINK_INTERFACE_LIBRARIES`. If set, this property completely
|
||||
overrides the generic property for the named configuration.
|
||||
|
||||
This property is overridden by the INTERFACE_LINK_LIBRARIES property if
|
||||
policy CMP0022 is NEW.
|
||||
This property is overridden by the :prop_tgt:`INTERFACE_LINK_LIBRARIES`
|
||||
property if policy :policy:`CMP0022` is ``NEW``.
|
||||
|
||||
This property is deprecated. Use INTERFACE_LINK_LIBRARIES instead.
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue