From 50eadd794e0f9154bf844741739b12c2f21392a6 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 19 Apr 2024 14:18:10 -0400 Subject: Help: Clarify cross-references to target-dependent generator expressions --- Help/command/add_custom_command.rst | 8 ++++---- Help/command/add_custom_target.rst | 4 ++-- Help/manual/cmake-generator-expressions.7.rst | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) 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 @@ The options are: .. versionadded:: 3.20 Arguments to ``BYPRODUCTS`` may use a restricted set of :manual:`generator expressions `. - :ref:`Target-dependent expressions ` are not - permitted. + :ref:`Target-dependent expressions ` + are not permitted. .. versionchanged:: 3.28 In targets using :ref:`file sets`, custom command byproducts are now @@ -272,8 +272,8 @@ The options are: .. versionadded:: 3.20 Arguments to ``OUTPUT`` may use a restricted set of :manual:`generator expressions `. - :ref:`Target-dependent expressions ` are not - permitted. + :ref:`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 @@ The options are: .. versionadded:: 3.20 Arguments to ``BYPRODUCTS`` may use a restricted set of :manual:`generator expressions `. - :ref:`Target-dependent expressions ` are not - permitted. + :ref:`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..62c0e88 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -1702,7 +1702,7 @@ Link Context only be used to specify link options. -.. _`Target-Dependent Queries`: +.. _`Target-Dependent Expressions`: Target-Dependent Expressions ---------------------------- -- cgit v0.12 From 36145e2680f764b75cf656b6cba54114333df116 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 19 Apr 2024 14:23:51 -0400 Subject: Help: Organize target-dependent generator expressions into subsections --- Help/manual/cmake-generator-expressions.7.rst | 55 ++++++++++++++++++--------- 1 file changed, 36 insertions(+), 19 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 62c0e88..9630de6 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -1707,17 +1707,10 @@ Link Context 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:: $ @@ -1740,6 +1733,20 @@ In the following, the phrase "the ``tgt`` filename" means the name of the targets to multiple dependent export sets. The ``...`` must be a literal name of a target, it may not contain generator expressions. +.. genex:: $ + + ``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 `. + .. genex:: $ Value of the property ``prop`` on the target ``tgt``. @@ -1763,19 +1770,22 @@ In the following, the phrase "the ``tgt`` filename" means the name of the :ref:`usage requirements ` this is the consuming target rather than the target specifying the requirement. -.. genex:: $ - .. versionadded:: 3.1 +Target Artifacts +^^^^^^^^^^^^^^^^ - List of objects resulting from building ``tgt``. This would typically be - used on :ref:`object library ` targets. +These expressions look up information about artifacts associated with +a given target ``tgt``. Unless otherwise stated, this can be any +runtime artifact, namely: -.. genex:: $ +* 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`. - ``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. +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:: $ @@ -2257,6 +2267,13 @@ In the following, the phrase "the ``tgt`` filename" means the name of the Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). +.. genex:: $ + + .. versionadded:: 3.1 + + List of objects resulting from building ``tgt``. This would typically be + used on :ref:`object library ` targets. + .. genex:: $ .. versionadded:: 3.21 -- cgit v0.12 From f70eb84be7f7432a69ac306bb3746ba57ff0635e Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 19 Apr 2024 14:34:28 -0400 Subject: Help: Clarify role of TARGET_NAME generator expression --- Help/manual/cmake-generator-expressions.7.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 9630de6..68eb3ee 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -1727,11 +1727,13 @@ These expressions look up information about a target. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -.. genex:: $ +.. genex:: $ - 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:: $ -- cgit v0.12 From 263f6b888c4bb9023a68ddf719c6d6bbb42693e7 Mon Sep 17 00:00:00 2001 From: Brad King Date: Fri, 19 Apr 2024 15:13:29 -0400 Subject: Help: Document TARGET_PROPERTY genex handling of transitive properties --- Help/manual/cmake-generator-expressions.7.rst | 38 +++++++++++++++++++++++---- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 68eb3ee..38fa6f9 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -1757,8 +1757,7 @@ These expressions look up the values of expression is evaluated on. .. versionchanged:: 3.26 - When encountered during evaluation of - :ref:`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 @@ -1768,9 +1767,38 @@ These expressions look up the values of :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 ` 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. + +The expressions have special evaluation rules for some properties: + +* :ref:`Target Build Specification` properties evaluate as a + :ref:`semicolon-separated list ` 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`. + + Evaluation of :prop_tgt:`LINK_LIBRARIES` itself is not transitive. + +* :ref:`Target Usage Requirements` evaluate as a + :ref:`semicolon-separated list ` 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`. + + 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 -- cgit v0.12