diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 50c816cc3d..ca4ea3e0aa 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -46,7 +46,8 @@ Available boolean expressions are: Logical Operators ----------------- -``$`` +.. genex:: $ + Converts ``string`` to ``0`` or ``1``. Evaluates to ``0`` if any of the following is true: @@ -57,23 +58,27 @@ Logical Operators Otherwise evaluates to ``1``. -``$`` +.. genex:: $ + where ``conditions`` is a comma-separated list of boolean expressions. Evaluates to ``1`` if all conditions are ``1``. Otherwise evaluates to ``0``. -``$`` +.. genex:: $ + 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``. -``$`` +.. genex:: $ + ``0`` if ``condition`` is ``1``, else ``1``. String Comparisons ------------------ -``$`` +.. genex:: $ + ``1`` if ``string1`` and ``string2`` are equal, else ``0``. The comparison is case-sensitive. For a case-insensitive comparison, combine with a :ref:`string transforming generator expression @@ -83,100 +88,150 @@ String Comparisons $,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ... -``$`` +.. genex:: $ + ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``. -``$`` + +.. genex:: $ + ``1`` if ``string`` is member of the semicolon-separated ``list``, else ``0``. Uses case-sensitive comparisons. -``$`` + +.. genex:: $ + ``1`` if ``v1`` is a version less than ``v2``, else ``0``. -``$`` + +.. genex:: $ + ``1`` if ``v1`` is a version greater than ``v2``, else ``0``. -``$`` + +.. genex:: $ + ``1`` if ``v1`` is the same version as ``v2``, else ``0``. -``$`` + +.. genex:: $ + ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. -``$`` + +.. genex:: $ + ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. Variable Queries ---------------- -``$`` +.. genex:: $ + ``1`` if ``target`` exists, else ``0``. -``$`` + +.. genex:: $ + ``1`` if config is any one of the entries in ``cfgs``, 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. -``$`` + +.. genex:: $ + where ``platform_ids`` is a comma-separated list. ``1`` if the CMake's platform id matches any one of the entries in ``platform_ids``, otherwise ``0``. See also the :variable:`CMAKE_SYSTEM_NAME` variable. -``$`` + +.. genex:: $ + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the C compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the CXX compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the CUDA compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the Objective-C compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the Objective-C++ compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the Fortran compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + where ``compiler_ids`` is a comma-separated list. ``1`` if the CMake's compiler id of the ISPC compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. 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. -``$`` + +.. genex:: $ + 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 @@ -188,7 +243,8 @@ Variable Queries .. _`Boolean COMPILE_LANGUAGE Generator Expression`: -``$`` +.. genex:: $ + ``1`` when the language used for compilation unit matches ``language`` and the CMake's compiler id of the language compiler matches any one of the entries in ``compiler_ids``, otherwise ``0``. This expression is a short form @@ -224,7 +280,8 @@ Variable Queries $<$,$>:COMPILING_C_WITH_CLANG> ) -``$`` +.. genex:: $ + ``1`` when the language used for compilation unit matches any of the entries in ``languages``, otherwise ``0``. This expression may be used to specify compile options, compile definitions, and include directories for source files of a @@ -269,7 +326,8 @@ Variable Queries .. _`Boolean LINK_LANGUAGE Generator Expression`: -``$`` +.. genex:: $ + ``1`` when the language used for link step matches ``language`` and the CMake's compiler id of the language linker matches any one of the entries in ``compiler_ids``, otherwise ``0``. This expression is a short form for the @@ -308,7 +366,8 @@ Variable Queries ``$`` for constraints about the usage of this generator expression. -``$`` +.. genex:: $ + ``1`` when the language used for link step matches any of the entries in ``languages``, otherwise ``0``. This expression may be used to specify link libraries, link options, link directories and link dependencies of a @@ -370,14 +429,16 @@ Variable Queries evaluation will give ``C`` as link language, so the second pass will correctly add target ``libother`` as link dependency. -``$`` +.. genex:: $ + Returns the list if it is the device link step, an empty list otherwise. The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION` and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and policy :policy:`CMP0105`. This expression can only be used to specify link options. -``$`` +.. genex:: $ + Returns the list if it is the normal link step, an empty list otherwise. This expression is mainly useful when a device link step is also involved (see ``$`` generator expression). This expression can only @@ -433,11 +494,16 @@ Escaped Characters String literals to escape the special meaning a character would otherwise have: -``$`` +.. genex:: $ + A literal ``>``. Used for example to compare strings that contain a ``>``. -``$`` + +.. genex:: $ + A literal ``,``. Used for example to compare strings which contain a ``,``. -``$`` + +.. genex:: $ + A literal ``;``. Used to prevent list expansion on an argument with ``;``. .. _`Conditional Generator Expressions`: @@ -448,11 +514,13 @@ Conditional Expressions Conditional generator expressions depend on a boolean condition that must be ``0`` or ``1``. -``$`` +.. genex:: $ + Evaluates to ``true_string`` if ``condition`` is ``1``. Otherwise evaluates to the empty string. -``$`` +.. genex:: $ + Evaluates to ``true_string`` if ``condition`` is ``1``. Otherwise evaluates to ``false_string``. @@ -471,22 +539,34 @@ otherwise expands to the empty string. String Transformations ---------------------- -``$`` +.. genex:: $ + Joins the list with the content of ``string``. -``$`` + +.. genex:: $ + Removes duplicated items in the given ``list``. -``$`` + +.. genex:: $ + Includes or removes items from ``list`` that match the regular expression ``regex``. -``$`` + +.. genex:: $ + Content of ``string`` converted to lower case. -``$`` + +.. genex:: $ + Content of ``string`` converted to upper case. -``$`` +.. genex:: $ + 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. -``$`` + +.. genex:: $ + 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. @@ -525,62 +605,99 @@ String Transformations Variable Queries ---------------- -``$`` +.. genex:: $ + Configuration name. -``$`` + +.. genex:: $ + Configuration name. Deprecated since CMake 3.0. Use ``CONFIG`` instead. -``$`` + +.. genex:: $ + The current system's CMake platform id. See also the :variable:`CMAKE_SYSTEM_NAME` variable. -``$`` + +.. genex:: $ + The CMake's compiler id of the C compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + The CMake's compiler id of the CXX compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + The CMake's compiler id of the CUDA compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + The CMake's compiler id of the OBJC compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + The CMake's compiler id of the OBJCXX compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + The CMake's compiler id of the Fortran compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + The CMake's compiler id of the ISPC compiler used. See also the :variable:`CMAKE__COMPILER_ID` variable. -``$`` + +.. genex:: $ + The version of the C compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + The version of the CXX compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + The version of the CUDA compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + The version of the OBJC compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + The version of the OBJCXX compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + The version of the Fortran compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + The version of the ISPC compiler used. See also the :variable:`CMAKE__COMPILER_VERSION` variable. -``$`` + +.. genex:: $ + 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. -``$`` + +.. genex:: $ + The link language of target when evaluating link options. See :ref:`the related boolean expression ` ``$`` @@ -607,14 +724,19 @@ In the following, "the ``tgt`` filename" means the name of the ``tgt`` binary file. This has to be distinguished from "the target name", which is just the string ``tgt``. -``$`` +.. genex:: $ + The target name ``tgt`` if the target exists, an empty string otherwise. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + Full path to the ``tgt`` binary file. -``$`` + +.. genex:: $ + Base name of ``tgt``, i.e. ``$`` without prefix and suffix. For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``. @@ -631,36 +753,48 @@ which is just the string ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + Prefix of the ``tgt`` filename (such as ``lib``). See also the :prop_tgt:`PREFIX` target property. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + Suffix of the ``tgt`` filename (extension such as ``.so`` or ``.exe``). See also the :prop_tgt:`SUFFIX` target property. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + The ``tgt`` filename. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + Directory of the ``tgt`` binary file. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + File used when linking to the ``tgt`` target. This will usually be the library that ``tgt`` represents (``.a``, ``.lib``, ``.so``), but for a shared library on DLL platforms, it would be the ``.lib`` import library associated with the DLL. -``$`` + +.. genex:: $ + Base name of file used to link the target ``tgt``, i.e. ``$`` without prefix and suffix. For example, if target file name is ``libbase.a``, the base name is ``base``. @@ -676,7 +810,9 @@ which is just the string ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + Prefix of file used to link target ``tgt``. See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target @@ -684,7 +820,9 @@ which is just the string ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + Suffix of file used to link where ``tgt`` is the name of a target. The suffix corresponds to the file extension (such as ".so" or ".lib"). @@ -694,36 +832,49 @@ which is just the string ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + Name of file used to link target ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + Directory of file used to link target ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + File with soname (``.so.3``) where ``tgt`` is the name of a target. -``$`` +.. genex:: $ + Name of file with soname (``.so.3``). Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + Directory of with soname (``.so.3``). Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + Full path to the linker generated program database file (.pdb) where ``tgt`` is the name of a target. See also the :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY` target properties and their configuration specific variants :prop_tgt:`PDB_NAME_` and :prop_tgt:`PDB_OUTPUT_DIRECTORY_`. -``$`` + +.. genex:: $ + Base name of the linker generated program database file (.pdb) where ``tgt`` is the name of a target. @@ -739,23 +890,31 @@ which is just the string ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + Name of the linker generated program database file (.pdb). Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + Directory of the linker generated program database file (.pdb). Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + Full path to the bundle directory (``my.app``, ``my.framework``, or ``my.bundle``) where ``tgt`` is the name of a target. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + Full path to the bundle content directory where ``tgt`` is the name of a target. For the macOS SDK it leads to ``my.app/Contents``, ``my.framework``, or ``my.bundle/Contents``. For all other SDKs (e.g. iOS) it leads to @@ -764,17 +923,23 @@ which is just the string ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). -``$`` + +.. genex:: $ + Value of the property ``prop`` on the target ``tgt``. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on. -``$`` + +.. genex:: $ + Value of the property ``prop`` on the target for which the expression 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:: $ + Content of the install prefix when the target is exported via :command:`install(EXPORT)`, or when evaluated in :prop_tgt:`INSTALL_NAME_DIR`, and empty otherwise. @@ -782,30 +947,43 @@ which is just the string ``tgt``. Output-Related Expressions -------------------------- -``$`` +.. 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. -``$`` + +.. genex:: $ + Content of ``...`` except when evaluated in a link interface while propagating :ref:`Target Usage Requirements`, in which case it is the empty string. Intended for use only in an :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property, perhaps via the :command:`target_link_libraries` command, to specify private link dependencies without other usage requirements. -``$`` + +.. genex:: $ + Content of ``...`` when the property is exported using :command:`install(EXPORT)`, and empty otherwise. -``$`` + +.. genex:: $ + 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. -``$`` + +.. genex:: $ + Content of ``...`` converted to a C identifier. The conversion follows the same behavior as :command:`string(MAKE_C_IDENTIFIER)`. -``$`` + +.. genex:: $ + List of objects resulting from build of ``objLib``. -``$`` + +.. genex:: $ + 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. @@ -815,7 +993,8 @@ Output-Related Expressions ``;`` on Windows). Be sure to enclose the argument containing this genex in double quotes in CMake source code so that ``;`` does not split arguments. -``$`` +.. genex:: $ + .. versionadded:: 3.20 Only valid in :command:`add_custom_command` and :command:`add_custom_target` @@ -824,7 +1003,8 @@ Output-Related Expressions in ``...`` are evaluated using the custom command's "output config". With other generators, the content of ``...`` is evaluated normally. -``$`` +.. genex:: $ + .. versionadded:: 3.20 Only valid in :command:`add_custom_command` and :command:`add_custom_target`