From db749f404c29bc91a06f2ea2fb23d8a30c526a9a Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sun, 4 Nov 2018 14:55:51 +0100 Subject: Help: expand "..." and "?" in logical generator expressions Expand "..." and "?", which could be mistaken as metacharacters (and in the explanations of AND and OR actually were meant as metacharacters). --- Help/manual/cmake-generator-expressions.7.rst | 33 ++++++++++++++++----------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index bddf827..24b79d4 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -42,19 +42,26 @@ otherwise expands to nothing. Available logical expressions are: -``$`` - ``1`` if the ``...`` is true, else ``0`` -``$`` - ``1`` if all ``?`` are ``1``, else ``0`` - - The ``?`` must always be either ``0`` or ``1`` in boolean expressions. - -``$`` - ``0`` if all ``?`` are ``0``, else ``1`` -``$`` - ``0`` if ``?`` is ``1``, else ``1`` -``$`` - ``true-value...`` if ``?`` is ``1``, ``false-value...`` if ``?`` is ``0`` +``$`` + ``1`` if the ``condition`` is true, else ``0`` + +``$`` + where ``conditions`` is a comma-separated list of boolean expressions. + Evaluates to ``1`` if all conditions are ``1``. + Otherwise evaluates to ``0``. + +``$`` + where ``conditions`` is a comma-separated list of boolean expressions. + Evaluates to ``1`` if at least one of the conditions is ``1``. + Otherwise evaluates to ``0``. + +``$`` + ``0`` if ``condition`` is ``1``, else ``1`` + +``$`` + ``true_value`` if ``condition`` is ``1``, + ``false_value`` if ``condition`` is ``0`` + ``$`` ``1`` if ``a`` is STREQUAL ``b``, else ``0`` ``$`` -- cgit v0.12 From b2a798fe32ce25e5ea19f6487ce9cadf9852ea83 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sun, 4 Nov 2018 15:07:42 +0100 Subject: Help: expand "ver", "pol", ... No need to save a few characters on formal parameters. Use this occasion to correct $: the parameter is a platform_id, not a compiler_id. --- Help/manual/cmake-generator-expressions.7.rst | 42 +++++++++++++++------------ 1 file changed, 23 insertions(+), 19 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 24b79d4..95de378 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -68,21 +68,24 @@ Available logical expressions are: ``1`` if ``a`` is EQUAL ``b`` in a numeric comparison, else ``0`` ``$`` ``1`` if ``a`` is IN_LIST ``b``, else ``0`` -``$`` - ``1`` if ``tgt`` is an existed target name, else ``0``. +``$`` + ``1`` if ``target`` exists, else ``0``. ``$`` ``1`` if config is ``cfg``, else ``0``. This is a case-insensitive comparison. The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_` is also considered by this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` target. -``$`` - ``1`` if the CMake-id of the platform matches ``comp``, otherwise ``0``. +``$`` + ``1`` if the CMake-id of the platform matches ``platform_id`` + otherwise ``0``. See also the :variable:`CMAKE_SYSTEM_NAME` variable. -``$`` - ``1`` if the CMake-id of the C compiler matches ``comp``, otherwise ``0``. +``$`` + ``1`` if the CMake-id of the C compiler matches ``compiler_id``, + otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` - ``1`` if the CMake-id of the CXX compiler matches ``comp``, otherwise ``0``. +``$`` + ``1`` if the CMake-id of the CXX compiler matches ``compiler_id``, + otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. ``$`` ``1`` if ``v1`` is a version less than ``v2``, else ``0``. @@ -94,27 +97,28 @@ Available logical expressions are: ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. ``$`` ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. -``$`` - ``1`` if the version of the C compiler matches ``ver``, otherwise ``0``. +``$`` + ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` - ``1`` if the version of the CXX compiler matches ``ver``, otherwise ``0``. +``$`` + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` - ``1`` if the policy ``pol`` was NEW when the 'head' target was created, - else ``0``. If the policy was not set, the warning message for the 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. -``$`` - ``1`` if all of the ``feature`` features are available for the 'head' +``$`` + where ``features`` is a comma-spearated list. + Evaluates to ``1`` if all of the ``features`` are available for the 'head' target, and ``0`` otherwise. If this expression is used while evaluating the link implementation of a target and if any dependency transitively increases the required :prop_tgt:`C_STANDARD` or :prop_tgt:`CXX_STANDARD` for the 'head' target, an error is reported. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. -``$`` - ``1`` when the language used for compilation unit matches ``lang``, +``$`` + ``1`` when the language used for compilation unit matches ``language``, otherwise ``0``. This expression may be used to specify compile options, compile definitions, and include directories for source files of a particular language in a target. For example: -- cgit v0.12 From 873e59c0c456c2e13e66019c15f3632d06dac0f6 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sun, 4 Nov 2018 15:10:40 +0100 Subject: Help: rm unmotivated "This means that" That generator expressions enable conditional things has not been said before. Amended for nicer source format. --- Help/manual/cmake-generator-expressions.7.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 95de378..6f17812 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -20,10 +20,10 @@ commands to populate those properties, such as :command:`target_link_libraries`, :command:`target_include_directories`, :command:`target_compile_definitions` and others. -This means that they enable conditional linking, conditional -definitions used when compiling, and conditional include directories and -more. The conditions may be based on the build configuration, target -properties, platform information or any other queryable information. +They enable conditional linking, conditional definitions used when compiling, +conditional include directories, and more. The conditions may be based on +the build configuration, target properties, platform information or any other +queryable information. Logical Expressions =================== -- cgit v0.12 From 20b6561e78f5acceecae7c6fc330f7f7de4f2223 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sun, 4 Nov 2018 15:23:00 +0100 Subject: Help: new section on conditional generator expressions Before, the closely related signatures $ $ were explained in two different sections. The former section was badly explained, with '0' and '1' in place of the formal parameter 'condition'. --- Help/manual/cmake-generator-expressions.7.rst | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 6f17812..094bfc1 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -25,6 +25,21 @@ conditional include directories, and more. The conditions may be based on the build configuration, target properties, platform information or any other queryable information. +Conditional Expressions +======================= + +Conditional expressions depend on a boolean condition that must be +``0`` or ``1``. + +``$`` + Evaluates to ``true_value`` if ``condition`` is ``1``. + Otherwise evaluates to the empty string. + +``$`` + Evaluates to ``true_value`` if ``condition`` is ``1``. + Otherwise evaluates to ``false_value``. + + Logical Expressions =================== @@ -58,10 +73,6 @@ Available logical expressions are: ``$`` ``0`` if ``condition`` is ``1``, else ``1`` -``$`` - ``true_value`` if ``condition`` is ``1``, - ``false_value`` if ``condition`` is ``0`` - ``$`` ``1`` if ``a`` is STREQUAL ``b``, else ``0`` ``$`` @@ -289,10 +300,6 @@ where ``${prop}`` refers to a helper variable: Available output expressions are: -``$<0:...>`` - Empty string (ignores ``...``) -``$<1:...>`` - Content of ``...`` ``$`` Joins the list with the content of ``...`` ``$`` -- cgit v0.12 From 9891adf74becfa95463f6928fda9f8ac17c934bd Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sun, 4 Nov 2018 15:40:58 +0100 Subject: Help: Cross-link conditional and boolean expressions. Rename Logical -> Boolean Generator Expressions. It's the return type that helps us to sort the expression zoo. --- Help/manual/cmake-generator-expressions.7.rst | 42 +++++++++++++++------------ 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 094bfc1..1c3d3fc 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -25,11 +25,13 @@ conditional include directories, and more. The conditions may be based on the build configuration, target properties, platform information or any other queryable information. -Conditional Expressions -======================= +.. _`Conditional Generator Expressions`: -Conditional expressions depend on a boolean condition that must be -``0`` or ``1``. +Conditional Generator Expressions +================================= + +Conditional generator expressions depend on a boolean condition +that must be ``0`` or ``1``. ``$`` Evaluates to ``true_value`` if ``condition`` is ``1``. @@ -39,23 +41,27 @@ Conditional expressions depend on a boolean condition that must be Evaluates to ``true_value`` if ``condition`` is ``1``. Otherwise evaluates to ``false_value``. - -Logical Expressions -=================== - -Logical expressions are used to create conditional output. The basic -expressions are the ``0`` and ``1`` expressions. Because other logical -expressions evaluate to either ``0`` or ``1``, they can be composed to -create conditional output: +Typically, the ``condition`` is a +:ref:`boolean generator expression`. +For instance, .. code-block:: cmake $<$:DEBUG_MODE> expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and -otherwise expands to nothing. +otherwise expands to the empty string. + +.. _`Boolean Generator Expressions`: + +Boolean Generator Expressions +============================= + +Boolean expressions evaluate to either ``0`` or ``1``. +They are typically used to construct the condition in a +:ref:`conditional generator expression`. -Available logical expressions are: +Available boolean expressions are: ``$`` ``1`` if the ``condition`` is true, else ``0`` @@ -171,8 +177,8 @@ Available logical expressions are: add_executable(myapp main.cpp) target_link_libraries(myapp myapp_c myapp_cxx) -Informational Expressions -========================= +Informational Generator Expressions +=================================== These expressions expand to some information. The information may be used directly, eg: @@ -272,8 +278,8 @@ Available informational expressions are: the unary version for notes about portability of this generator expression. -Output Expressions -================== +Output Generator Expressions +============================ These expressions generate output, in some cases depending on an input. These expressions may be combined with other expressions for information or logical -- cgit v0.12 From fe8acf7c0540ca39300bab5b014e428e84077c7a Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sun, 4 Nov 2018 15:48:02 +0100 Subject: Help: 3 subtypes of boolean generator expressions. Main classification by return type, subclassification by dependences --- Help/manual/cmake-generator-expressions.7.rst | 30 ++++++++++++++++++--------- 1 file changed, 20 insertions(+), 10 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 1c3d3fc..099d398 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -63,6 +63,9 @@ They are typically used to construct the condition in a Available boolean expressions are: +Logical Operators +----------------- + ``$`` ``1`` if the ``condition`` is true, else ``0`` @@ -79,12 +82,29 @@ Available boolean expressions are: ``$`` ``0`` if ``condition`` is ``1``, else ``1`` +String Comparisons +------------------ + ``$`` ``1`` if ``a`` is STREQUAL ``b``, else ``0`` ``$`` ``1`` if ``a`` is EQUAL ``b`` in a numeric comparison, else ``0`` ``$`` ``1`` if ``a`` is IN_LIST ``b``, else ``0`` +``$`` + ``1`` if ``v1`` is a version less than ``v2``, else ``0``. +``$`` + ``1`` if ``v1`` is a version greater than ``v2``, else ``0``. +``$`` + ``1`` if ``v1`` is the same version as ``v2``, else ``0``. +``$`` + ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. +``$`` + ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. + +Variable Queries +---------------- + ``$`` ``1`` if ``target`` exists, else ``0``. ``$`` @@ -104,16 +124,6 @@ Available boolean expressions are: ``1`` if the CMake-id of the CXX compiler matches ``compiler_id``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` - ``1`` if ``v1`` is a version less than ``v2``, else ``0``. -``$`` - ``1`` if ``v1`` is a version greater than ``v2``, else ``0``. -``$`` - ``1`` if ``v1`` is the same version as ``v2``, else ``0``. -``$`` - ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. -``$`` - ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. ``$`` ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -- cgit v0.12 From ff1db47728a37a7775a3b870ff9ffdc3249c3d40 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sun, 4 Nov 2018 17:08:25 +0100 Subject: Help: Revise documentation of string-valued generator expressions * Consolidate examples * Sort, and insert subsection headers --- Help/manual/cmake-generator-expressions.7.rst | 203 ++++++++++++++------------ 1 file changed, 111 insertions(+), 92 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 099d398..187f3b7 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -102,6 +102,7 @@ String Comparisons ``$`` ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. + Variable Queries ---------------- @@ -144,6 +145,9 @@ Variable Queries for the 'head' target, an error is reported. See the :manual:`cmake-compile-features(7)` manual for information on compile features and a list of supported compilers. + +.. _`Boolean COMPILE_LANGUAGE Generator Expression`: + ``$`` ``1`` when the language used for compilation unit matches ``language``, otherwise ``0``. This expression may be used to specify compile options, @@ -187,20 +191,22 @@ Variable Queries add_executable(myapp main.cpp) target_link_libraries(myapp myapp_c myapp_cxx) -Informational Generator Expressions +String-Valued Generator Expressions =================================== -These expressions expand to some information. The information may be used -directly, eg: +These expressions expand to some string. +For example, .. code-block:: cmake include_directories(/usr/include/$/) expands to ``/usr/include/GNU/`` or ``/usr/include/Clang/`` etc, depending on -the Id of the compiler. +the compiler identifier. -These expressions may also may be combined with logical expressions: +String-valued expressions may also be combined with other expressions. +Here an example for a string-valued expression within a boolean expressions +within a conditional expression: .. code-block:: cmake @@ -210,12 +216,95 @@ expands to ``OLD_COMPILER`` if the :variable:`CMAKE_CXX_COMPILER_VERSION _COMPILER_VERSION>` is less than 4.2.0. +And here two nested string-valued expressions: + +.. code-block:: cmake + + -I$, -I> + +generates a string of the entries in the :prop_tgt:`INCLUDE_DIRECTORIES` target +property with each entry preceded by ``-I``. + +Expanding on the previous example, if one first wants to check if the +``INCLUDE_DIRECTORIES`` property is non-empty, then it is advisable to +introduce a helper variable to keep the code readable: + +.. code-block:: cmake + + set(prop "$") # helper variable + $<$:-I$> + Available informational expressions are: -``$`` - Configuration name. Deprecated. Use ``CONFIG`` instead. +Escaped Characters +------------------ + +String literals to escape the special meaning a character would otherwise have: + +``$`` + A literal ``>``. Used for example to compare strings that contain a ``>``. +``$`` + A literal ``,``. Used for example to compare strings which contain a ``,``. +``$`` + A literal ``;``. Used to prevent list expansion on an argument with ``;``. + +String Operations +----------------- + +``$`` + Joins the list with the content of ``string`` +``$`` + Content of ``string`` converted to lower case. +``$`` + Content of ``string`` converted to upper case. + +``$`` + Content of ``expr`` evaluated as a generator expression in the current + context. This enables consumption of generator expressions whose + evaluation results itself in generator expressions. +``$`` + Content of ``expr`` evaluated as a generator expression in the context of + ``tgt`` target. This enables consumption of custom target properties that + themselves contain generator expressions. + + Having the capability to evaluate generator expressions is very useful when + you want to manage custom properties supporting generator expressions. + For example: + + .. code-block:: cmake + + add_library(foo ...) + + set_property(TARGET foo PROPERTY + CUSTOM_KEYS $<$:FOO_EXTRA_THINGS> + ) + + add_custom_target(printFooKeys + COMMAND ${CMAKE_COMMAND} -E echo $ + ) + + This naive implementation of the ``printFooKeys`` custom command is wrong + because ``CUSTOM_KEYS`` target property is not evaluated and the content + is passed as is (i.e. ``$<$:FOO_EXTRA_THINGS>``). + + To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is + ``Debug``), it is required to evaluate the output of + ``$``: + + .. code-block:: cmake + + add_custom_target(printFooKeys + COMMAND ${CMAKE_COMMAND} -E + echo $> + ) + +Variable Queries +---------------- + ``$`` Configuration name +``$`` + Configuration name. Deprecated. Use ``CONFIG`` instead. ``$`` The CMake-id of the platform. See also the :variable:`CMAKE_SYSTEM_NAME` variable. @@ -231,6 +320,19 @@ Available informational expressions are: ``$`` The version of the CXX compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. +``$`` + The compile language of source files when evaluating compile options. + See :ref:`the related boolean expression + ` + ``$`` + for notes about the portability of this generator expression. + +Target-Dependent Queries +------------------------ + +``$`` + Expands to the ``tgt`` if the given target exists, an empty string + otherwise. ``$`` Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a target. ``$`` @@ -283,54 +385,14 @@ Available informational expressions are: ``$`` Content of the install prefix when the target is exported via :command:`install(EXPORT)` and empty otherwise. -``$`` - The compile language of source files when evaluating compile options. See - the unary version for notes about portability of this generator - expression. -Output Generator Expressions -============================ +Output-Related Expressions +-------------------------- -These expressions generate output, in some cases depending on an input. These -expressions may be combined with other expressions for information or logical -comparison: - -.. code-block:: cmake - - -I$, -I> - -generates a string of the entries in the :prop_tgt:`INCLUDE_DIRECTORIES` target -property with each entry preceded by ``-I``. Note that a more-complete use -in this situation would require first checking if the INCLUDE_DIRECTORIES -property is non-empty: - -.. code-block:: cmake - - $<$:-I$> - -where ``${prop}`` refers to a helper variable: - -.. code-block:: cmake - - set(prop "$") - -Available output expressions are: - -``$`` - Joins the list with the content of ``...`` -``$`` - A literal ``>``. Used to compare strings which contain a ``>`` for example. -``$`` - A literal ``,``. Used to compare strings which contain a ``,`` for example. -``$`` - A literal ``;``. Used to prevent list expansion on an argument with ``;``. ``$`` 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. -``$`` - Expands to the ``...`` if the given target exists, an empty string - otherwise. ``$`` Content of ``...`` except when evaluated in a link interface while propagating :ref:`Target Usage Requirements`, in which case it is the @@ -345,10 +407,6 @@ Available output expressions are: Content of ``...`` when the property is exported using :command:`export`, or when the target is used by another target in the same buildsystem. Expands to the empty string otherwise. -``$`` - Content of ``...`` converted to lower case. -``$`` - Content of ``...`` converted to upper case. ``$`` Content of ``...`` converted to a C identifier. The conversion follows the same behavior as :command:`string(MAKE_C_IDENTIFIER)`. @@ -359,42 +417,3 @@ Available output expressions are: Content of ``...`` converted to shell path style. For example, slashes are converted to backslashes in Windows shells and drive letters are converted to posix paths in MSYS shells. The ``...`` must be an absolute path. -``$`` - Content of ``...`` evaluated as a generator expression in the current - context. This enables consumption of generator expressions - whose evaluation results itself in generator expressions. -``$`` - Content of ``...`` evaluated as a generator expression in the context of - ``tgt`` target. This enables consumption of custom target properties that - themselves contain generator expressions. - - Having the capability to evaluate generator expressions is very useful when - you want to manage custom properties supporting generator expressions. - For example: - - .. code-block:: cmake - - add_library(foo ...) - - set_property(TARGET foo PROPERTY - CUSTOM_KEYS $<$:FOO_EXTRA_THINGS> - ) - - add_custom_target(printFooKeys - COMMAND ${CMAKE_COMMAND} -E echo $ - ) - - This naive implementation of the ``printFooKeys`` custom command is wrong - because ``CUSTOM_KEYS`` target property is not evaluated and the content - is passed as is (i.e. ``$<$:FOO_EXTRA_THINGS>``). - - To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is - ``Debug``), it is required to evaluate the output of - ``$``: - - .. code-block:: cmake - - add_custom_target(printFooKeys - COMMAND ${CMAKE_COMMAND} -E - echo $> - ) -- cgit v0.12 From a85e5e6f4d53dd158392dd74b9632d84fb583722 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sun, 4 Nov 2018 18:26:13 +0100 Subject: Help: Add note on omitted <..> notation in cmake-generator-expressions(7) --- Help/manual/cmake-generator-expressions.7.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 187f3b7..929d120 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -25,6 +25,11 @@ conditional include directories, and more. The conditions may be based on the build configuration, target properties, platform information or any other queryable information. +Generator expressions have the form ``$<...>``. To avoid confusion, this page +deviates from most of the CMake documentation in that it omits angular brackets +``<...>`` around placeholders like ``condition``, ``true_value``, ``string``, +and so on. + .. _`Conditional Generator Expressions`: Conditional Generator Expressions -- cgit v0.12 From 867c9c9c0dc2782b2d822557c8dc83c451409b48 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sun, 4 Nov 2018 18:51:38 +0100 Subject: Help: Add deprecation date of $ --- Help/manual/cmake-generator-expressions.7.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 929d120..4f2036e 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -309,7 +309,7 @@ Variable Queries ``$`` Configuration name ``$`` - Configuration name. Deprecated. Use ``CONFIG`` instead. + Configuration name. Deprecated since CMake 3.0. Use ``CONFIG`` instead. ``$`` The CMake-id of the platform. See also the :variable:`CMAKE_SYSTEM_NAME` variable. -- cgit v0.12 From fb423b3c49d21df851b1d4a91fddfe94d835155b Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sun, 4 Nov 2018 19:31:22 +0100 Subject: Help: sort conditional expressions below string-valued ones. Makes things yet clearer and simpler. Also correct remnant of "informational expression". --- Help/manual/cmake-generator-expressions.7.rst | 59 +++++++++++++-------------- 1 file changed, 29 insertions(+), 30 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 4f2036e..cbeb348 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -30,41 +30,14 @@ deviates from most of the CMake documentation in that it omits angular brackets ``<...>`` around placeholders like ``condition``, ``true_value``, ``string``, and so on. -.. _`Conditional Generator Expressions`: - -Conditional Generator Expressions -================================= - -Conditional generator expressions depend on a boolean condition -that must be ``0`` or ``1``. - -``$`` - Evaluates to ``true_value`` if ``condition`` is ``1``. - Otherwise evaluates to the empty string. - -``$`` - Evaluates to ``true_value`` if ``condition`` is ``1``. - Otherwise evaluates to ``false_value``. - -Typically, the ``condition`` is a -:ref:`boolean generator expression`. -For instance, - -.. code-block:: cmake - - $<$:DEBUG_MODE> - -expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and -otherwise expands to the empty string. - .. _`Boolean Generator Expressions`: Boolean Generator Expressions ============================= Boolean expressions evaluate to either ``0`` or ``1``. -They are typically used to construct the condition in a -:ref:`conditional generator expression`. +They are typically used to construct the condition in a :ref:`conditional +generator expression`. Available boolean expressions are: @@ -239,7 +212,7 @@ introduce a helper variable to keep the code readable: set(prop "$") # helper variable $<$:-I$> -Available informational expressions are: +The following string-valued generator expressions are available: Escaped Characters ------------------ @@ -253,6 +226,32 @@ String literals to escape the special meaning a character would otherwise have: ``$`` A literal ``;``. Used to prevent list expansion on an argument with ``;``. +.. _`Conditional Generator Expressions`: + +Conditional Expressions +----------------------- + +Conditional generator expressions depend on a boolean condition +that must be ``0`` or ``1``. + +``$`` + Evaluates to ``true_string`` if ``condition`` is ``1``. + Otherwise evaluates to the empty string. + +``$`` + Evaluates to ``true_string`` if ``condition`` is ``1``. + Otherwise evaluates to ``false_string``. + +Typically, the ``condition`` is a :ref:`boolean generator expression +`. For instance, + +.. code-block:: cmake + + $<$:DEBUG_MODE> + +expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and +otherwise expands to the empty string. + String Operations ----------------- -- cgit v0.12 From 3fa0a03b7e4094bef1b66e48ed437e1c0b41c49a Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sun, 4 Nov 2018 19:51:06 +0100 Subject: Help: Expand placeholders in string comparisons. And point out that STREQUAL is case sensitive. --- Help/manual/cmake-generator-expressions.7.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index cbeb348..27bf7d1 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -63,12 +63,14 @@ Logical Operators String Comparisons ------------------ -``$`` - ``1`` if ``a`` is STREQUAL ``b``, else ``0`` -``$`` - ``1`` if ``a`` is EQUAL ``b`` in a numeric comparison, else ``0`` -``$`` - ``1`` if ``a`` is IN_LIST ``b``, else ``0`` +``$`` + ``1`` if ``string1`` and ``string2`` are equal, else ``0``. + The comparison is case-sensitive. +``$`` + ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0`` +``$`` + ``1`` if ``string`` is member of the comma-separated ``list``, else ``0``. + Uses case-sensitive comparisons. ``$`` ``1`` if ``v1`` is a version less than ``v2``, else ``0``. ``$`` -- cgit v0.12 From e045fb202ddf9100965ac418f4aa22e65256dd8d Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sun, 4 Nov 2018 19:54:20 +0100 Subject: Help: Terminate explanations with a dot. --- Help/manual/cmake-generator-expressions.7.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 27bf7d1..bf11b05 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -58,7 +58,7 @@ Logical Operators Otherwise evaluates to ``0``. ``$`` - ``0`` if ``condition`` is ``1``, else ``1`` + ``0`` if ``condition`` is ``1``, else ``1``. String Comparisons ------------------ @@ -67,7 +67,7 @@ String Comparisons ``1`` if ``string1`` and ``string2`` are equal, else ``0``. The comparison is case-sensitive. ``$`` - ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0`` + ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``. ``$`` ``1`` if ``string`` is member of the comma-separated ``list``, else ``0``. Uses case-sensitive comparisons. @@ -258,7 +258,7 @@ String Operations ----------------- ``$`` - Joins the list with the content of ``string`` + Joins the list with the content of ``string``. ``$`` Content of ``string`` converted to lower case. ``$`` @@ -308,7 +308,7 @@ Variable Queries ---------------- ``$`` - Configuration name + Configuration name. ``$`` Configuration name. Deprecated since CMake 3.0. Use ``CONFIG`` instead. ``$`` -- cgit v0.12 From 2b2b41f038af97b7bca2213cda0198d2a28f6c2e Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sun, 4 Nov 2018 20:03:43 +0100 Subject: Help: Code example for case-insensitive comparison --- Help/manual/cmake-generator-expressions.7.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index bf11b05..c5d7a31 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -65,7 +65,14 @@ String Comparisons ``$`` ``1`` if ``string1`` and ``string2`` are equal, else ``0``. - The comparison is case-sensitive. + The comparison is case-sensitive. For a case-insensitive comparison, + combine with a :ref:`string transforming generator expression + `, + + .. code-block:: cmake + + $,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ... + ``$`` ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``. ``$`` @@ -254,8 +261,10 @@ Typically, the ``condition`` is a :ref:`boolean generator expression expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and otherwise expands to the empty string. -String Operations ------------------ +.. _`String Transforming Generator Expressions`: + +String Transformations +---------------------- ``$`` Joins the list with the content of ``string``. -- cgit v0.12 From e0f0f80f0286b7181b1203693799f5fcfcd8b4af Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sun, 4 Nov 2018 23:00:12 +0100 Subject: Help: Explain conversion rules of $. This resolves #18549. --- Help/manual/cmake-generator-expressions.7.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index c5d7a31..eb9c9fe 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -44,8 +44,16 @@ Available boolean expressions are: Logical Operators ----------------- -``$`` - ``1`` if the ``condition`` is true, else ``0`` +``$`` + Converts ``string`` to ``0`` or ``1`` according to the rules of the + :command:`if()` command. Evaluates to ``0`` if any of the following is true: + + * ``string`` is empty, + * ``string`` is a case-insensitive equal of + ``0``, ``FALSE``, ``OFF``, ``N``, ``NO``, ``IGNORE``, or ``NOTFOUND``, or + * ``string`` ends in the suffix ``-NOTFOUND`` (case-sensitive). + + Otherwise evaluates to ``1``. ``$`` where ``conditions`` is a comma-separated list of boolean expressions. -- cgit v0.12 From ab1d7df7575503c8eabdf6f8892b5944b06d98e5 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (h)" Date: Sun, 4 Nov 2018 23:13:21 +0100 Subject: Help: add section on debugging generator expressions. This resolves #18550. --- Help/manual/cmake-generator-expressions.7.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index eb9c9fe..b5c4457 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -440,3 +440,25 @@ Output-Related Expressions Content of ``...`` converted to shell path style. For example, slashes are converted to backslashes in Windows shells and drive letters are converted to posix paths in MSYS shells. The ``...`` must be an absolute path. + +Debugging +========= + +Since generator expressions are evaluated during generation of the buildsystem, +and not during processing of ``CMakeLists.txt`` files, it is not possible to +inspect their result with the :command:`message()` command. + +One possible way to generate debug messages is to add a custom target, + +.. code-block:: cmake + + add_custom_target(genexdebug COMMAND ${CMAKE_COMMAND} -E echo "$<...>") + +The shell command ``make genexdebug`` (invoked after execution of ``cmake``) +would then print the result of ``$<...>``. + +Another way is to write debug messages to a file: + +.. code-block:: cmake + + file(GENERATE OUTPUT filename CONTENT "$<...>") -- cgit v0.12 From 86c07b916557ac83cd77f6250d090fa45b4b9bc2 Mon Sep 17 00:00:00 2001 From: "Joachim Wuttke (o)" Date: Tue, 6 Nov 2018 12:54:32 +0100 Subject: Help: Say early on that generator expressions can be nested. --- Help/manual/cmake-generator-expressions.7.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index b5c4457..63e43e1 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -27,8 +27,10 @@ queryable information. Generator expressions have the form ``$<...>``. To avoid confusion, this page deviates from most of the CMake documentation in that it omits angular brackets -``<...>`` around placeholders like ``condition``, ``true_value``, ``string``, -and so on. +``<...>`` around placeholders like ``condition``, ``string``, ``target``, +among others. + +Generator expressions can be nested, as shown in most of the examples below. .. _`Boolean Generator Expressions`: -- cgit v0.12