summaryrefslogtreecommitdiff
path: root/Help/manual/cmake-generator-expressions.7.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Help/manual/cmake-generator-expressions.7.rst')
-rw-r--r--Help/manual/cmake-generator-expressions.7.rst160
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:...>