diff options
Diffstat (limited to 'Help/manual/cmake-generator-expressions.7.rst')
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 200 |
1 files changed, 175 insertions, 25 deletions
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index 7f484a4..c0449fb 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -86,7 +86,7 @@ String Comparisons ``$<EQUAL:value1,value2>`` ``1`` if ``value1`` and ``value2`` are numerically equal, else ``0``. ``$<IN_LIST:string,list>`` - ``1`` if ``string`` is member of the comma-separated ``list``, else ``0``. + ``1`` if ``string`` is member of the semicolon-separated ``list``, else ``0``. Uses case-sensitive comparisons. ``$<VERSION_LESS:v1,v2>`` ``1`` if ``v1`` is a version less than ``v2``, else ``0``. @@ -110,21 +110,30 @@ Variable Queries The mapping in :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>` is also considered by this expression when it is evaluated on a property on an :prop_tgt:`IMPORTED` target. -``$<PLATFORM_ID:platform_id>`` - ``1`` if the CMake-id of the platform matches ``platform_id`` - otherwise ``0``. +``$<PLATFORM_ID:platform_ids>`` + where ``platform_ids`` is a comma-separated list. + ``1`` if the CMake's platform id matches any one of the entries in + ``platform_ids``, otherwise ``0``. See also the :variable:`CMAKE_SYSTEM_NAME` variable. -``$<C_COMPILER_ID:compiler_id>`` - ``1`` if the CMake-id of the C compiler matches ``compiler_id``, - otherwise ``0``. +``$<C_COMPILER_ID:compiler_ids>`` + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the C compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. -``$<CXX_COMPILER_ID:compiler_id>`` - ``1`` if the CMake-id of the CXX compiler matches ``compiler_id``, - otherwise ``0``. +``$<CXX_COMPILER_ID:compiler_ids>`` + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the CXX compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. -``$<Fortran_COMPILER_ID:compiler_id>`` - ``1`` if the CMake-id of the Fortran compiler matches ``compiler_id``, - otherwise ``0``. +``$<CUDA_COMPILER_ID:compiler_ids>`` + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the CUDA compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<Fortran_COMPILER_ID:compiler_ids>`` + where ``compiler_ids`` is a comma-separated list. + ``1`` if the CMake's compiler id of the Fortran compiler matches any one + of the entries in ``compiler_ids``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<C_COMPILER_VERSION:version>`` ``1`` if the version of the C compiler matches ``version``, otherwise ``0``. @@ -132,6 +141,9 @@ Variable Queries ``$<CXX_COMPILER_VERSION:version>`` ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<CUDA_COMPILER_VERSION:version>`` + ``1`` if the version of the CXX compiler matches ``version``, otherwise ``0``. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. ``$<Fortran_COMPILER_VERSION:version>`` ``1`` if the version of the Fortran compiler matches ``version``, otherwise ``0``. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. @@ -152,10 +164,46 @@ Variable Queries .. _`Boolean COMPILE_LANGUAGE Generator Expression`: -``$<COMPILE_LANGUAGE:language>`` - ``1`` when the language used for compilation unit matches ``language``, - otherwise ``0``. This expression may be used to specify compile options, - compile definitions, and include directories for source files of a +``$<COMPILE_LANG_AND_ID:language,compiler_ids>`` + ``1`` when the language used for compilation unit matches ``language`` and + the CMake's compiler id of the language compiler matches any one of the + entries in ``compiler_ids``, otherwise ``0``. This expression is a short form + for the combination of ``$<COMPILE_LANGUAGE:language>`` and + ``$<LANG_COMPILER_ID:compiler_ids>``. This expression may be used to specify + compile options, compile definitions, and include directories for source files of a + particular language and compiler combination in a target. For example: + + .. code-block:: cmake + + add_executable(myapp main.cpp foo.c bar.cpp zot.cu) + target_compile_definitions(myapp + PRIVATE $<$<COMPILE_LANG_AND_ID:CXX,AppleClang,Clang>:COMPILING_CXX_WITH_CLANG> + $<$<COMPILE_LANG_AND_ID:CXX,Intel>:COMPILING_CXX_WITH_INTEL> + $<$<COMPILE_LANG_AND_ID:C,Clang>:COMPILING_C_WITH_CLANG> + ) + + This specifies the use of different compile definitions based on both + the compiler id and compilation language. This example will have a + ``COMPILING_CXX_WITH_CLANG`` compile definition when Clang is the CXX + compiler, and ``COMPILING_CXX_WITH_INTEL`` when Intel is the CXX compiler. + Likewise when the C compiler is Clang it will only see the ``COMPILING_C_WITH_CLANG`` + definition. + + Without the ``COMPILE_LANG_AND_ID`` generator expression the same logic + would be expressed as: + + .. code-block:: cmake + + target_compile_definitions(myapp + PRIVATE $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Clang>>:COMPILING_CXX_WITH_CLANG> + $<$<AND:$<COMPILE_LANGUAGE:CXX>,$<CXX_COMPILER_ID:Intel>>:COMPILING_CXX_WITH_INTEL> + $<$<AND:$<COMPILE_LANGUAGE:C>,$<C_COMPILER_ID:Clang>>:COMPILING_C_WITH_CLANG> + ) + +``$<COMPILE_LANGUAGE:languages>`` + ``1`` when the language used for compilation unit matches any of the entries + in ``languages``, otherwise ``0``. This expression may be used to specify + compile options, compile definitions, and include directories for source files of a particular language in a target. For example: .. code-block:: cmake @@ -169,7 +217,7 @@ Variable Queries $<$<COMPILE_LANGUAGE:CUDA>:COMPILING_CUDA> ) target_include_directories(myapp - PRIVATE $<$<COMPILE_LANGUAGE:CXX>:/opt/foo/cxx_headers> + PRIVATE $<$<COMPILE_LANGUAGE:CXX,CUDA>:/opt/foo/headers> ) This specifies the use of the ``-fno-exceptions`` compile option, @@ -285,6 +333,10 @@ String Transformations ``$<JOIN:list,string>`` Joins the list with the content of ``string``. +``$<REMOVE_DUPLICATES:list>`` + Removes duplicated items in the given ``list``. +``$<FILTER:list,INCLUDE|EXCLUDE,regex>`` + Includes or removes items from ``list`` that match the regular expression ``regex``. ``$<LOWER_CASE:string>`` Content of ``string`` converted to lower case. ``$<UPPER_CASE:string>`` @@ -338,16 +390,19 @@ Variable Queries ``$<CONFIGURATION>`` Configuration name. Deprecated since CMake 3.0. Use ``CONFIG`` instead. ``$<PLATFORM_ID>`` - The CMake-id of the platform. + The current system's CMake platform id. See also the :variable:`CMAKE_SYSTEM_NAME` variable. ``$<C_COMPILER_ID>`` - The CMake-id of the C compiler used. + The CMake's compiler id of the C compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<CXX_COMPILER_ID>`` - The CMake-id of the CXX compiler used. + The CMake's compiler id of the CXX compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. +``$<CUDA_COMPILER_ID>`` + The CMake's compiler id of the CUDA compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<Fortran_COMPILER_ID>`` - The CMake-id of the Fortran compiler used. + The CMake's compiler id of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_ID` variable. ``$<C_COMPILER_VERSION>`` The version of the C compiler used. @@ -355,6 +410,9 @@ Variable Queries ``$<CXX_COMPILER_VERSION>`` The version of the CXX compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. +``$<CUDA_COMPILER_VERSION>`` + The version of the CUDA compiler used. + See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. ``$<Fortran_COMPILER_VERSION>`` The version of the Fortran compiler used. See also the :variable:`CMAKE_<LANG>_COMPILER_VERSION` variable. @@ -372,13 +430,85 @@ Target-Dependent Queries Expands to the ``tgt`` if the given target exists, an empty string otherwise. ``$<TARGET_FILE:tgt>`` - Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a target. + Full path to main file (.exe, .so.1.2, .a) where ``tgt`` is the name of a + target. +``$<TARGET_FILE_BASE_NAME:tgt>`` + Base name of main file where ``tgt`` is the name of a target. + + The base name corresponds to the target file name (see + ``$<TARGET_FILE_NAME:tgt>``) without prefix and suffix. For example, if + target file name is ``libbase.so``, the base name is ``base``. + + See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + :prop_tgt:`LIBRARY_OUTPUT_NAME` and :prop_tgt:`RUNTIME_OUTPUT_NAME` + target properties and their configuration specific variants + :prop_tgt:`OUTPUT_NAME_<CONFIG>`, :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>`, + :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>` and + :prop_tgt:`RUNTIME_OUTPUT_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. +``$<TARGET_FILE_PREFIX:tgt>`` + Prefix of main file where ``tgt`` is the name of a target. + + See also the :prop_tgt:`PREFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. +``$<TARGET_FILE_SUFFIX:tgt>`` + Suffix of main file where ``tgt`` is the name of a target. + + The suffix corresponds to the file extension (such as ".so" or ".exe"). + + See also the :prop_tgt:`SUFFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. ``$<TARGET_FILE_NAME:tgt>`` Name of main file (.exe, .so.1.2, .a). ``$<TARGET_FILE_DIR:tgt>`` Directory of main file (.exe, .so.1.2, .a). ``$<TARGET_LINKER_FILE:tgt>`` File used to link (.a, .lib, .so) where ``tgt`` is the name of a target. +``$<TARGET_LINKER_FILE_BASE_NAME:tgt>`` + Base name of file used to link where ``tgt`` is the name of a target. + + The base name corresponds to the target linker file name (see + ``$<TARGET_LINKER_FILE_NAME:tgt>``) without prefix and suffix. For example, + if target file name is ``libbase.a``, the base name is ``base``. + + See also the :prop_tgt:`OUTPUT_NAME`, :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + and :prop_tgt:`LIBRARY_OUTPUT_NAME` target properties and their configuration + specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>`, + :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` and + :prop_tgt:`LIBRARY_OUTPUT_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. +``$<TARGET_LINKER_FILE_PREFIX:tgt>`` + Prefix of file used to link where ``tgt`` is the name of a target. + + See also the :prop_tgt:`PREFIX` and :prop_tgt:`IMPORT_PREFIX` target + properties. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. +``$<TARGET_LINKER_FILE_SUFFIX:tgt>`` + Suffix of file used to link where ``tgt`` is the name of a target. + + The suffix corresponds to the file extension (such as ".so" or ".lib"). + + See also the :prop_tgt:`SUFFIX` and :prop_tgt:`IMPORT_SUFFIX` target + properties. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. ``$<TARGET_LINKER_FILE_NAME:tgt>`` Name of file used to link (.a, .lib, .so). ``$<TARGET_LINKER_FILE_DIR:tgt>`` @@ -396,6 +526,22 @@ Target-Dependent Queries See also the :prop_tgt:`PDB_NAME` and :prop_tgt:`PDB_OUTPUT_DIRECTORY` target properties and their configuration specific variants :prop_tgt:`PDB_NAME_<CONFIG>` and :prop_tgt:`PDB_OUTPUT_DIRECTORY_<CONFIG>`. +``$<TARGET_PDB_FILE_BASE_NAME:tgt>`` + Base name of the linker generated program database file (.pdb) + where ``tgt`` is the name of a target. + + The base name corresponds to the target PDB file name (see + ``$<TARGET_PDB_FILE_NAME:tgt>``) without prefix and suffix. For example, + if target file name is ``base.pdb``, the base name is ``base``. + + See also the :prop_tgt:`PDB_NAME` target property and its configuration + specific variant :prop_tgt:`PDB_NAME_<CONFIG>`. + + The :prop_tgt:`<CONFIG>_POSTFIX` and :prop_tgt:`DEBUG_POSTFIX` target + properties can also be considered. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. ``$<TARGET_PDB_FILE_NAME:tgt>`` Name of the linker generated program database file (.pdb). ``$<TARGET_PDB_FILE_DIR:tgt>`` @@ -449,12 +595,16 @@ Output-Related Expressions Content of ``...`` converted to a C identifier. The conversion follows the same behavior as :command:`string(MAKE_C_IDENTIFIER)`. ``$<TARGET_OBJECTS:objLib>`` - List of objects resulting from build of ``objLib``. ``objLib`` must be an - object of type ``OBJECT_LIBRARY``. + List of objects resulting from build of ``objLib``. ``$<SHELL_PATH:...>`` Content of ``...`` converted to shell path style. For example, slashes are converted to backslashes in Windows shells and drive letters are converted to posix paths in MSYS shells. The ``...`` must be an absolute path. + The ``...`` may be a :ref:`semicolon-separated list <CMake Language Lists>` + of paths, in which case each path is converted individually and a result + list is generated using the shell path separator (``:`` on POSIX and + ``;`` on Windows). Be sure to enclose the argument containing this genex + in double quotes in CMake source code so that ``;`` does not split arguments. Debugging ========= |