diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 18147b326b..357a20cb3f 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -12,7 +12,14 @@ Introduction Generator expressions are evaluated during build system generation to produce information specific to each build configuration. They have the form -``$<...>``. +``$<...>``. For example: + +.. code-block:: cmake + + target_include_directories(tgt PRIVATE /opt/include/$) + +This would expand to ``/opt/include/GNU``, ``/opt/include/Clang``, etc. +depending on the C++ compiler used. Generator expressions are allowed in the context of many target properties, such as :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INCLUDE_DIRECTORIES`, @@ -24,7 +31,17 @@ compiling, 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 can be nested, as shown in most of the examples below. +Generator expressions can be nested: + +.. code-block:: cmake + + target_compile_definitions(tgt PRIVATE + $<$,4.2.0>:OLD_COMPILER> + ) + +The above would expand to ``OLD_COMPILER`` if the +:variable:`CMAKE_CXX_COMPILER_VERSION _COMPILER_VERSION>` is less +than 4.2.0. Debugging ========= @@ -58,19 +75,38 @@ Generator Expression Reference ``string``, ``target``, etc. This is to prevent an opportunity for those placeholders to be misinterpreted as generator expressions. -.. _`Boolean Generator Expressions`: +.. _`Conditional Generator Expressions`: -Boolean Generator Expressions ------------------------------ +Conditional Expressions +----------------------- -Boolean expressions evaluate to either ``0`` or ``1``. -They are typically used to construct the condition in a :ref:`conditional -generator expression`. +A fundamental category of generator expressions relates to conditional logic. +Two forms of conditional generator expressions are supported: -Available boolean expressions are: +.. genex:: $ -Logical Operators -^^^^^^^^^^^^^^^^^ + Evaluates to ``true_string`` if ``condition`` is ``1``, or an empty string + if ``condition`` evaluates to ``0``. Any other value for ``condition`` + results in an error. + +.. genex:: $ + + .. versionadded:: 3.8 + + Evaluates to ``true_string`` if ``condition`` is ``1``, or ``false_string`` + if ``condition`` is ``0``. Any other value for ``condition`` results in an + error. + +Typically, the ``condition`` is itself a generator expression. For instance, +the following expression expands to ``DEBUG_MODE`` when the ``Debug`` +configuration is used, and the empty string for all other configurations: + +.. code-block:: cmake + + $<$:DEBUG_MODE> + +Boolean-like ``condition`` values other than ``1`` or ``0`` can be handled +by wrapping them with the ``$`` generator expression: .. genex:: $ @@ -84,6 +120,21 @@ Logical Operators Otherwise evaluates to ``1``. +The ``$`` generator expression is often used when a ``condition`` +is provided by a CMake variable: + +.. code-block:: cmake + + $<$:-DENABLE_SOME_FEATURE> + + +.. _`Boolean Generator Expressions`: + +Logical Operators +----------------- + +The common boolean logic operators are supported: + .. genex:: $ where ``conditions`` is a comma-separated list of boolean expressions, @@ -103,6 +154,16 @@ Logical Operators ``condition`` must be ``0`` or ``1``. The result of the expression is ``0`` if ``condition`` is ``1``, else ``1``. +.. _`Comparison Expressions`: + +Primary Comparison Expressions +------------------------------ + +CMake supports a variety of generator expressions that compare things. +This section covers the primary and most widely used comparison types. +Other more specific comparison types are documented in their own separate +sections further below. + String Comparisons ^^^^^^^^^^^^^^^^^^ @@ -111,23 +172,17 @@ String Comparisons ``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 - `, + `. For example, the following + evaluates to ``1`` if ``${foo}`` is any of ``BAR``, ``Bar``, ``bar``, etc. .. code-block:: cmake - $,"BAR"> # "1" if ${foo} is any of "BAR", "Bar", "bar", ... + $,BAR> .. genex:: $ ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``. -.. genex:: $ - - .. versionadded:: 3.12 - - ``1`` if ``string`` is an item in the semicolon-separated ``list``, else ``0``. - It uses case-sensitive comparisons. - Version Comparisons ^^^^^^^^^^^^^^^^^^^ @@ -155,6 +210,67 @@ Version Comparisons ``1`` if ``v1`` is a version greater than or equal to ``v2``, else ``0``. +.. _`String Transforming Generator Expressions`: + +String Transformations +---------------------- + +.. genex:: $ + + Content of ``string`` converted to lower case. + +.. genex:: $ + + Content of ``string`` converted to upper case. + +.. genex:: $ + + Content of ``...`` converted to a C identifier. The conversion follows the + same behavior as :command:`string(MAKE_C_IDENTIFIER)`. + +List Expressions +---------------- + +.. genex:: $ + + .. versionadded:: 3.12 + + ``1`` if ``string`` is an item in the semicolon-separated ``list``, else ``0``. + It uses case-sensitive comparisons. + +.. genex:: $ + + Joins the list with the content of ``string`` inserted between each item. + +.. genex:: $ + + .. versionadded:: 3.15 + + Removes duplicated items in the given ``list``. The relative order of items + is preserved, but if duplicates are encountered, only the first instance is + preserved. + +.. genex:: $ + + .. versionadded:: 3.15 + + Includes or removes items from ``list`` that match the regular expression + ``regex``. + +Path Expressions +---------------- + +Most of the expressions in this section are closely associated with the +:command:`cmake_path` command, providing the same capabilities, but in +the form of a generator expression. + +For all generator expressions in this section, paths are expected to be in +cmake-style format. The :ref:`$\ ` +generator expression can be used to convert a native path to a cmake-style +one. + +.. _GenEx Path Comparisons: + Path Comparisons ^^^^^^^^^^^^^^^^ @@ -173,16 +289,9 @@ Path Comparisons Path Queries ^^^^^^^^^^^^ -The ``$`` generator expression offers the same capabilities as the -:command:`cmake_path` command, for the :ref:`Query ` options. - -For all ``$`` generator expressions, paths are expected in cmake-style -format. The :ref:`$\ ` generator -expression can be used to convert a native path to a cmake-style one. - -The ``$`` generator expression can also be used for path -:ref:`Decomposition ` and -:ref:`Transformations `. +These expressions provide the generation-time capabilities equivalent to the +:ref:`Query ` options of the :command:`cmake_path` command. +All paths are expected to be in cmake-style format. .. genex:: $ @@ -228,553 +337,19 @@ The ``$`` generator expression can also be used for path .. versionadded:: 3.24 - Returns ``1`` if ``path`` is the prefix of ``input``,``0`` otherwise. + Returns ``1`` if ``path`` is the prefix of ``input``, ``0`` otherwise. When the ``NORMALIZE`` option is specified, ``path`` and ``input`` are :ref:`normalized ` before the check. -Variable Queries -^^^^^^^^^^^^^^^^ - -.. genex:: $ - - .. versionadded:: 3.12 - - ``1`` if ``target`` exists, else ``0``. - -.. genex:: $ - - ``1`` if config is any one of the entries in comma-separated list - ``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 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 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 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:: $ - - .. versionadded:: 3.15 - - where ``compiler_ids`` is a comma-separated list. - ``1`` if 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:: $ - - .. versionadded:: 3.16 - - where ``compiler_ids`` is a comma-separated list. - ``1`` if 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:: $ - - .. versionadded:: 3.16 - - where ``compiler_ids`` is a comma-separated list. - ``1`` if 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 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:: $ - - .. versionadded:: 3.21 - - where ``compiler_ids`` is a comma-separated list. - ``1`` if CMake's compiler id of the HIP compiler matches any one - of the entries in ``compiler_ids``, otherwise ``0``. - See also the :variable:`CMAKE__COMPILER_ID` variable. - -.. genex:: $ - - .. versionadded:: 3.19 - - where ``compiler_ids`` is a comma-separated list. - ``1`` if 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:: $ - - .. versionadded:: 3.15 - - ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. - -.. genex:: $ - - .. versionadded:: 3.16 - - ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. - -.. genex:: $ - - .. versionadded:: 3.16 - - ``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:: $ - - .. versionadded:: 3.21 - - ``1`` if the version of the HIP compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. - -.. genex:: $ - - .. versionadded:: 3.19 - - ``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:: $ - - .. versionadded:: 3.1 - - where ``features`` is a comma-separated 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. - -.. genex:: $ - - .. versionadded:: 3.15 - - ``1`` when the language used for compilation unit matches ``language`` and - 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 - for the combination of ``$`` and - ``$``. This expression may be used to specify - compile options, compile definitions, and include directories for source files of a - particular language and compiler combination in a target. For example: - - .. code-block:: cmake - - add_executable(myapp main.cpp foo.c bar.cpp zot.cu) - target_compile_definitions(myapp - PRIVATE $<$:COMPILING_CXX_WITH_CLANG> - $<$:COMPILING_CXX_WITH_INTEL> - $<$:COMPILING_C_WITH_CLANG> - ) - - This specifies the use of different compile definitions based on both - the compiler id and compilation language. This example will have a - ``COMPILING_CXX_WITH_CLANG`` compile definition when Clang is the CXX - compiler, and ``COMPILING_CXX_WITH_INTEL`` when Intel is the CXX compiler. - Likewise when the C compiler is Clang it will only see the ``COMPILING_C_WITH_CLANG`` - definition. - - Without the ``COMPILE_LANG_AND_ID`` generator expression the same logic - would be expressed as: - - .. code-block:: cmake - - target_compile_definitions(myapp - PRIVATE $<$,$>:COMPILING_CXX_WITH_CLANG> - $<$,$>:COMPILING_CXX_WITH_INTEL> - $<$,$>:COMPILING_C_WITH_CLANG> - ) - -.. _`Boolean COMPILE_LANGUAGE Generator Expression`: - -.. genex:: $ - - .. 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 - files of a particular language in a target. For example: - - .. code-block:: cmake - - add_executable(myapp main.cpp foo.c bar.cpp zot.cu) - target_compile_options(myapp - PRIVATE $<$:-fno-exceptions> - ) - target_compile_definitions(myapp - PRIVATE $<$:COMPILING_CXX> - $<$:COMPILING_CUDA> - ) - target_include_directories(myapp - PRIVATE $<$:/opt/foo/headers> - ) - - This specifies the use of the ``-fno-exceptions`` compile option, - ``COMPILING_CXX`` compile definition, and ``cxx_headers`` include - directory for C++ only (compiler id checks elided). It also specifies - a ``COMPILING_CUDA`` compile definition for CUDA. - - Note that with :ref:`Visual Studio Generators` and :generator:`Xcode` there - is no way to represent target-wide compile definitions or include directories - separately for ``C`` and ``CXX`` languages. - Also, with :ref:`Visual Studio Generators` there is no way to represent - target-wide flags separately for ``C`` and ``CXX`` languages. Under these - generators, expressions for both C and C++ sources will be evaluated - using ``CXX`` if there are any C++ sources and otherwise using ``C``. - A workaround is to create separate libraries for each source file language - instead: - - .. code-block:: cmake - - add_library(myapp_c foo.c) - add_library(myapp_cxx bar.cpp) - target_compile_options(myapp_cxx PUBLIC -fno-exceptions) - add_executable(myapp main.cpp) - target_link_libraries(myapp myapp_c myapp_cxx) - -.. genex:: $ - - .. 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 - combination of ``$`` and - ``$``. This expression may be used to specify - link libraries, link options, link directories and link dependencies of a - particular language and linker combination in a target. For example: - - .. code-block:: cmake - - add_library(libC_Clang ...) - add_library(libCXX_Clang ...) - add_library(libC_Intel ...) - add_library(libCXX_Intel ...) - - add_executable(myapp main.c) - if (CXX_CONFIG) - target_sources(myapp PRIVATE file.cxx) - endif() - target_link_libraries(myapp - PRIVATE $<$:libCXX_Clang> - $<$:libC_Clang> - $<$:libCXX_Intel> - $<$:libC_Intel>) - - This specifies the use of different link libraries based on both the - compiler id and link language. This example will have target ``libCXX_Clang`` - as link dependency when ``Clang`` or ``AppleClang`` is the ``CXX`` - linker, and ``libCXX_Intel`` when ``Intel`` is the ``CXX`` linker. - Likewise when the ``C`` linker is ``Clang`` or ``AppleClang``, target - ``libC_Clang`` will be added as link dependency and ``libC_Intel`` when - ``Intel`` is the ``C`` linker. - - See :ref:`the note related to - ` - ``$`` for constraints about the usage of this - generator expression. - -.. _`Boolean LINK_LANGUAGE Generator Expression`: - -.. genex:: $ - - .. 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 - particular language in a target. For example: - - .. code-block:: cmake - - add_library(api_C ...) - add_library(api_CXX ...) - add_library(api INTERFACE) - target_link_options(api INTERFACE $<$:-opt_c> - $<$:-opt_cxx>) - target_link_libraries(api INTERFACE $<$:api_C> - $<$:api_CXX>) - - add_executable(myapp1 main.c) - target_link_options(myapp1 PRIVATE api) - - add_executable(myapp2 main.cpp) - target_link_options(myapp2 PRIVATE api) - - This specifies to use the ``api`` target for linking targets ``myapp1`` and - ``myapp2``. In practice, ``myapp1`` will link with target ``api_C`` and - option ``-opt_c`` because it will use ``C`` as link language. And ``myapp2`` - will link with ``api_CXX`` and option ``-opt_cxx`` because ``CXX`` will be - the link language. - - .. _`Constraints LINK_LANGUAGE Generator Expression`: - - .. note:: - - To determine the link language of a target, it is required to collect, - transitively, all the targets which will be linked to it. So, for link - libraries properties, a double evaluation will be done. During the first - evaluation, ``$`` expressions will always return ``0``. - The link language computed after this first pass will be used to do the - second pass. To avoid inconsistency, it is required that the second pass - do not change the link language. Moreover, to avoid unexpected - side-effects, it is required to specify complete entities as part of the - ``$`` expression. For example: - - .. code-block:: cmake - - add_library(lib STATIC file.cxx) - add_library(libother STATIC file.c) - - # bad usage - add_executable(myapp1 main.c) - target_link_libraries(myapp1 PRIVATE lib$<$:other>) - - # correct usage - add_executable(myapp2 main.c) - target_link_libraries(myapp2 PRIVATE $<$:libother>) - - In this example, for ``myapp1``, the first pass will, unexpectedly, - determine that the link language is ``CXX`` because the evaluation of the - generator expression will be an empty string so ``myapp1`` will depends on - target ``lib`` which is ``C++``. On the contrary, for ``myapp2``, the first - evaluation will give ``C`` as link language, so the second pass will - correctly add target ``libother`` as link dependency. - -String-Valued Generator Expressions ------------------------------------ - -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 compiler identifier. - -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 - - $<$,4.2.0>:OLD_COMPILER> - -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$> - -The following string-valued generator expressions are available: - -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`: - -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:: $ - - .. versionadded:: 3.8 - - 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 Transforming Generator Expressions`: - -String Transformations -^^^^^^^^^^^^^^^^^^^^^^ - -.. genex:: $ - - Joins the list with the content of ``string``. - -.. genex:: $ - - .. versionadded:: 3.15 - - Removes duplicated items in the given ``list``. The relative order of items - is preserved, but if duplicates are encountered, only the first instance is - preserved. - -.. genex:: $ - - .. versionadded:: 3.15 - - 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:: $ - - .. 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:: $ - - .. 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. - - 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 $> - ) - .. _GenEx Path Decomposition: Path Decomposition ^^^^^^^^^^^^^^^^^^ -The ``$`` generator expression offers the same capabilities as the -:command:`cmake_path` command, for the -:ref:`Decomposition ` options. - -For all ``$`` generator expressions, paths are expected in cmake-style -format. The :ref:`$\ ` generator -expression can be used to convert a native path to a cmake-style one. - -The ``$`` generator expression can also be used for path -:ref:`Queries ` and -:ref:`Transformations `. +These expressions provide the generation-time capabilities equivalent to the +:ref:`Decomposition ` options of the :command:`cmake_path` +command. All paths are expected to be in cmake-style format. .. genex:: $ @@ -803,18 +378,10 @@ The ``$`` generator expression can also be used for path Path Transformations ^^^^^^^^^^^^^^^^^^^^ -The ``$`` generator expression offers the same capabilities as the -:command:`cmake_path` command, for the -:ref:`Modification ` and -:ref:`Generation ` options. - -For all ``$`` generator expressions, paths are expected in cmake-style -format. The :ref:`$\ ` generator -expression can be used to convert a native path to a cmake-style one. - -The ``$`` generator expression can also be used for path -:ref:`Queries ` and -:ref:`Decomposition `. +These expressions provide the generation-time capabilities equivalent to the +:ref:`Modification ` and :ref:`Generation ` +options of the :command:`cmake_path` command. All paths are expected to be +in cmake-style format. .. _GenEx PATH-CMAKE_PATH: @@ -906,121 +473,273 @@ The ``$`` generator expression can also be used for path See :ref:`cmake_path(ABSOLUTE_PATH) ` for more details. -Variable Queries -^^^^^^^^^^^^^^^^ +Shell Paths +^^^^^^^^^^^ + +.. genex:: $ + + .. 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. + + .. versionadded:: 3.14 + The ``...`` may be a :ref:`semicolon-separated list ` + 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. + +Configuration Expressions +------------------------- .. genex:: $ - Configuration name. + Configuration name. Use this instead of the deprecated :genex:`CONFIGURATION` + generator expression. -.. genex:: $ +.. genex:: $ - Configuration name. Deprecated since CMake 3.0. Use ``CONFIG`` instead. + ``1`` if config is any one of the entries in comma-separated list + ``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 of an :prop_tgt:`IMPORTED` + target. + +.. genex:: $ + + .. versionadded:: 3.20 + + Only valid in :command:`add_custom_command` and :command:`add_custom_target` + as the outer-most generator expression in an argument. + With the :generator:`Ninja Multi-Config` generator, generator 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` + as the outer-most generator expression in an argument. + With the :generator:`Ninja Multi-Config` generator, generator expressions + in ``...`` are evaluated using the custom command's "command config". + With other generators, the content of ``...`` is evaluated normally. + +Toolchain And Language Expressions +---------------------------------- + +Platform +^^^^^^^^ .. genex:: $ The current system's CMake platform id. See also the :variable:`CMAKE_SYSTEM_NAME` variable. -.. genex:: $ +.. genex:: $ - CMake's compiler id of the C compiler used. - See also the :variable:`CMAKE__COMPILER_ID` variable. + where ``platform_ids`` is a comma-separated list. + ``1`` if CMake's platform id matches any one of the entries in + ``platform_ids``, otherwise ``0``. + See also the :variable:`CMAKE_SYSTEM_NAME` variable. -.. genex:: $ +Compiler Version +^^^^^^^^^^^^^^^^ - CMake's compiler id of the CXX compiler used. - See also the :variable:`CMAKE__COMPILER_ID` variable. - -.. genex:: $ - - .. versionadded:: 3.15 - - CMake's compiler id of the CUDA compiler used. - See also the :variable:`CMAKE__COMPILER_ID` variable. - -.. genex:: $ - - .. versionadded:: 3.16 - - CMake's compiler id of the OBJC compiler used. - See also the :variable:`CMAKE__COMPILER_ID` variable. - -.. genex:: $ - - .. versionadded:: 3.16 - - CMake's compiler id of the OBJCXX compiler used. - See also the :variable:`CMAKE__COMPILER_ID` variable. - -.. genex:: $ - - CMake's compiler id of the Fortran compiler used. - See also the :variable:`CMAKE__COMPILER_ID` variable. - -.. genex:: $ - - .. versionadded:: 3.21 - - CMake's compiler id of the HIP compiler used. - See also the :variable:`CMAKE__COMPILER_ID` variable. - -.. genex:: $ - - .. versionadded:: 3.19 - - CMake's compiler id of the ISPC compiler used. - See also the :variable:`CMAKE__COMPILER_ID` variable. +See also the :variable:`CMAKE__COMPILER_VERSION` variable, which is +closely related to the expressions in this sub-section. .. genex:: $ The version of the C compiler used. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. + +.. genex:: $ + + ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. .. genex:: $ The version of the CXX compiler used. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. + +.. genex:: $ + + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. .. genex:: $ .. versionadded:: 3.15 The version of the CUDA compiler used. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. + +.. genex:: $ + + .. versionadded:: 3.15 + + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. .. genex:: $ .. versionadded:: 3.16 The version of the OBJC compiler used. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. + +.. genex:: $ + + .. versionadded:: 3.16 + + ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``. .. genex:: $ .. versionadded:: 3.16 The version of the OBJCXX compiler used. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. + +.. genex:: $ + + .. versionadded:: 3.16 + + ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``. .. genex:: $ The version of the Fortran compiler used. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. + +.. genex:: $ + + ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. .. genex:: $ .. versionadded:: 3.21 The version of the HIP compiler used. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. + +.. genex:: $ + + .. versionadded:: 3.21 + + ``1`` if the version of the HIP compiler matches ``version``, otherwise ``0``. .. genex:: $ .. versionadded:: 3.19 The version of the ISPC compiler used. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. + +.. genex:: $ + + .. versionadded:: 3.19 + + ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``. + +Compiler Language And ID +^^^^^^^^^^^^^^^^^^^^^^^^ + +See also the :variable:`CMAKE__COMPILER_ID` variable, which is closely +related to most of the expressions in this sub-section. + +.. genex:: $ + + CMake's compiler id of the C compiler used. + +.. genex:: $ + + where ``compiler_ids`` is a comma-separated list. + ``1`` if CMake's compiler id of the C compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + +.. genex:: $ + + CMake's compiler id of the CXX compiler used. + +.. genex:: $ + + where ``compiler_ids`` is a comma-separated list. + ``1`` if CMake's compiler id of the CXX compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + +.. genex:: $ + + .. versionadded:: 3.15 + + CMake's compiler id of the CUDA compiler used. + +.. genex:: $ + + .. versionadded:: 3.15 + + where ``compiler_ids`` is a comma-separated list. + ``1`` if CMake's compiler id of the CUDA compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + +.. genex:: $ + + .. versionadded:: 3.16 + + CMake's compiler id of the OBJC compiler used. + +.. genex:: $ + + .. versionadded:: 3.16 + + where ``compiler_ids`` is a comma-separated list. + ``1`` if CMake's compiler id of the Objective-C compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + +.. genex:: $ + + .. versionadded:: 3.16 + + CMake's compiler id of the OBJCXX compiler used. + +.. genex:: $ + + .. versionadded:: 3.16 + + where ``compiler_ids`` is a comma-separated list. + ``1`` if CMake's compiler id of the Objective-C++ compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + +.. genex:: $ + + CMake's compiler id of the Fortran compiler used. + +.. genex:: $ + + where ``compiler_ids`` is a comma-separated list. + ``1`` if CMake's compiler id of the Fortran compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + +.. genex:: $ + + .. versionadded:: 3.21 + + CMake's compiler id of the HIP compiler used. + +.. genex:: $ + + .. versionadded:: 3.21 + + where ``compiler_ids`` is a comma-separated list. + ``1`` if CMake's compiler id of the HIP compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + +.. genex:: $ + + .. versionadded:: 3.19 + + CMake's compiler id of the ISPC compiler used. + +.. genex:: $ + + .. versionadded:: 3.19 + + where ``compiler_ids`` is a comma-separated list. + ``1`` if CMake's compiler id of the ISPC compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. .. genex:: $ @@ -1032,13 +751,120 @@ Variable Queries ``$`` for notes about the portability of this generator expression. +.. _`Boolean COMPILE_LANGUAGE Generator Expression`: + +.. genex:: $ + + .. 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 particular language in a target. For example: + + .. code-block:: cmake + + add_executable(myapp main.cpp foo.c bar.cpp zot.cu) + target_compile_options(myapp + PRIVATE $<$:-fno-exceptions> + ) + target_compile_definitions(myapp + PRIVATE $<$:COMPILING_CXX> + $<$:COMPILING_CUDA> + ) + target_include_directories(myapp + PRIVATE $<$:/opt/foo/headers> + ) + + This specifies the use of the ``-fno-exceptions`` compile option, + ``COMPILING_CXX`` compile definition, and ``cxx_headers`` include + directory for C++ only (compiler id checks elided). It also specifies + a ``COMPILING_CUDA`` compile definition for CUDA. + + Note that with :ref:`Visual Studio Generators` and :generator:`Xcode` there + is no way to represent target-wide compile definitions or include directories + separately for ``C`` and ``CXX`` languages. + Also, with :ref:`Visual Studio Generators` there is no way to represent + target-wide flags separately for ``C`` and ``CXX`` languages. Under these + generators, expressions for both C and C++ sources will be evaluated + using ``CXX`` if there are any C++ sources and otherwise using ``C``. + A workaround is to create separate libraries for each source file language + instead: + + .. code-block:: cmake + + add_library(myapp_c foo.c) + add_library(myapp_cxx bar.cpp) + target_compile_options(myapp_cxx PUBLIC -fno-exceptions) + add_executable(myapp main.cpp) + target_link_libraries(myapp myapp_c myapp_cxx) + +.. genex:: $ + + .. versionadded:: 3.15 + + ``1`` when the language used for compilation unit matches ``language`` and + 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 + for the combination of ``$`` and + ``$``. This expression may be used to specify + compile options, compile definitions, and include directories for source + files of a particular language and compiler combination in a target. + For example: + + .. code-block:: cmake + + add_executable(myapp main.cpp foo.c bar.cpp zot.cu) + target_compile_definitions(myapp + PRIVATE $<$:COMPILING_CXX_WITH_CLANG> + $<$:COMPILING_CXX_WITH_INTEL> + $<$:COMPILING_C_WITH_CLANG> + ) + + This specifies the use of different compile definitions based on both + the compiler id and compilation language. This example will have a + ``COMPILING_CXX_WITH_CLANG`` compile definition when Clang is the CXX + compiler, and ``COMPILING_CXX_WITH_INTEL`` when Intel is the CXX compiler. + Likewise, when the C compiler is Clang, it will only see the + ``COMPILING_C_WITH_CLANG`` definition. + + Without the ``COMPILE_LANG_AND_ID`` generator expression, the same logic + would be expressed as: + + .. code-block:: cmake + + target_compile_definitions(myapp + PRIVATE $<$,$>:COMPILING_CXX_WITH_CLANG> + $<$,$>:COMPILING_CXX_WITH_INTEL> + $<$,$>:COMPILING_C_WITH_CLANG> + ) + +Compile Features +^^^^^^^^^^^^^^^^ + +.. genex:: $ + + .. versionadded:: 3.1 + + where ``features`` is a comma-separated 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. + +Linker Language And ID +^^^^^^^^^^^^^^^^^^^^^^ + .. genex:: $ .. versionadded:: 3.18 The link language of the target when evaluating link options. See :ref:`the related boolean expression - ` ``$`` + ` ``$`` for notes about the portability of this generator expression. .. note:: @@ -1047,361 +873,118 @@ Variable Queries properties to avoid side-effects due to the double evaluation of these properties. -.. _`Target-Dependent Queries`: -Target-Dependent Queries -^^^^^^^^^^^^^^^^^^^^^^^^ +.. _`Boolean LINK_LANGUAGE Generator Expression`: -These queries refer to a target ``tgt``. 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` + .. versionadded:: 3.18 -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:: $ - - .. 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 - expression is evaluated on. - -.. genex:: $ - - Full path to the ``tgt`` binary file. - - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on, unless the expression is being used in - :command:`add_custom_command` or :command:`add_custom_target`. - -.. genex:: $ - - .. versionadded:: 3.15 - - Base name of ``tgt``, i.e. ``$`` without prefix and - suffix. - For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``. - - See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, - :prop_tgt:`LIBRARY_OUTPUT_NAME` and :prop_tgt:`RUNTIME_OUTPUT_NAME` - target properties and their configuration specific variants - :prop_tgt:`OUTPUT_NAME_`, :prop_tgt:`ARCHIVE_OUTPUT_NAME_`, - :prop_tgt:`LIBRARY_OUTPUT_NAME_` and - :prop_tgt:`RUNTIME_OUTPUT_NAME_`. - - The :prop_tgt:`_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target - properties can also be considered. - - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on. - -.. genex:: $ - - .. versionadded:: 3.15 - - 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:: $ - - .. versionadded:: 3.15 - - 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:: $ - - .. versionadded:: 3.15 - - 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``. - - See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, - and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration - specific variants :prop_tgt:`OUTPUT_NAME_`, - :prop_tgt:`ARCHIVE_OUTPUT_NAME_` and - :prop_tgt:`LIBRARY_OUTPUT_NAME_`. - - The :prop_tgt:`_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target - properties can also be considered. - - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on. - -.. genex:: $ - - .. versionadded:: 3.15 - - Prefix of file used to link target ``tgt``. - - See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target - properties. - - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on. - -.. genex:: $ - - .. 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"). - - See also the :prop_tgt:`SUFFIX` and :prop_tgt:`IMPORT_SUFFIX` target - properties. - - 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:: $ - - .. versionadded:: 3.1 - - 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:: $ - - .. versionadded:: 3.15 - - Base name of the linker generated program database file (.pdb) - where ``tgt`` is the name of a target. - - The base name corresponds to the target PDB file name (see - ``$``) without prefix and suffix. For example, - if target file name is ``base.pdb``, the base name is ``base``. - - See also the :prop_tgt:`PDB_NAME` target property and its configuration - specific variant :prop_tgt:`PDB_NAME_`. - - The :prop_tgt:`_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target - properties can also be considered. - - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on. - -.. genex:: $ - - .. 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 - expression is evaluated on (see policy :policy:`CMP0112`). - -.. genex:: $ - - .. 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 - expression is evaluated on (see policy :policy:`CMP0112`). - -.. genex:: $ - - .. versionadded:: 3.9 - - Full path to the bundle directory (``/path/to/my.app``, - ``/path/to/my.framework``, or ``/path/to/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:: $ - - .. versionadded:: 3.24 - - Name of 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:: $ - - .. 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 ``/path/to/my.app/Contents``, - ``/path/to/my.framework``, or ``/path/to/my.bundle/Contents``. - For all other SDKs (e.g. iOS) it leads to ``/path/to/my.app``, - ``/path/to/my.framework``, or ``/path/to/my.bundle`` due to the flat - bundle structure. - - 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:: $ - - .. versionadded:: 3.21 - - List of DLLs that the target depends on at runtime. This is determined by - the locations of all the ``SHARED`` 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, this expression always 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: + ``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 + particular language in a target. For example: .. code-block:: cmake - find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT) + add_library(api_C ...) + add_library(api_CXX ...) + add_library(api INTERFACE) + target_link_options(api INTERFACE $<$:-opt_c> + $<$:-opt_cxx>) + target_link_libraries(api INTERFACE $<$:api_C> + $<$:api_CXX>) - 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 $ $ - COMMAND_EXPAND_LISTS - ) + add_executable(myapp1 main.c) + target_link_options(myapp1 PRIVATE api) + + add_executable(myapp2 main.cpp) + target_link_options(myapp2 PRIVATE api) + + This specifies to use the ``api`` target for linking targets ``myapp1`` and + ``myapp2``. In practice, ``myapp1`` will link with target ``api_C`` and + option ``-opt_c`` because it will use ``C`` as link language. And ``myapp2`` + will link with ``api_CXX`` and option ``-opt_cxx`` because ``CXX`` will be + the link language. + + .. _`Constraints LINK_LANGUAGE Generator Expression`: .. note:: - :ref:`Imported Targets` are supported only if they know the location - of their ``.dll`` files. An imported ``SHARED`` library must have - :prop_tgt:`IMPORTED_LOCATION` set to its ``.dll`` file. See the - :ref:`add_library imported libraries ` - section for details. Many :ref:`Find Modules` produce imported targets - with the ``UNKNOWN`` type and therefore will be ignored. + To determine the link language of a target, it is required to collect, + transitively, all the targets which will be linked to it. So, for link + libraries properties, a double evaluation will be done. During the first + evaluation, ``$`` expressions will always return ``0``. + The link language computed after this first pass will be used to do the + second pass. To avoid inconsistency, it is required that the second pass + do not change the link language. Moreover, to avoid unexpected + side-effects, it is required to specify complete entities as part of the + ``$`` expression. For example: -.. genex:: $ + .. code-block:: cmake - Content of the install prefix when the target is exported via - :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. + add_library(lib STATIC file.cxx) + add_library(libother STATIC file.c) -Output-Related Expressions -^^^^^^^^^^^^^^^^^^^^^^^^^^ + # bad usage + add_executable(myapp1 main.c) + target_link_libraries(myapp1 PRIVATE lib$<$:other>) -.. genex:: $ + # correct usage + add_executable(myapp2 main.c) + target_link_libraries(myapp2 PRIVATE $<$:libother>) - 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. + In this example, for ``myapp1``, the first pass will, unexpectedly, + determine that the link language is ``CXX`` because the evaluation of the + generator expression will be an empty string so ``myapp1`` will depends on + target ``lib`` which is ``C++``. On the contrary, for ``myapp2``, the first + evaluation will give ``C`` as link language, so the second pass will + correctly add target ``libother`` as link dependency. -.. genex:: $ - - .. versionadded:: 3.1 - - Content of ``...``, except while collecting :ref:`Target Usage Requirements`, - in which case it is the empty string. This is intended for use in an - :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property, typically populated - via the :command:`target_link_libraries` command, to specify private link - dependencies without other usage requirements. - - .. versionadded:: 3.24 - ``LINK_ONLY`` may also be used in a :prop_tgt:`LINK_LIBRARIES` target - property. See policy :policy:`CMP0131`. - -.. genex:: $ +.. genex:: $ .. 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 - policy :policy:`CMP0105`. This expression can only be used to specify link - options. + ``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 + combination of ``$`` and + ``$``. This expression may be used to specify + link libraries, link options, link directories and link dependencies of a + particular language and linker combination in a target. For example: -.. genex:: $ + .. code-block:: cmake - .. versionadded:: 3.18 + add_library(libC_Clang ...) + add_library(libCXX_Clang ...) + add_library(libC_Intel ...) + add_library(libCXX_Intel ...) - 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 :genex:`$` generator expression). This expression can - only be used to specify link options. + add_executable(myapp main.c) + if (CXX_CONFIG) + target_sources(myapp PRIVATE file.cxx) + endif() + target_link_libraries(myapp + PRIVATE $<$:libCXX_Clang> + $<$:libC_Clang> + $<$:libCXX_Intel> + $<$:libC_Intel>) + + This specifies the use of different link libraries based on both the + compiler id and link language. This example will have target ``libCXX_Clang`` + as link dependency when ``Clang`` or ``AppleClang`` is the ``CXX`` + linker, and ``libCXX_Intel`` when ``Intel`` is the ``CXX`` linker. + Likewise when the ``C`` linker is ``Clang`` or ``AppleClang``, target + ``libC_Clang`` will be added as link dependency and ``libC_Intel`` when + ``Intel`` is the ``C`` linker. + + See :ref:`the note related to + ` + ``$`` for constraints about the usage of this + generator expression. + +Link Features +^^^^^^^^^^^^^ .. genex:: $ @@ -1641,6 +1224,380 @@ Output-Related Expressions command. It is the responsibility of the environment consuming this import to define the link feature used by this expression. +Link Context +^^^^^^^^^^^^ + +.. genex:: $ + + .. versionadded:: 3.1 + + Content of ``...``, except while collecting :ref:`Target Usage Requirements`, + in which case it is the empty string. This is intended for use in an + :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property, typically populated + via the :command:`target_link_libraries` command, to specify private link + dependencies without other usage requirements. + + .. versionadded:: 3.24 + ``LINK_ONLY`` may also be used in a :prop_tgt:`LINK_LIBRARIES` target + property. See policy :policy:`CMP0131`. + +.. genex:: $ + + .. 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 + policy :policy:`CMP0105`. This expression can only be used to specify link + options. + +.. genex:: $ + + .. 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 :genex:`$` generator expression). This expression can + only be used to specify link options. + + +.. _`Target-Dependent Queries`: + +Target-Dependent Expressions +---------------------------- + +These queries refer to a target ``tgt``. Unless otherwise stated, this can +be any runtime artifact, namely: + +* 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``. + +.. genex:: $ + + .. versionadded:: 3.12 + + ``1`` if ``tgt`` exists as a CMake target, else ``0``. + +.. genex:: $ + + .. 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 + expression is evaluated on. + +.. 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:: $ + + 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:: $ + + .. versionadded:: 3.1 + + List of objects resulting from building ``tgt``. This would typically be + used on :ref:`object library ` targets. + +.. 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:: $ + + Full path to the ``tgt`` binary file. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on, unless the expression is being used in + :command:`add_custom_command` or :command:`add_custom_target`. + +.. genex:: $ + + .. versionadded:: 3.15 + + Base name of ``tgt``, i.e. ``$`` without prefix and + suffix. + For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``. + + See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + :prop_tgt:`LIBRARY_OUTPUT_NAME` and :prop_tgt:`RUNTIME_OUTPUT_NAME` + target properties and their configuration specific variants + :prop_tgt:`OUTPUT_NAME_`, :prop_tgt:`ARCHIVE_OUTPUT_NAME_`, + :prop_tgt:`LIBRARY_OUTPUT_NAME_` and + :prop_tgt:`RUNTIME_OUTPUT_NAME_`. + + The :prop_tgt:`_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $ + + .. versionadded:: 3.15 + + 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:: $ + + .. versionadded:: 3.15 + + 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:: $ + + .. versionadded:: 3.15 + + 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``. + + See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration + specific variants :prop_tgt:`OUTPUT_NAME_`, + :prop_tgt:`ARCHIVE_OUTPUT_NAME_` and + :prop_tgt:`LIBRARY_OUTPUT_NAME_`. + + The :prop_tgt:`_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $ + + .. versionadded:: 3.15 + + Prefix of file used to link target ``tgt``. + + See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target + properties. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $ + + .. 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"). + + See also the :prop_tgt:`SUFFIX` and :prop_tgt:`IMPORT_SUFFIX` target + properties. + + 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:: $ + + .. versionadded:: 3.1 + + 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:: $ + + .. versionadded:: 3.15 + + Base name of the linker generated program database file (.pdb) + where ``tgt`` is the name of a target. + + The base name corresponds to the target PDB file name (see + ``$``) without prefix and suffix. For example, + if target file name is ``base.pdb``, the base name is ``base``. + + See also the :prop_tgt:`PDB_NAME` target property and its configuration + specific variant :prop_tgt:`PDB_NAME_`. + + The :prop_tgt:`_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $ + + .. 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 + expression is evaluated on (see policy :policy:`CMP0112`). + +.. genex:: $ + + .. 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 + expression is evaluated on (see policy :policy:`CMP0112`). + +.. genex:: $ + + .. versionadded:: 3.9 + + Full path to the bundle directory (``/path/to/my.app``, + ``/path/to/my.framework``, or ``/path/to/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:: $ + + .. versionadded:: 3.24 + + Name of 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:: $ + + .. 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 ``/path/to/my.app/Contents``, + ``/path/to/my.framework``, or ``/path/to/my.bundle/Contents``. + For all other SDKs (e.g. iOS) it leads to ``/path/to/my.app``, + ``/path/to/my.framework``, or ``/path/to/my.bundle`` due to the flat + bundle structure. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). + +.. genex:: $ + + .. versionadded:: 3.21 + + List of DLLs that the target depends on at runtime. This is determined by + the locations of all the ``SHARED`` 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, this expression always 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 CONFIG REQUIRED) # package generated by install(EXPORT) + + 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 $ $ + COMMAND_EXPAND_LISTS + ) + + .. note:: + + :ref:`Imported Targets` are supported only if they know the location + of their ``.dll`` files. An imported ``SHARED`` library must have + :prop_tgt:`IMPORTED_LOCATION` set to its ``.dll`` file. See the + :ref:`add_library imported libraries ` + section for details. Many :ref:`Find Modules` produce imported targets + with the ``UNKNOWN`` type and therefore will be ignored. + + +Export And Install Expressions +------------------------------ + .. genex:: $ Content of ``...`` when the property is exported using @@ -1652,48 +1609,85 @@ Output-Related Expressions when the target is used by another target in the same buildsystem. Expands to the empty string otherwise. -.. genex:: $ +.. genex:: $ - Content of ``...`` converted to a C identifier. The conversion follows the - same behavior as :command:`string(MAKE_C_IDENTIFIER)`. + Content of the install prefix when the target is exported via + :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. -.. genex:: $ +Multi-level Expression Evaluation +--------------------------------- - .. versionadded:: 3.1 +.. genex:: $ - List of objects resulting from build of ``objLib``. + .. versionadded:: 3.12 -.. 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. - .. versionadded:: 3.4 +.. 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. + .. versionadded:: 3.12 - .. versionadded:: 3.14 - The ``...`` may be a :ref:`semicolon-separated list ` - 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. + 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. -.. genex:: $ + Having the capability to evaluate generator expressions is very useful when + you want to manage custom properties supporting generator expressions. + For example: - .. versionadded:: 3.20 + .. code-block:: cmake - Only valid in :command:`add_custom_command` and :command:`add_custom_target` - as the outer-most generator expression in an argument. - With the :generator:`Ninja Multi-Config` generator, generator expressions - in ``...`` are evaluated using the custom command's "output config". - With other generators, the content of ``...`` is evaluated normally. + add_library(foo ...) -.. genex:: $ + set_property(TARGET foo PROPERTY + CUSTOM_KEYS $<$:FOO_EXTRA_THINGS> + ) - .. versionadded:: 3.20 + add_custom_target(printFooKeys + COMMAND ${CMAKE_COMMAND} -E echo $ + ) - Only valid in :command:`add_custom_command` and :command:`add_custom_target` - as the outer-most generator expression in an argument. - With the :generator:`Ninja Multi-Config` generator, generator expressions - in ``...`` are evaluated using the custom command's "command config". - With other generators, the content of ``...`` is evaluated normally. + 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 $> + ) + +Escaped Characters +------------------ + +These expressions evaluate to specific string literals. Use them in place of +the actual string literal where you need to prevent them from having their +special meaning. + +.. 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 ``;``. + +Deprecated Expressions +---------------------- + +.. genex:: $ + + Configuration name. Deprecated since CMake 3.0. Use :genex:`CONFIG` instead.