Merge topic 'doc-genex'
263f6b888c Help: Document TARGET_PROPERTY genex handling of transitive properties
f70eb84be7 Help: Clarify role of TARGET_NAME generator expression
36145e2680 Help: Organize target-dependent generator expressions into subsections
50eadd794e Help: Clarify cross-references to target-dependent generator expressions
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !9460
diff --git a/Help/command/add_custom_command.rst b/Help/command/add_custom_command.rst
index bd80e6e..c184a96 100644
--- a/Help/command/add_custom_command.rst
+++ b/Help/command/add_custom_command.rst
@@ -84,8 +84,8 @@
.. versionadded:: 3.20
Arguments to ``BYPRODUCTS`` may use a restricted set of
:manual:`generator expressions <cmake-generator-expressions(7)>`.
- :ref:`Target-dependent expressions <Target-Dependent Queries>` are not
- permitted.
+ :ref:`Target-dependent expressions <Target-Dependent Expressions>`
+ are not permitted.
.. versionchanged:: 3.28
In targets using :ref:`file sets`, custom command byproducts are now
@@ -272,8 +272,8 @@
.. versionadded:: 3.20
Arguments to ``OUTPUT`` may use a restricted set of
:manual:`generator expressions <cmake-generator-expressions(7)>`.
- :ref:`Target-dependent expressions <Target-Dependent Queries>` are not
- permitted.
+ :ref:`Target-dependent expressions <Target-Dependent Expressions>`
+ are not permitted.
.. versionchanged:: 3.28
In targets using :ref:`file sets`, custom command outputs are now
diff --git a/Help/command/add_custom_target.rst b/Help/command/add_custom_target.rst
index 0385a93..d88e0f0 100644
--- a/Help/command/add_custom_target.rst
+++ b/Help/command/add_custom_target.rst
@@ -60,8 +60,8 @@
.. versionadded:: 3.20
Arguments to ``BYPRODUCTS`` may use a restricted set of
:manual:`generator expressions <cmake-generator-expressions(7)>`.
- :ref:`Target-dependent expressions <Target-Dependent Queries>` are not
- permitted.
+ :ref:`Target-dependent expressions <Target-Dependent Expressions>`
+ are not permitted.
.. versionchanged:: 3.28
In custom targets using :ref:`file sets`, byproducts are now
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst
index e2a99c3..38fa6f9 100644
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -1702,22 +1702,15 @@
only be used to specify link options.
-.. _`Target-Dependent Queries`:
+.. _`Target-Dependent Expressions`:
Target-Dependent Expressions
----------------------------
-These queries refer to a target ``tgt``. Unless otherwise stated, this can
-be any runtime artifact, namely:
+Target Meta-Data
+^^^^^^^^^^^^^^^^
-* An executable target created by :command:`add_executable`.
-* A shared library target (``.so``, ``.dll`` but not their ``.lib`` import
- library) created by :command:`add_library`.
-* A static library target created by :command:`add_library`.
-
-In the following, the phrase "the ``tgt`` filename" means the name of the
-``tgt`` binary file. This has to be distinguished from the phrase
-"the target name", which is just the string ``tgt``.
+These expressions look up information about a target.
.. genex:: $<TARGET_EXISTS:tgt>
@@ -1734,11 +1727,27 @@
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on.
-.. genex:: $<TARGET_NAME:...>
+.. genex:: $<TARGET_NAME:tgt>
- Marks ``...`` as being the name of a target. This is required if exporting
- targets to multiple dependent export sets. The ``...`` must be a literal
- name of a target, it may not contain generator expressions.
+ The target name ``tgt`` as written. This marks ``tgt`` as being the name
+ of a target inside a larger expression, which is required if exporting
+ targets to multiple dependent export sets. The ``tgt`` text must be a
+ literal name of a target; it may not contain generator expressions.
+ The target does not have to exist.
+
+.. genex:: $<TARGET_POLICY:policy>
+
+ ``1`` if the ``policy`` was ``NEW`` when the 'head' target was created,
+ else ``0``. If the ``policy`` was not set, the warning message for the policy
+ will be emitted. This generator expression only works for a subset of
+ policies.
+
+
+Target Properties
+^^^^^^^^^^^^^^^^^
+
+These expressions look up the values of
+:ref:`target properties <Target Properties>`.
.. genex:: $<TARGET_PROPERTY:tgt,prop>
@@ -1748,8 +1757,7 @@
expression is evaluated on.
.. versionchanged:: 3.26
- When encountered during evaluation of
- :ref:`usage requirements <Target Usage Requirements>`,
+ When encountered during evaluation of :ref:`Target Usage Requirements`,
typically in an ``INTERFACE_*`` target property, lookup of the ``tgt``
name occurs in the directory of the target specifying the requirement,
rather than the directory of the consuming target for which the
@@ -1759,23 +1767,55 @@
:target: TARGET_PROPERTY:prop
Value of the property ``prop`` on the target for which the expression
- is being evaluated. Note that for generator expressions in
- :ref:`usage requirements <Target Usage Requirements>` this is the
- consuming target rather than the target specifying the requirement.
+ is being evaluated. Note that for generator expressions in
+ :ref:`Target Usage Requirements` this is the consuming target rather
+ than the target specifying the requirement.
-.. genex:: $<TARGET_OBJECTS:tgt>
+The expressions have special evaluation rules for some properties:
- .. versionadded:: 3.1
+* :ref:`Target Build Specification` properties evaluate as a
+ :ref:`semicolon-separated list <CMake Language Lists>` representing the union
+ of the value on the target itself with the values of the corresponding
+ :ref:`Target Usage Requirements` on targets named by the target's
+ :prop_tgt:`LINK_LIBRARIES`. Evaluation of the usage requirements is
+ transitive over the closure of the linked targets'
+ :prop_tgt:`INTERFACE_LINK_LIBRARIES`.
- List of objects resulting from building ``tgt``. This would typically be
- used on :ref:`object library <Object Libraries>` targets.
+ Evaluation of :prop_tgt:`LINK_LIBRARIES` itself is not transitive.
-.. genex:: $<TARGET_POLICY:policy>
+* :ref:`Target Usage Requirements` evaluate as a
+ :ref:`semicolon-separated list <CMake Language Lists>` representing the union
+ of the value on the target itself with the values of the same properties on
+ targets named by the target's :prop_tgt:`INTERFACE_LINK_LIBRARIES`.
+ Evaluation is transitive over the closure of the target's
+ :prop_tgt:`INTERFACE_LINK_LIBRARIES`.
- ``1`` if the ``policy`` was ``NEW`` when the 'head' target was created,
- else ``0``. If the ``policy`` was not set, the warning message for the policy
- will be emitted. This generator expression only works for a subset of
- policies.
+ Evaluation of :prop_tgt:`INTERFACE_LINK_LIBRARIES` itself is not transitive.
+
+* :ref:`Compatible Interface Properties` evaluate as a single value
+ combined from the target itself, from targets named by the target's
+ :prop_tgt:`LINK_LIBRARIES`, and from the transitive closure of the
+ linked targets' :prop_tgt:`INTERFACE_LINK_LIBRARIES`. Values of a
+ compatible interface property from multiple targets combine based on
+ the type of compatibility required by the ``COMPATIBLE_INTERFACE_*``
+ property defining it.
+
+
+Target Artifacts
+^^^^^^^^^^^^^^^^
+
+These expressions look up information about artifacts associated with
+a given target ``tgt``. Unless otherwise stated, this can be any
+runtime artifact, namely:
+
+* An executable target created by :command:`add_executable`.
+* A shared library target (``.so``, ``.dll`` but not their ``.lib`` import
+ library) created by :command:`add_library`.
+* A static library target created by :command:`add_library`.
+
+In the following, the phrase "the ``tgt`` filename" means the name of the
+``tgt`` binary file. This has to be distinguished from the phrase
+"the target name", which is just the string ``tgt``.
.. genex:: $<TARGET_FILE:tgt>
@@ -2257,6 +2297,13 @@
Note that ``tgt`` is not added as a dependency of the target this
expression is evaluated on (see policy :policy:`CMP0112`).
+.. genex:: $<TARGET_OBJECTS:tgt>
+
+ .. versionadded:: 3.1
+
+ List of objects resulting from building ``tgt``. This would typically be
+ used on :ref:`object library <Object Libraries>` targets.
+
.. genex:: $<TARGET_RUNTIME_DLLS:tgt>
.. versionadded:: 3.21
