From 044c22e12129c035b2c8750c61de3e02afa9e5e4 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Tue, 19 Jul 2022 17:04:02 +1000 Subject: Help: Restructure reference sections of genex manual As part of the general restructuring, also move the notes of a more introductory nature out of what was the "String-Valued Generator Expressions" section and up to the dedicated Introduction. This gives the reader a bit more of a foundation before they get to the heavier detail of the reference section. --- Help/manual/cmake-generator-expressions.7.rst | 2116 ++++++++++++------------- 1 file changed, 1055 insertions(+), 1061 deletions(-) diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 18147b3..357a20c 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 +----------------------- + +A fundamental category of generator expressions relates to conditional logic. +Two forms of conditional generator expressions are supported: -Boolean expressions evaluate to either ``0`` or ``1``. -They are typically used to construct the condition in a :ref:`conditional -generator expression`. +.. genex:: $ -Available boolean expressions are: + 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. -Logical Operators -^^^^^^^^^^^^^^^^^ +.. 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,1083 +337,967 @@ 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 Path Decomposition: -.. genex:: $ +Path Decomposition +^^^^^^^^^^^^^^^^^^ - .. versionadded:: 3.12 +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. - ``1`` if ``target`` exists, else ``0``. +.. genex:: $ -.. genex:: $ + .. versionadded:: 3.24 - ``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. + The following operations retrieve a different component or group of + components from a path. See :ref:`Path Structure And Terminology` for the + meaning of each path component. -.. 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:: $ + If a requested component is not present in the path, an empty string is + returned. - 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 Path Transformations: -.. genex:: $ +Path Transformations +^^^^^^^^^^^^^^^^^^^^ - 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. +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:: $ +.. _GenEx PATH-CMAKE_PATH: - .. versionadded:: 3.15 +.. genex:: $ - 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. + .. versionadded:: 3.24 -.. genex:: $ + Returns ``path``. If ``path`` is a native path, it is converted into a + cmake-style path with forward-slashes (``/``). On Windows, the long filename + marker is taken into account. - .. versionadded:: 3.16 + When the ``NORMALIZE`` option is specified, the path is :ref:`normalized + ` after the conversion. - 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:: $ -.. genex:: $ + .. versionadded:: 3.24 - .. versionadded:: 3.16 + Returns all the ``input`` arguments appended to ``path`` using ``/`` as the + ``directory-separator``. Depending on the ``input``, the value of ``path`` + may be discarded. - 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. + See :ref:`cmake_path(APPEND) ` for more details. -.. genex:: $ +.. 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. + .. versionadded:: 3.24 -.. genex:: $ + Returns ``path`` with filename component (as returned by + ``$``) removed. After removal, any trailing + ``directory-separator`` is left alone, if present. - .. versionadded:: 3.21 + See :ref:`cmake_path(REMOVE_FILENAME) ` for more details. - 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:: $ -.. genex:: $ + .. versionadded:: 3.24 - .. versionadded:: 3.19 + Returns ``path`` with the filename component replaced by ``input``. If + ``path`` has no filename component (i.e. ``$`` returns + ``0``), ``path`` is unchanged. - 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. + See :ref:`cmake_path(REPLACE_FILENAME) ` for more details. -.. genex:: $ +.. genex:: $ - ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. + .. versionadded:: 3.24 -.. genex:: $ + Returns ``path`` with the :ref:`extension ` removed, if any. - ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. + See :ref:`cmake_path(REMOVE_EXTENSION) ` for more details. -.. genex:: $ +.. genex:: $ - .. versionadded:: 3.15 + .. versionadded:: 3.24 - ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. + Returns ``path`` with the :ref:`extension ` replaced by + ``input``, if any. -.. genex:: $ + See :ref:`cmake_path(REPLACE_EXTENSION) ` for more details. - .. versionadded:: 3.16 +.. genex:: $ - ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. + .. versionadded:: 3.24 -.. genex:: $ + Returns ``path`` normalized according to the steps described in + :ref:`Normalization`. - .. versionadded:: 3.16 +.. genex:: $ - ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. + .. versionadded:: 3.24 -.. genex:: $ + Returns ``path``, modified to make it relative to the ``base_directory`` + argument. - ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. + See :ref:`cmake_path(RELATIVE_PATH) ` for more + details. -.. genex:: $ +.. genex:: $ - .. versionadded:: 3.21 + .. versionadded:: 3.24 - ``1`` if the version of the HIP compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. + Returns ``path`` as absolute. If ``path`` is a relative path + (``$`` returns ``1``), it is evaluated relative to the + given base directory specified by ``base_directory`` argument. -.. genex:: $ + When the ``NORMALIZE`` option is specified, the path is + :ref:`normalized ` after the path computation. - .. versionadded:: 3.19 + See :ref:`cmake_path(ABSOLUTE_PATH) ` for more details. - ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. +Shell Paths +^^^^^^^^^^^ -.. genex:: $ +.. 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. + .. 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.1 + .. 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. - 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. +Configuration Expressions +------------------------- -.. genex:: $ +.. genex:: $ - .. versionadded:: 3.15 + Configuration name. Use this instead of the deprecated :genex:`CONFIGURATION` + generator expression. - ``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: +.. genex:: $ - .. code-block:: cmake + ``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. - 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> - ) +.. genex:: $ - 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. + .. versionadded:: 3.20 - Without the ``COMPILE_LANG_AND_ID`` generator expression the same logic - would be expressed as: + 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. - .. code-block:: cmake +.. genex:: $ - target_compile_definitions(myapp - PRIVATE $<$,$>:COMPILING_CXX_WITH_CLANG> - $<$,$>:COMPILING_CXX_WITH_INTEL> - $<$,$>:COMPILING_C_WITH_CLANG> - ) + .. versionadded:: 3.20 -.. _`Boolean COMPILE_LANGUAGE Generator Expression`: + 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. -.. genex:: $ +Toolchain And Language Expressions +---------------------------------- - .. versionadded:: 3.3 +Platform +^^^^^^^^ - ``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: +.. genex:: $ - .. code-block:: cmake + The current system's CMake platform id. + See also the :variable:`CMAKE_SYSTEM_NAME` variable. - 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> - ) +.. genex:: $ - 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. + 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. - 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: +Compiler Version +^^^^^^^^^^^^^^^^ - .. code-block:: cmake +See also the :variable:`CMAKE__COMPILER_VERSION` variable, which is +closely related to the expressions in this sub-section. - 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:: $ -.. genex:: $ + The version of the C compiler used. - .. versionadded:: 3.18 +.. genex:: $ - ``1`` when the language used for link step matches ``language`` and the - CMake's compiler id of the language linker matches any one of the entries - in ``compiler_ids``, otherwise ``0``. This expression is a short form for the - 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: + ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. - .. code-block:: cmake +.. genex:: $ - add_library(libC_Clang ...) - add_library(libCXX_Clang ...) - add_library(libC_Intel ...) - add_library(libCXX_Intel ...) + The version of the CXX compiler used. - 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>) +.. genex:: $ - 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. + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. - See :ref:`the note related to - ` - ``$`` for constraints about the usage of this - generator expression. +.. genex:: $ -.. _`Boolean LINK_LANGUAGE Generator Expression`: + .. versionadded:: 3.15 -.. genex:: $ + The version of the CUDA compiler used. - .. versionadded:: 3.18 +.. genex:: $ - ``1`` when the language used for link step matches any of the entries - in ``languages``, otherwise ``0``. This expression may be used to specify - link libraries, link options, link directories and link dependencies of a - particular language in a target. For example: + .. versionadded:: 3.15 - .. code-block:: cmake + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. - 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>) +.. genex:: $ - add_executable(myapp1 main.c) - target_link_options(myapp1 PRIVATE api) + .. versionadded:: 3.16 - add_executable(myapp2 main.cpp) - target_link_options(myapp2 PRIVATE api) + The version of the OBJC compiler used. - 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. +.. genex:: $ - .. _`Constraints LINK_LANGUAGE Generator Expression`: + .. versionadded:: 3.16 - .. note:: + ``1`` if the version of the OBJC compiler matches ``version``, otherwise ``0``. - 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 + .. versionadded:: 3.16 - add_library(lib STATIC file.cxx) - add_library(libother STATIC file.c) + The version of the OBJCXX compiler used. - # 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>) + .. versionadded:: 3.16 - 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. + ``1`` if the version of the OBJCXX compiler matches ``version``, otherwise ``0``. -String-Valued Generator Expressions ------------------------------------ +.. genex:: $ -These expressions expand to some string. -For example, + The version of the Fortran compiler used. -.. code-block:: cmake +.. genex:: $ - include_directories(/usr/include/$/) + ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. -expands to ``/usr/include/GNU/`` or ``/usr/include/Clang/`` etc, depending on -the compiler identifier. +.. genex:: $ -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: + .. versionadded:: 3.21 -.. code-block:: cmake + The version of the HIP compiler used. - $<$,4.2.0>:OLD_COMPILER> +.. genex:: $ -expands to ``OLD_COMPILER`` if the -:variable:`CMAKE_CXX_COMPILER_VERSION _COMPILER_VERSION>` is less -than 4.2.0. + .. versionadded:: 3.21 -And here two nested string-valued expressions: + ``1`` if the version of the HIP compiler matches ``version``, otherwise ``0``. -.. code-block:: cmake +.. genex:: $ - -I$, -I> + .. versionadded:: 3.19 -generates a string of the entries in the :prop_tgt:`INCLUDE_DIRECTORIES` target -property with each entry preceded by ``-I``. + The version of the ISPC compiler used. -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: +.. genex:: $ -.. code-block:: cmake + .. versionadded:: 3.19 - set(prop "$") # helper variable - $<$:-I$> + ``1`` if the version of the ISPC compiler matches ``version``, otherwise ``0``. -The following string-valued generator expressions are available: +Compiler Language And ID +^^^^^^^^^^^^^^^^^^^^^^^^ -Escaped Characters -^^^^^^^^^^^^^^^^^^ +See also the :variable:`CMAKE__COMPILER_ID` variable, which is closely +related to most of the expressions in this sub-section. -String literals to escape the special meaning a character would otherwise have: +.. genex:: $ -.. genex:: $ + CMake's compiler id of the C compiler used. - A literal ``>``. Used for example to compare strings that contain a ``>``. +.. genex:: $ -.. 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``. - A literal ``,``. Used for example to compare strings which contain a ``,``. +.. genex:: $ -.. genex:: $ + CMake's compiler id of the CXX compiler used. - A literal ``;``. Used to prevent list expansion on an argument with ``;``. +.. genex:: $ -.. _`Conditional Generator Expressions`: + 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``. -Conditional Expressions -^^^^^^^^^^^^^^^^^^^^^^^ +.. genex:: $ -Conditional generator expressions depend on a boolean condition -that must be ``0`` or ``1``. + .. versionadded:: 3.15 -.. genex:: $ + CMake's compiler id of the CUDA compiler used. - Evaluates to ``true_string`` if ``condition`` is ``1``. - Otherwise evaluates to the empty string. +.. genex:: $ -.. genex:: $ + .. versionadded:: 3.15 - .. versionadded:: 3.8 + 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``. - Evaluates to ``true_string`` if ``condition`` is ``1``. - Otherwise evaluates to ``false_string``. +.. genex:: $ -Typically, the ``condition`` is a :ref:`boolean generator expression -`. For instance, + .. versionadded:: 3.16 -.. code-block:: cmake + CMake's compiler id of the OBJC compiler used. - $<$:DEBUG_MODE> +.. genex:: $ -expands to ``DEBUG_MODE`` when the ``Debug`` configuration is used, and -otherwise expands to the empty string. + .. versionadded:: 3.16 -.. _`String Transforming Generator Expressions`: + 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``. -String Transformations -^^^^^^^^^^^^^^^^^^^^^^ +.. genex:: $ -.. genex:: $ + .. versionadded:: 3.16 - Joins the list with the content of ``string``. + CMake's compiler id of the OBJCXX compiler used. -.. genex:: $ +.. genex:: $ - .. versionadded:: 3.15 + .. versionadded:: 3.16 - 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. + 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:: $ +.. genex:: $ - .. versionadded:: 3.15 + CMake's compiler id of the Fortran compiler used. - Includes or removes items from ``list`` that match the regular expression ``regex``. +.. genex:: $ -.. 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``. - Content of ``string`` converted to lower case. +.. genex:: $ -.. genex:: $ + .. versionadded:: 3.21 - Content of ``string`` converted to upper case. + CMake's compiler id of the HIP compiler used. -.. genex:: $ +.. genex:: $ - .. versionadded:: 3.12 + .. versionadded:: 3.21 - 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. + 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:: $ +.. genex:: $ - .. versionadded:: 3.12 + .. versionadded:: 3.19 - 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. + CMake's compiler id of the ISPC compiler used. - Having the capability to evaluate generator expressions is very useful when - you want to manage custom properties supporting generator expressions. - For example: +.. genex:: $ - .. code-block:: cmake + .. versionadded:: 3.19 - add_library(foo ...) + 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``. - set_property(TARGET foo PROPERTY - CUSTOM_KEYS $<$:FOO_EXTRA_THINGS> - ) +.. genex:: $ - add_custom_target(printFooKeys - COMMAND ${CMAKE_COMMAND} -E echo $ - ) + .. versionadded:: 3.3 - 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>``). + The compile language of source files when evaluating compile options. + See :ref:`the related boolean expression + ` + ``$`` + for notes about the portability of this generator expression. - To have the expected result (i.e. ``FOO_EXTRA_THINGS`` if config is - ``Debug``), it is required to evaluate the output of - ``$``: +.. _`Boolean COMPILE_LANGUAGE Generator Expression`: - .. code-block:: cmake +.. genex:: $ - add_custom_target(printFooKeys - COMMAND ${CMAKE_COMMAND} -E - echo $> - ) + .. versionadded:: 3.3 -.. _GenEx Path Decomposition: + ``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: -Path Decomposition -^^^^^^^^^^^^^^^^^^ + .. code-block:: cmake -The ``$`` generator expression offers the same capabilities as the -:command:`cmake_path` command, for the -:ref:`Decomposition ` options. + 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> + ) -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. + 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. -The ``$`` generator expression can also be used for path -:ref:`Queries ` and -:ref:`Transformations `. + 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: -.. genex:: $ + .. code-block:: cmake - .. versionadded:: 3.24 + 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) - The following operations retrieve a different component or group of - components from a path. See :ref:`Path Structure And Terminology` for the - meaning of each path component. +.. 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: - If a requested component is not present in the path, an empty string is - returned. + .. code-block:: cmake -.. _GenEx Path Transformations: + 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> + ) -Path Transformations -^^^^^^^^^^^^^^^^^^^^ + 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. -The ``$`` generator expression offers the same capabilities as the -:command:`cmake_path` command, for the -:ref:`Modification ` and -:ref:`Generation ` options. + Without the ``COMPILE_LANG_AND_ID`` generator expression, the same logic + would be expressed as: -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. + .. code-block:: cmake -The ``$`` generator expression can also be used for path -:ref:`Queries ` and -:ref:`Decomposition `. + target_compile_definitions(myapp + PRIVATE $<$,$>:COMPILING_CXX_WITH_CLANG> + $<$,$>:COMPILING_CXX_WITH_INTEL> + $<$,$>:COMPILING_C_WITH_CLANG> + ) -.. _GenEx PATH-CMAKE_PATH: +Compile Features +^^^^^^^^^^^^^^^^ -.. genex:: $ +.. genex:: $ - .. versionadded:: 3.24 + .. versionadded:: 3.1 - Returns ``path``. If ``path`` is a native path, it is converted into a - cmake-style path with forward-slashes (``/``). On Windows, the long filename - marker is taken into account. + 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. - When the ``NORMALIZE`` option is specified, the path is :ref:`normalized - ` after the conversion. +Linker Language And ID +^^^^^^^^^^^^^^^^^^^^^^ -.. genex:: $ +.. genex:: $ - .. versionadded:: 3.24 + .. versionadded:: 3.18 - Returns all the ``input`` arguments appended to ``path`` using ``/`` as the - ``directory-separator``. Depending on the ``input``, the value of ``path`` - may be discarded. + 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. - See :ref:`cmake_path(APPEND) ` for more details. + .. note:: -.. genex:: $ + This generator expression is not supported by the link libraries + properties to avoid side-effects due to the double evaluation of + these properties. - .. versionadded:: 3.24 - Returns ``path`` with filename component (as returned by - ``$``) removed. After removal, any trailing - ``directory-separator`` is left alone, if present. +.. _`Boolean LINK_LANGUAGE Generator Expression`: - See :ref:`cmake_path(REMOVE_FILENAME) ` for more details. +.. genex:: $ -.. genex:: $ + .. versionadded:: 3.18 - .. versionadded:: 3.24 + ``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: - Returns ``path`` with the filename component replaced by ``input``. If - ``path`` has no filename component (i.e. ``$`` returns - ``0``), ``path`` is unchanged. + .. code-block:: cmake - See :ref:`cmake_path(REPLACE_FILENAME) ` for more details. + 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>) -.. genex:: $ + add_executable(myapp1 main.c) + target_link_options(myapp1 PRIVATE api) - .. versionadded:: 3.24 + add_executable(myapp2 main.cpp) + target_link_options(myapp2 PRIVATE api) - Returns ``path`` with the :ref:`extension ` removed, if any. - - See :ref:`cmake_path(REMOVE_EXTENSION) ` for more details. - -.. genex:: $ - - .. versionadded:: 3.24 - - Returns ``path`` with the :ref:`extension ` replaced by - ``input``, if any. - - See :ref:`cmake_path(REPLACE_EXTENSION) ` for more details. - -.. genex:: $ - - .. versionadded:: 3.24 - - Returns ``path`` normalized according to the steps described in - :ref:`Normalization`. - -.. genex:: $ - - .. versionadded:: 3.24 - - Returns ``path``, modified to make it relative to the ``base_directory`` - argument. - - See :ref:`cmake_path(RELATIVE_PATH) ` for more - details. - -.. genex:: $ - - .. versionadded:: 3.24 - - Returns ``path`` as absolute. If ``path`` is a relative path - (``$`` returns ``1``), it is evaluated relative to the - given base directory specified by ``base_directory`` argument. - - When the ``NORMALIZE`` option is specified, the path is - :ref:`normalized ` after the path computation. - - See :ref:`cmake_path(ABSOLUTE_PATH) ` for more details. - -Variable Queries -^^^^^^^^^^^^^^^^ - -.. genex:: $ - - Configuration name. - -.. genex:: $ - - Configuration name. Deprecated since CMake 3.0. Use ``CONFIG`` instead. - -.. genex:: $ - - The current system's CMake platform id. - See also the :variable:`CMAKE_SYSTEM_NAME` variable. - -.. genex:: $ - - CMake's compiler id of the C compiler used. - See also the :variable:`CMAKE__COMPILER_ID` variable. - -.. genex:: $ - - 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. - -.. genex:: $ - - The version of the C compiler used. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. - -.. genex:: $ - - The version of the CXX compiler used. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. - -.. genex:: $ - - .. versionadded:: 3.15 - - The version of the CUDA compiler used. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. - -.. genex:: $ - - .. versionadded:: 3.16 - - The version of the OBJC compiler used. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. - -.. genex:: $ - - .. versionadded:: 3.16 - - The version of the OBJCXX compiler used. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. - -.. genex:: $ - - The version of the Fortran compiler used. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. - -.. genex:: $ + 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. - .. versionadded:: 3.21 + .. _`Constraints LINK_LANGUAGE Generator Expression`: - The version of the HIP compiler used. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. + .. note:: -.. genex:: $ + 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: - .. versionadded:: 3.19 + .. code-block:: cmake - The version of the ISPC compiler used. - See also the :variable:`CMAKE__COMPILER_VERSION` variable. + add_library(lib STATIC file.cxx) + add_library(libother STATIC file.c) -.. genex:: $ + # bad usage + add_executable(myapp1 main.c) + target_link_libraries(myapp1 PRIVATE lib$<$:other>) - .. versionadded:: 3.3 + # correct usage + add_executable(myapp2 main.c) + target_link_libraries(myapp2 PRIVATE $<$:libother>) - The compile language of source files when evaluating compile options. - See :ref:`the related boolean expression - ` - ``$`` - for notes about the portability of this generator expression. + 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:: $ +.. 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:: - - This generator expression is not supported by the link libraries - properties to avoid side-effects due to the double evaluation of - these properties. - -.. _`Target-Dependent Queries`: + ``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: -Target-Dependent Queries -^^^^^^^^^^^^^^^^^^^^^^^^ + .. code-block:: cmake -These queries refer to a target ``tgt``. This can be any runtime artifact, -namely: + add_library(libC_Clang ...) + add_library(libCXX_Clang ...) + add_library(libC_Intel ...) + add_library(libCXX_Intel ...) -* 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` + 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>) -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``. + 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. -.. genex:: $ + See :ref:`the note related to + ` + ``$`` for constraints about the usage of this + generator expression. - .. versionadded:: 3.12 +Link Features +^^^^^^^^^^^^^ - The target name ``tgt`` if the target exists, an empty string otherwise. +.. genex:: $ - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on. + .. versionadded:: 3.24 -.. genex:: $ + Specify a set of libraries to link to a target, along with a ``feature`` + which provides details about *how* they should be linked. For example: - Full path to the ``tgt`` binary file. + .. code-block:: cmake - 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`. + add_library(lib1 STATIC ...) + add_library(lib2 ...) + target_link_libraries(lib2 PRIVATE "$") -.. genex:: $ + This specifies that ``lib2`` should link to ``lib1`` and use the + ``WHOLE_ARCHIVE`` feature when doing so. - .. versionadded:: 3.15 + Feature names are case-sensitive and may only contain letters, numbers and + underscores. Feature names defined in all uppercase are reserved for CMake's + own built-in features. The pre-defined built-in library features are: - Base name of ``tgt``, i.e. ``$`` without prefix and - suffix. - For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``. + .. include:: ../variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt - 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_`. + Built-in and custom library features are defined in terms of the following + variables: - The :prop_tgt:`_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target - properties can also be considered. + * :variable:`CMAKE__LINK_LIBRARY_USING__SUPPORTED` + * :variable:`CMAKE__LINK_LIBRARY_USING_` + * :variable:`CMAKE_LINK_LIBRARY_USING__SUPPORTED` + * :variable:`CMAKE_LINK_LIBRARY_USING_` - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on. + The value used for each of these variables is the value as set at the end of + the directory scope in which the target was created. The usage is as follows: -.. genex:: $ + 1. If the language-specific + :variable:`CMAKE__LINK_LIBRARY_USING__SUPPORTED` variable + is true, the ``feature`` must be defined by the corresponding + :variable:`CMAKE__LINK_LIBRARY_USING_` variable. + 2. If no language-specific ``feature`` is supported, then the + :variable:`CMAKE_LINK_LIBRARY_USING__SUPPORTED` variable must be + true and the ``feature`` must be defined by the corresponding + :variable:`CMAKE_LINK_LIBRARY_USING_` variable. - .. versionadded:: 3.15 + The following limitations should be noted: - Prefix of the ``tgt`` filename (such as ``lib``). + * The ``library-list`` can specify CMake targets or libraries. + Any CMake target of type :ref:`OBJECT ` + or :ref:`INTERFACE ` will ignore the feature aspect + of the expression and instead be linked in the standard way. - See also the :prop_tgt:`PREFIX` target property. + * The ``$`` generator expression can only be used to + specify link libraries. In practice, this means it can appear in the + :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INTERFACE_LINK_LIBRARIES`, and + :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target properties, and be + specified in :command:`target_link_libraries` and :command:`link_libraries` + commands. - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on. + * If a ``$`` generator expression appears in the + :prop_tgt:`INTERFACE_LINK_LIBRARIES` property of a target, it will be + included in the imported target generated by a :command:`install(EXPORT)` + command. It is the responsibility of the environment consuming this + import to define the link feature used by this expression. -.. genex:: $ + * Each target or library involved in the link step must have at most only + one kind of library feature. The absence of a feature is also incompatible + with all other features. For example: - .. versionadded:: 3.15 + .. code-block:: cmake - Suffix of the ``tgt`` filename (extension such as ``.so`` or ``.exe``). + add_library(lib1 ...) + add_library(lib2 ...) + add_library(lib3 ...) - See also the :prop_tgt:`SUFFIX` target property. + # lib1 will be associated with feature1 + target_link_libraries(lib2 PUBLIC "$") - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on. + # lib1 is being linked with no feature here. This conflicts with the + # use of feature1 in the line above and would result in an error. + target_link_libraries(lib3 PRIVATE lib1 lib2) -.. genex:: $ + Where it isn't possible to use the same feature throughout a build for a + given target or library, the :prop_tgt:`LINK_LIBRARY_OVERRIDE` and + :prop_tgt:`LINK_LIBRARY_OVERRIDE_` target properties can be + used to resolve such incompatibilities. - The ``tgt`` filename. + * The ``$`` generator expression does not guarantee + that the list of specified targets and libraries will be kept grouped + together. To manage constructs like ``--start-group`` and ``--end-group``, + as supported by the GNU ``ld`` linker, use the :genex:`LINK_GROUP` + generator expression instead. - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on (see policy :policy:`CMP0112`). +.. genex:: $ -.. genex:: $ + .. versionadded:: 3.24 - Directory of the ``tgt`` binary file. + Specify a group of libraries to link to a target, along with a ``feature`` + which defines how that group should be linked. For example: - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on (see policy :policy:`CMP0112`). + .. code-block:: cmake -.. genex:: $ + add_library(lib1 STATIC ...) + add_library(lib2 ...) + target_link_libraries(lib2 PRIVATE "$") - 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. + This specifies that ``lib2`` should link to ``lib1`` and ``external``, and + that both of those two libraries should be included on the linker command + line according to the definition of the ``RESCAN`` feature. -.. genex:: $ + Feature names are case-sensitive and may only contain letters, numbers and + underscores. Feature names defined in all uppercase are reserved for CMake's + own built-in features. Currently, there is only one pre-defined built-in + group feature: - .. versionadded:: 3.15 + .. include:: ../variable/LINK_GROUP_PREDEFINED_FEATURES.txt - 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``. + Built-in and custom group features are defined in terms of the following + variables: - 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_`. + * :variable:`CMAKE__LINK_GROUP_USING__SUPPORTED` + * :variable:`CMAKE__LINK_GROUP_USING_` + * :variable:`CMAKE_LINK_GROUP_USING__SUPPORTED` + * :variable:`CMAKE_LINK_GROUP_USING_` - The :prop_tgt:`_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target - properties can also be considered. + The value used for each of these variables is the value as set at the end of + the directory scope in which the target was created. The usage is as follows: - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on. + 1. If the language-specific + :variable:`CMAKE__LINK_GROUP_USING__SUPPORTED` variable + is true, the ``feature`` must be defined by the corresponding + :variable:`CMAKE__LINK_GROUP_USING_` variable. + 2. If no language-specific ``feature`` is supported, then the + :variable:`CMAKE_LINK_GROUP_USING__SUPPORTED` variable must be + true and the ``feature`` must be defined by the corresponding + :variable:`CMAKE_LINK_GROUP_USING_` variable. -.. genex:: $ + The ``LINK_GROUP`` generator expression is compatible with the + :genex:`LINK_LIBRARY` generator expression. The libraries involved in a + group can be specified using the :genex:`LINK_LIBRARY` generator expression. - .. versionadded:: 3.15 + Each target or external library involved in the link step is allowed to be + part of multiple groups, but only if all the groups involved specify the + same ``feature``. Such groups will not be merged on the linker command line, + the individual groups will still be preserved. Mixing different group + features for the same target or library is forbidden. - Prefix of file used to link target ``tgt``. + .. code-block:: cmake - See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target - properties. + add_library(lib1 ...) + add_library(lib2 ...) + add_library(lib3 ...) + add_library(lib4 ...) + add_library(lib5 ...) - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on. + target_link_libraries(lib3 PUBLIC "$") + target_link_libraries(lib4 PRIVATE "$") + # lib4 will be linked with the groups {lib1,lib2} and {lib1,lib3}. + # Both groups specify the same feature, so this is fine. -.. genex:: $ + target_link_libraries(lib5 PRIVATE "$") + # An error will be raised here because both lib1 and lib3 are part of two + # groups with different features. - .. versionadded:: 3.15 + When a target or an external library is involved in the link step as part of + a group and also as not part of any group, any occurrence of the non-group + link item will be replaced by the groups it belongs to. - Suffix of file used to link where ``tgt`` is the name of a target. + .. code-block:: cmake - The suffix corresponds to the file extension (such as ".so" or ".lib"). + add_library(lib1 ...) + add_library(lib2 ...) + add_library(lib3 ...) + add_library(lib4 ...) - See also the :prop_tgt:`SUFFIX` and :prop_tgt:`IMPORT_SUFFIX` target - properties. + target_link_libraries(lib3 PUBLIC lib1) - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on. + target_link_libraries(lib4 PRIVATE lib3 "$") + # lib4 will only be linked with lib3 and the group {lib1,lib2} -.. genex:: $ + Because ``lib1`` is part of the group defined for ``lib4``, that group then + gets applied back to the use of ``lib1`` for ``lib3``. The end result will + be as though the linking relationship for ``lib3`` had been specified as: - Name of file used to link target ``tgt``. + .. code-block:: cmake - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on (see policy :policy:`CMP0112`). + target_link_libraries(lib3 PUBLIC "$") -.. genex:: $ + Be aware that the precedence of the group over the non-group link item can + result in circular dependencies between groups. If this occurs, a fatal + error is raised because circular dependencies are not allowed for groups. - Directory of file used to link target ``tgt``. + .. code-block:: cmake - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on (see policy :policy:`CMP0112`). + add_library(lib1A ...) + add_library(lib1B ...) + add_library(lib2A ...) + add_library(lib2B ...) + add_library(lib3 ...) -.. genex:: $ + # Non-group linking relationships, these are non-circular so far + target_link_libraries(lib1A PUBLIC lib2A) + target_link_libraries(lib2B PUBLIC lib1B) - File with soname (``.so.3``) where ``tgt`` is the name of a target. -.. genex:: $ + # The addition of these groups creates circular dependencies + target_link_libraries(lib3 PRIVATE + "$" + "$" + ) - Name of file with soname (``.so.3``). + Because of the groups defined for ``lib3``, the linking relationships for + ``lib1A`` and ``lib2B`` effectively get expanded to the equivalent of: - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on (see policy :policy:`CMP0112`). + .. code-block:: cmake -.. genex:: $ + target_link_libraries(lib1A PUBLIC "$") + target_link_libraries(lib2B PUBLIC "$") - Directory of with soname (``.so.3``). + This creates a circular dependency between groups: + ``lib1A --> lib2B --> lib1A``. - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on (see policy :policy:`CMP0112`). + The following limitations should also be noted: -.. genex:: $ + * The ``library-list`` can specify CMake targets or libraries. + Any CMake target of type :ref:`OBJECT ` + or :ref:`INTERFACE ` will ignore the feature aspect + of the expression and instead be linked in the standard way. - .. versionadded:: 3.1 + * The ``$`` generator expression can only be used to + specify link libraries. In practice, this means it can appear in the + :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INTERFACE_LINK_LIBRARIES`,and + :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target properties, and be + specified in :command:`target_link_libraries` and :command:`link_libraries` + commands. - Full path to the linker generated program database file (.pdb) - where ``tgt`` is the name of a target. + * If a ``$`` generator expression appears in the + :prop_tgt:`INTERFACE_LINK_LIBRARIES` property of a target, it will be + included in the imported target generated by a :command:`install(EXPORT)` + command. It is the responsibility of the environment consuming this + import to define the link feature used by this expression. - 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_`. +Link Context +^^^^^^^^^^^^ -.. genex:: $ +.. genex:: $ - .. versionadded:: 3.15 + .. versionadded:: 3.1 - Base name of the linker generated program database file (.pdb) - where ``tgt`` is the name of a target. + 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. - 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``. + .. versionadded:: 3.24 + ``LINK_ONLY`` may also be used in a :prop_tgt:`LINK_LIBRARIES` target + property. See policy :policy:`CMP0131`. - See also the :prop_tgt:`PDB_NAME` target property and its configuration - specific variant :prop_tgt:`PDB_NAME_`. +.. genex:: $ - The :prop_tgt:`_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target - properties can also be considered. + .. versionadded:: 3.18 - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on. + 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:: $ +.. genex:: $ - .. versionadded:: 3.1 + .. versionadded:: 3.18 - Name of the linker generated program database file (.pdb). + 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. - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on (see policy :policy:`CMP0112`). -.. genex:: $ +.. _`Target-Dependent Queries`: - .. versionadded:: 3.1 +Target-Dependent Expressions +---------------------------- - Directory of the linker generated program database file (.pdb). +These queries refer to a target ``tgt``. Unless otherwise stated, this can +be any runtime artifact, namely: - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on (see policy :policy:`CMP0112`). +* 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`. -.. genex:: $ +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``. - .. versionadded:: 3.9 +.. genex:: $ - 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. + .. versionadded:: 3.12 - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on (see policy :policy:`CMP0112`). + ``1`` if ``tgt`` exists as a CMake target, else ``0``. -.. genex:: $ +.. genex:: $ - .. versionadded:: 3.24 + .. versionadded:: 3.12 - Name of the bundle directory (``my.app``, ``my.framework``, or - ``my.bundle``), where ``tgt`` is the name of a target. + 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 (see policy :policy:`CMP0112`). - -.. genex:: $ - - .. versionadded:: 3.9 + expression is evaluated on. - 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. +.. genex:: $ - Note that ``tgt`` is not added as a dependency of the target this - expression is evaluated on (see policy :policy:`CMP0112`). + 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:: $ @@ -1320,326 +1313,290 @@ which is just the string ``tgt``. :ref:`Target Usage Requirements` this is the consuming target rather than the target specifying the requirement. -.. genex:: $ +.. genex:: $ - .. versionadded:: 3.21 + .. versionadded:: 3.1 - 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**. + List of objects resulting from building ``tgt``. This would typically be + used on :ref:`object library ` targets. - 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: +.. genex:: $ - .. code-block:: cmake + ``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. - find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT) +.. genex:: $ - 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 - ) + Full path to the ``tgt`` binary file. - .. note:: + 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`. - :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. +.. genex:: $ -.. genex:: $ + .. versionadded:: 3.15 - 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. + Base name of ``tgt``, i.e. ``$`` without prefix and + suffix. + For example, if the ``tgt`` filename is ``libbase.so``, the base name is ``base``. -Output-Related Expressions -^^^^^^^^^^^^^^^^^^^^^^^^^^ + 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_`. -.. genex:: $ + The :prop_tgt:`_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. - 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. + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. -.. genex:: $ +.. genex:: $ - .. versionadded:: 3.1 + .. versionadded:: 3.15 - 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. + Prefix of the ``tgt`` filename (such as ``lib``). - .. versionadded:: 3.24 - ``LINK_ONLY`` may also be used in a :prop_tgt:`LINK_LIBRARIES` target - property. See policy :policy:`CMP0131`. + See also the :prop_tgt:`PREFIX` target property. -.. genex:: $ + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. - .. versionadded:: 3.18 +.. genex:: $ - Returns the list if it is the device link step, an empty list otherwise. - The device link step is controlled by :prop_tgt:`CUDA_SEPARABLE_COMPILATION` - and :prop_tgt:`CUDA_RESOLVE_DEVICE_SYMBOLS` properties and - policy :policy:`CMP0105`. This expression can only be used to specify link - options. + .. versionadded:: 3.15 -.. genex:: $ + Suffix of the ``tgt`` filename (extension such as ``.so`` or ``.exe``). - .. versionadded:: 3.18 + See also the :prop_tgt:`SUFFIX` target property. - 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. + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. -.. genex:: $ +.. genex:: $ - .. versionadded:: 3.24 + The ``tgt`` filename. - Specify a set of libraries to link to a target, along with a ``feature`` - which provides details about *how* they should be linked. For example: + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). - .. code-block:: cmake +.. genex:: $ - add_library(lib1 STATIC ...) - add_library(lib2 ...) - target_link_libraries(lib2 PRIVATE "$") + Directory of the ``tgt`` binary file. - This specifies that ``lib2`` should link to ``lib1`` and use the - ``WHOLE_ARCHIVE`` feature when doing so. + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). - Feature names are case-sensitive and may only contain letters, numbers and - underscores. Feature names defined in all uppercase are reserved for CMake's - own built-in features. The pre-defined built-in library features are: +.. genex:: $ - .. include:: ../variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt + 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. - Built-in and custom library features are defined in terms of the following - variables: +.. genex:: $ - * :variable:`CMAKE__LINK_LIBRARY_USING__SUPPORTED` - * :variable:`CMAKE__LINK_LIBRARY_USING_` - * :variable:`CMAKE_LINK_LIBRARY_USING__SUPPORTED` - * :variable:`CMAKE_LINK_LIBRARY_USING_` + .. versionadded:: 3.15 - The value used for each of these variables is the value as set at the end of - the directory scope in which the target was created. The usage is as follows: + 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``. - 1. If the language-specific - :variable:`CMAKE__LINK_LIBRARY_USING__SUPPORTED` variable - is true, the ``feature`` must be defined by the corresponding - :variable:`CMAKE__LINK_LIBRARY_USING_` variable. - 2. If no language-specific ``feature`` is supported, then the - :variable:`CMAKE_LINK_LIBRARY_USING__SUPPORTED` variable must be - true and the ``feature`` must be defined by the corresponding - :variable:`CMAKE_LINK_LIBRARY_USING_` variable. + 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 following limitations should be noted: + The :prop_tgt:`_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. - * The ``library-list`` can specify CMake targets or libraries. - Any CMake target of type :ref:`OBJECT ` - or :ref:`INTERFACE ` will ignore the feature aspect - of the expression and instead be linked in the standard way. + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. - * The ``$`` generator expression can only be used to - specify link libraries. In practice, this means it can appear in the - :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INTERFACE_LINK_LIBRARIES`, and - :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target properties, and be - specified in :command:`target_link_libraries` and :command:`link_libraries` - commands. +.. genex:: $ - * If a ``$`` generator expression appears in the - :prop_tgt:`INTERFACE_LINK_LIBRARIES` property of a target, it will be - included in the imported target generated by a :command:`install(EXPORT)` - command. It is the responsibility of the environment consuming this - import to define the link feature used by this expression. + .. versionadded:: 3.15 - * Each target or library involved in the link step must have at most only - one kind of library feature. The absence of a feature is also incompatible - with all other features. For example: + Prefix of file used to link target ``tgt``. - .. code-block:: cmake + See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target + properties. - add_library(lib1 ...) - add_library(lib2 ...) - add_library(lib3 ...) + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. - # lib1 will be associated with feature1 - target_link_libraries(lib2 PUBLIC "$") +.. genex:: $ - # lib1 is being linked with no feature here. This conflicts with the - # use of feature1 in the line above and would result in an error. - target_link_libraries(lib3 PRIVATE lib1 lib2) + .. versionadded:: 3.15 - Where it isn't possible to use the same feature throughout a build for a - given target or library, the :prop_tgt:`LINK_LIBRARY_OVERRIDE` and - :prop_tgt:`LINK_LIBRARY_OVERRIDE_` target properties can be - used to resolve such incompatibilities. + Suffix of file used to link where ``tgt`` is the name of a target. - * The ``$`` generator expression does not guarantee - that the list of specified targets and libraries will be kept grouped - together. To manage constructs like ``--start-group`` and ``--end-group``, - as supported by the GNU ``ld`` linker, use the :genex:`LINK_GROUP` - generator expression instead. + The suffix corresponds to the file extension (such as ".so" or ".lib"). -.. genex:: $ + See also the :prop_tgt:`SUFFIX` and :prop_tgt:`IMPORT_SUFFIX` target + properties. - .. versionadded:: 3.24 + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. - Specify a group of libraries to link to a target, along with a ``feature`` - which defines how that group should be linked. For example: +.. genex:: $ - .. code-block:: cmake + Name of file used to link target ``tgt``. - add_library(lib1 STATIC ...) - add_library(lib2 ...) - target_link_libraries(lib2 PRIVATE "$") + 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. - This specifies that ``lib2`` should link to ``lib1`` and ``external``, and - that both of those two libraries should be included on the linker command - line according to the definition of the ``RESCAN`` feature. + 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``. - Feature names are case-sensitive and may only contain letters, numbers and - underscores. Feature names defined in all uppercase are reserved for CMake's - own built-in features. Currently, there is only one pre-defined built-in - group feature: + See also the :prop_tgt:`PDB_NAME` target property and its configuration + specific variant :prop_tgt:`PDB_NAME_`. - .. include:: ../variable/LINK_GROUP_PREDEFINED_FEATURES.txt + The :prop_tgt:`_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. - Built-in and custom group features are defined in terms of the following - variables: + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. - * :variable:`CMAKE__LINK_GROUP_USING__SUPPORTED` - * :variable:`CMAKE__LINK_GROUP_USING_` - * :variable:`CMAKE_LINK_GROUP_USING__SUPPORTED` - * :variable:`CMAKE_LINK_GROUP_USING_` +.. genex:: $ - The value used for each of these variables is the value as set at the end of - the directory scope in which the target was created. The usage is as follows: + .. versionadded:: 3.1 - 1. If the language-specific - :variable:`CMAKE__LINK_GROUP_USING__SUPPORTED` variable - is true, the ``feature`` must be defined by the corresponding - :variable:`CMAKE__LINK_GROUP_USING_` variable. - 2. If no language-specific ``feature`` is supported, then the - :variable:`CMAKE_LINK_GROUP_USING__SUPPORTED` variable must be - true and the ``feature`` must be defined by the corresponding - :variable:`CMAKE_LINK_GROUP_USING_` variable. + Name of the linker generated program database file (.pdb). - The ``LINK_GROUP`` generator expression is compatible with the - :genex:`LINK_LIBRARY` generator expression. The libraries involved in a - group can be specified using the :genex:`LINK_LIBRARY` generator expression. + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). - Each target or external library involved in the link step is allowed to be - part of multiple groups, but only if all the groups involved specify the - same ``feature``. Such groups will not be merged on the linker command line, - the individual groups will still be preserved. Mixing different group - features for the same target or library is forbidden. +.. genex:: $ - .. code-block:: cmake + .. versionadded:: 3.1 - add_library(lib1 ...) - add_library(lib2 ...) - add_library(lib3 ...) - add_library(lib4 ...) - add_library(lib5 ...) + Directory of the linker generated program database file (.pdb). - target_link_libraries(lib3 PUBLIC "$") - target_link_libraries(lib4 PRIVATE "$") - # lib4 will be linked with the groups {lib1,lib2} and {lib1,lib3}. - # Both groups specify the same feature, so this is fine. + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). - target_link_libraries(lib5 PRIVATE "$") - # An error will be raised here because both lib1 and lib3 are part of two - # groups with different features. +.. genex:: $ - When a target or an external library is involved in the link step as part of - a group and also as not part of any group, any occurrence of the non-group - link item will be replaced by the groups it belongs to. + .. versionadded:: 3.9 - .. code-block:: cmake + 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. - add_library(lib1 ...) - add_library(lib2 ...) - add_library(lib3 ...) - add_library(lib4 ...) + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). - target_link_libraries(lib3 PUBLIC lib1) +.. genex:: $ - target_link_libraries(lib4 PRIVATE lib3 "$") - # lib4 will only be linked with lib3 and the group {lib1,lib2} + .. versionadded:: 3.24 - Because ``lib1`` is part of the group defined for ``lib4``, that group then - gets applied back to the use of ``lib1`` for ``lib3``. The end result will - be as though the linking relationship for ``lib3`` had been specified as: + Name of the bundle directory (``my.app``, ``my.framework``, or + ``my.bundle``), where ``tgt`` is the name of a target. - .. code-block:: cmake + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). - target_link_libraries(lib3 PUBLIC "$") +.. genex:: $ - Be aware that the precedence of the group over the non-group link item can - result in circular dependencies between groups. If this occurs, a fatal - error is raised because circular dependencies are not allowed for groups. + .. versionadded:: 3.9 - .. code-block:: cmake + 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. - add_library(lib1A ...) - add_library(lib1B ...) - add_library(lib2A ...) - add_library(lib2B ...) - add_library(lib3 ...) + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). - # Non-group linking relationships, these are non-circular so far - target_link_libraries(lib1A PUBLIC lib2A) - target_link_libraries(lib2B PUBLIC lib1B) +.. genex:: $ - # The addition of these groups creates circular dependencies - target_link_libraries(lib3 PRIVATE - "$" - "$" - ) + .. versionadded:: 3.21 - Because of the groups defined for ``lib3``, the linking relationships for - ``lib1A`` and ``lib2B`` effectively get expanded to the equivalent of: + 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 - target_link_libraries(lib1A PUBLIC "$") - target_link_libraries(lib2B PUBLIC "$") + find_package(foo CONFIG REQUIRED) # package generated by install(EXPORT) - This creates a circular dependency between groups: - ``lib1A --> lib2B --> lib1A``. + 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 + ) - The following limitations should also be noted: + .. note:: - * The ``library-list`` can specify CMake targets or libraries. - Any CMake target of type :ref:`OBJECT ` - or :ref:`INTERFACE ` will ignore the feature aspect - of the expression and instead be linked in the standard way. + :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. - * The ``$`` generator expression can only be used to - specify link libraries. In practice, this means it can appear in the - :prop_tgt:`LINK_LIBRARIES`, :prop_tgt:`INTERFACE_LINK_LIBRARIES`,and - :prop_tgt:`INTERFACE_LINK_LIBRARIES_DIRECT` target properties, and be - specified in :command:`target_link_libraries` and :command:`link_libraries` - commands. - * If a ``$`` generator expression appears in the - :prop_tgt:`INTERFACE_LINK_LIBRARIES` property of a target, it will be - included in the imported target generated by a :command:`install(EXPORT)` - command. It is the responsibility of the environment consuming this - import to define the link feature used by this expression. +Export And Install Expressions +------------------------------ .. genex:: $ @@ -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. -- cgit v0.12