diff options
Diffstat (limited to 'Help/manual/cmake-generator-expressions.7.rst')
-rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 160 |
1 files changed, 153 insertions, 7 deletions
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 7bc490f70..5d508cb0d 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -94,6 +94,8 @@ String Comparisons .. genex:: $<IN_LIST:string,list> + .. versionadded:: 3.12 + ``1`` if ``string`` is member of the semicolon-separated ``list``, else ``0``. Uses case-sensitive comparisons. @@ -111,10 +113,14 @@ String Comparisons .. genex:: $<VERSION_LESS_EQUAL:v1,v2> + .. versionadded:: 3.7 + ``1`` if ``v1`` is a version less than or equal to ``v2``, else ``0``. .. genex:: $<VERSION_GREATER_EQUAL:v1,v2> + .. versionadded:: 3.7 + ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. Variable Queries @@ -122,6 +128,8 @@ Variable Queries .. genex:: $<TARGET_EXISTS:target> + .. versionadded:: 3.12 + ``1`` if ``target`` exists, else ``0``. .. genex:: $<CONFIG:cfgs> @@ -155,6 +163,8 @@ Variable Queries .. genex:: $<CUDA_COMPILER_ID:compiler_ids> + .. versionadded:: 3.15 + 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``. @@ -162,6 +172,8 @@ Variable Queries .. genex:: $<OBJC_COMPILER_ID:compiler_ids> + .. versionadded:: 3.16 + 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``. @@ -169,6 +181,8 @@ Variable Queries .. genex:: $<OBJCXX_COMPILER_ID:compiler_ids> + .. versionadded:: 3.16 + 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``. @@ -181,8 +195,17 @@ Variable Queries of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +.. genex:: $<HIP_COMPILER_ID:compiler_ids> + + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the HIP compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + .. genex:: $<ISPC_COMPILER_ID:compiler_ids> + .. versionadded:: 3.19 + 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``. @@ -200,16 +223,22 @@ Variable Queries .. genex:: $<CUDA_COMPILER_VERSION:version> + .. versionadded:: 3.15 + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<OBJC_COMPILER_VERSION:version> + .. versionadded:: 3.16 + ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<OBJCXX_COMPILER_VERSION:version> + .. versionadded:: 3.16 + ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. @@ -218,8 +247,15 @@ Variable Queries ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +.. genex:: $<HIP_COMPILER_VERSION:version> + + ``1`` if the version of the HIP compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + .. genex:: $<ISPC_COMPILER_VERSION:version> + .. versionadded:: 3.19 + ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. @@ -232,6 +268,8 @@ Variable Queries .. genex:: $<COMPILE_FEATURES:features> + .. versionadded:: 3.1 + 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 @@ -245,6 +283,8 @@ Variable Queries .. genex:: $<COMPILE_LANG_AND_ID:language,compiler_ids> + .. versionadded:: 3.15 + ``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 @@ -282,6 +322,8 @@ Variable Queries .. genex:: $<COMPILE_LANGUAGE:languages> + .. versionadded:: 3.3 + ``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 @@ -328,6 +370,8 @@ Variable Queries .. genex:: $<LINK_LANG_AND_ID:language,compiler_ids> + .. versionadded:: 3.18 + ``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 @@ -368,6 +412,8 @@ Variable Queries .. genex:: $<LINK_LANGUAGE:languages> + .. versionadded:: 3.18 + ``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 @@ -431,6 +477,8 @@ Variable Queries .. genex:: $<DEVICE_LINK:list> + .. versionadded:: 3.18 + 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 @@ -439,6 +487,8 @@ Variable Queries .. genex:: $<HOST_LINK:list> + .. versionadded:: 3.18 + 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 ``$<DEVICE_LINK:list>`` generator expression). This expression can only @@ -521,6 +571,8 @@ that must be ``0`` or ``1``. .. genex:: $<IF:condition,true_string,false_string> + .. versionadded:: 3.8 + Evaluates to ``true_string`` if ``condition`` is ``1``. Otherwise evaluates to ``false_string``. @@ -545,10 +597,14 @@ String Transformations .. genex:: $<REMOVE_DUPLICATES:list> + .. versionadded:: 3.15 + Removes duplicated items in the given ``list``. .. genex:: $<FILTER:list,INCLUDE|EXCLUDE,regex> + .. versionadded:: 3.15 + Includes or removes items from ``list`` that match the regular expression ``regex``. .. genex:: $<LOWER_CASE:string> @@ -561,12 +617,16 @@ String Transformations .. genex:: $<GENEX_EVAL:expr> + .. versionadded:: 3.12 + 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:: $<TARGET_GENEX_EVAL:tgt,expr> + .. versionadded:: 3.12 + 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. @@ -635,11 +695,15 @@ Variable Queries .. genex:: $<OBJC_COMPILER_ID> + .. versionadded:: 3.16 + The CMake's compiler id of the OBJC compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. .. genex:: $<OBJCXX_COMPILER_ID> + .. versionadded:: 3.16 + The CMake's compiler id of the OBJCXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. @@ -648,8 +712,15 @@ Variable Queries The CMake's compiler id of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +.. genex:: $<HIP_COMPILER_ID> + + The CMake's compiler id of the HIP compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. + .. genex:: $<ISPC_COMPILER_ID> + .. versionadded:: 3.19 + The CMake's compiler id of the ISPC compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. @@ -670,11 +741,15 @@ Variable Queries .. genex:: $<OBJC_COMPILER_VERSION> + .. versionadded:: 3.16 + The version of the OBJC compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<OBJCXX_COMPILER_VERSION> + .. versionadded:: 3.16 + The version of the OBJCXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. @@ -683,13 +758,22 @@ Variable Queries The version of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +.. genex:: $<HIP_COMPILER_VERSION> + + The version of the HIP compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. + .. genex:: $<ISPC_COMPILER_VERSION> + .. versionadded:: 3.19 + The version of the ISPC compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. .. genex:: $<COMPILE_LANGUAGE> + .. versionadded:: 3.3 + The compile language of source files when evaluating compile options. See :ref:`the related boolean expression <Boolean COMPILE_LANGUAGE Generator Expression>` @@ -698,6 +782,8 @@ Variable Queries .. genex:: $<LINK_LANGUAGE> + .. versionadded:: 3.18 + The link language of target when evaluating link options. See :ref:`the related boolean expression <Boolean LINK_LANGUAGE Generator Expression>` ``$<LINK_LANGUAGE:language>`` @@ -728,6 +814,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_NAME_IF_EXISTS:tgt> + .. versionadded:: 3.12 + 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 @@ -739,6 +827,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_FILE_BASE_NAME:tgt> + .. versionadded:: 3.15 + Base name of ``tgt``, i.e. ``$<TARGET_FILE_NAME:tgt>`` without prefix and suffix. For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``. @@ -758,6 +848,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_FILE_PREFIX:tgt> + .. versionadded:: 3.15 + Prefix of the ``tgt`` filename (such as ``lib``). See also the :prop_tgt:`PREFIX` target property. @@ -767,6 +859,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_FILE_SUFFIX:tgt> + .. versionadded:: 3.15 + Suffix of the ``tgt`` filename (extension such as ``.so`` or ``.exe``). See also the :prop_tgt:`SUFFIX` target property. @@ -797,6 +891,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_LINKER_FILE_BASE_NAME:tgt> + .. versionadded:: 3.15 + Base name of file used to link the target ``tgt``, i.e. ``$<TARGET_LINKER_FILE_NAME:tgt>`` without prefix and suffix. For example, if target file name is ``libbase.a``, the base name is ``base``. @@ -815,6 +911,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_LINKER_FILE_PREFIX:tgt> + .. versionadded:: 3.15 + Prefix of file used to link target ``tgt``. See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target @@ -825,6 +923,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_LINKER_FILE_SUFFIX:tgt> + .. versionadded:: 3.15 + 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"). @@ -868,6 +968,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_PDB_FILE:tgt> + .. versionadded:: 3.1 + Full path to the linker generated program database file (.pdb) where ``tgt`` is the name of a target. @@ -877,6 +979,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_PDB_FILE_BASE_NAME:tgt> + .. versionadded:: 3.15 + Base name of the linker generated program database file (.pdb) where ``tgt`` is the name of a target. @@ -895,6 +999,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_PDB_FILE_NAME:tgt> + .. versionadded:: 3.1 + Name of the linker generated program database file (.pdb). Note that ``tgt`` is not added as a dependency of the target this @@ -902,6 +1008,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_PDB_FILE_DIR:tgt> + .. versionadded:: 3.1 + Directory of the linker generated program database file (.pdb). Note that ``tgt`` is not added as a dependency of the target this @@ -909,6 +1017,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_BUNDLE_DIR:tgt> + .. versionadded:: 3.9 + Full path to the bundle directory (``my.app``, ``my.framework``, or ``my.bundle``) where ``tgt`` is the name of a target. @@ -917,6 +1027,8 @@ which is just the string ``tgt``. .. genex:: $<TARGET_BUNDLE_CONTENT_DIR:tgt> + .. versionadded:: 3.9 + 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 @@ -940,11 +1052,37 @@ which is just the string ``tgt``. :ref:`Target Usage Requirements` this is the consuming target rather than the target specifying the requirement. +.. genex:: $<TARGET_RUNTIME_DLLS:tgt> + + .. versionadded:: 3.21 + + List of DLLs that the target depends on at runtime. This is determined by + the locations of all the ``SHARED`` and ``MODULE`` targets in the target's + transitive dependencies. Using this generator expression on targets other + than executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. + On non-DLL platforms, it evaluates to an empty string. + + This generator expression can be used to copy all of the DLLs that a target + depends on into its output directory in a ``POST_BUILD`` custom command. For + example: + + .. code-block:: cmake + + find_package(foo REQUIRED) + + add_executable(exe main.c) + target_link_libraries(exe PRIVATE foo::foo foo::bar) + add_custom_command(TARGET exe POST_BUILD + COMMAND ${CMAKE_COMMAND} -E copy $<TARGET_RUNTIME_DLLS:exe> $<TARGET_FILE_DIR:exe> + COMMAND_EXPAND_LISTS + ) + .. genex:: $<INSTALL_PREFIX> 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. + :command:`install(EXPORT)`, or when evaluated in the + :prop_tgt:`INSTALL_NAME_DIR` property or the ``INSTALL_NAME_DIR`` argument of + :command:`install(RUNTIME_DEPENDENCY_SET)`, and empty otherwise. Output-Related Expressions -------------------------- @@ -957,6 +1095,8 @@ Output-Related Expressions .. genex:: $<LINK_ONLY:...> + .. versionadded:: 3.1 + Content of ``...`` except when evaluated in a link interface while propagating :ref:`Target Usage Requirements`, in which case it is the empty string. @@ -982,18 +1122,24 @@ Output-Related Expressions .. genex:: $<TARGET_OBJECTS:objLib> + .. versionadded:: 3.1 + List of objects resulting from build of ``objLib``. .. genex:: $<SHELL_PATH:...> + .. versionadded:: 3.4 + 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. - The ``...`` may be a :ref:`semicolon-separated list <CMake Language Lists>` - of paths, in which case each path is converted individually and a result - list is generated using the shell path separator (``:`` on POSIX and - ``;`` on Windows). Be sure to enclose the argument containing this genex - in double quotes in CMake source code so that ``;`` does not split arguments. + + .. versionadded:: 3.14 + The ``...`` may be a :ref:`semicolon-separated list <CMake Language Lists>` + of paths, in which case each path is converted individually and a result + list is generated using the shell path separator (``:`` on POSIX and + ``;`` 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:: $<OUTPUT_CONFIG:...> |