diff options
Diffstat (limited to 'Help/manual/cmake-generator-expressions.7.rst')
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 319 |
1 files changed, 296 insertions, 23 deletions
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index c3e87d77c9..9da37999b1 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -446,16 +446,20 @@ command. All paths are expected to be in cmake-style format. components from a path. See :ref:`Path Structure And Terminology` for the meaning of each path component. + .. versionchanged:: 3.27 + All operations now accept a list of paths as argument. When a list of paths + is specified, the operation will be applied to each path. + :: - $<PATH:GET_ROOT_NAME,path> - $<PATH:GET_ROOT_DIRECTORY,path> - $<PATH:GET_ROOT_PATH,path> - $<PATH:GET_FILENAME,path> - $<PATH:GET_EXTENSION[,LAST_ONLY],path> - $<PATH:GET_STEM[,LAST_ONLY],path> - $<PATH:GET_RELATIVE_PART,path> - $<PATH:GET_PARENT_PATH,path> + $<PATH:GET_ROOT_NAME,path...> + $<PATH:GET_ROOT_DIRECTORY,path...> + $<PATH:GET_ROOT_PATH,path...> + $<PATH:GET_FILENAME,path...> + $<PATH:GET_EXTENSION[,LAST_ONLY],path...> + $<PATH:GET_STEM[,LAST_ONLY],path...> + $<PATH:GET_RELATIVE_PART,path...> + $<PATH:GET_PARENT_PATH,path...> If a requested component is not present in the path, an empty string is returned. @@ -470,9 +474,14 @@ These expressions provide the generation-time capabilities equivalent to the options of the :command:`cmake_path` command. All paths are expected to be in cmake-style format. +.. versionchanged:: 3.27 + All operations now accept a list of paths as argument. When a list of paths + is specified, the operation will be applied to each path. + + .. _GenEx PATH-CMAKE_PATH: -.. genex:: $<PATH:CMAKE_PATH[,NORMALIZE],path> +.. genex:: $<PATH:CMAKE_PATH[,NORMALIZE],path...> .. versionadded:: 3.24 @@ -483,7 +492,7 @@ in cmake-style format. When the ``NORMALIZE`` option is specified, the path is :ref:`normalized <Normalization>` after the conversion. -.. genex:: $<PATH:APPEND,path,input,...> +.. genex:: $<PATH:APPEND,path...,input,...> .. versionadded:: 3.24 @@ -493,7 +502,7 @@ in cmake-style format. See :ref:`cmake_path(APPEND) <APPEND>` for more details. -.. genex:: $<PATH:REMOVE_FILENAME,path> +.. genex:: $<PATH:REMOVE_FILENAME,path...> .. versionadded:: 3.24 @@ -503,7 +512,7 @@ in cmake-style format. See :ref:`cmake_path(REMOVE_FILENAME) <REMOVE_FILENAME>` for more details. -.. genex:: $<PATH:REPLACE_FILENAME,path,input> +.. genex:: $<PATH:REPLACE_FILENAME,path...,input> .. versionadded:: 3.24 @@ -513,7 +522,7 @@ in cmake-style format. See :ref:`cmake_path(REPLACE_FILENAME) <REPLACE_FILENAME>` for more details. -.. genex:: $<PATH:REMOVE_EXTENSION[,LAST_ONLY],path> +.. genex:: $<PATH:REMOVE_EXTENSION[,LAST_ONLY],path...> .. versionadded:: 3.24 @@ -521,7 +530,7 @@ in cmake-style format. See :ref:`cmake_path(REMOVE_EXTENSION) <REMOVE_EXTENSION>` for more details. -.. genex:: $<PATH:REPLACE_EXTENSION[,LAST_ONLY],path,input> +.. genex:: $<PATH:REPLACE_EXTENSION[,LAST_ONLY],path...,input> .. versionadded:: 3.24 @@ -530,14 +539,14 @@ in cmake-style format. See :ref:`cmake_path(REPLACE_EXTENSION) <REPLACE_EXTENSION>` for more details. -.. genex:: $<PATH:NORMAL_PATH,path> +.. genex:: $<PATH:NORMAL_PATH,path...> .. versionadded:: 3.24 Returns ``path`` normalized according to the steps described in :ref:`Normalization`. -.. genex:: $<PATH:RELATIVE_PATH,path,base_directory> +.. genex:: $<PATH:RELATIVE_PATH,path...,base_directory> .. versionadded:: 3.24 @@ -547,7 +556,7 @@ in cmake-style format. See :ref:`cmake_path(RELATIVE_PATH) <cmake_path-RELATIVE_PATH>` for more details. -.. genex:: $<PATH:ABSOLUTE_PATH[,NORMALIZE],path,base_directory> +.. genex:: $<PATH:ABSOLUTE_PATH[,NORMALIZE],path...,base_directory> .. versionadded:: 3.24 @@ -1409,6 +1418,7 @@ In the following, the phrase "the ``tgt`` filename" means the name of the expression is being evaluated. .. genex:: $<TARGET_PROPERTY:prop> + :target: TARGET_PROPERTY:prop Value of the property ``prop`` on the target for which the expression is being evaluated. Note that for generator expressions in @@ -1494,6 +1504,76 @@ In the following, the phrase "the ``tgt`` filename" means the name of the Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). +.. genex:: $<TARGET_IMPORT_FILE:tgt> + + .. versionadded:: 3.27 + + Full path to the linker import file. On DLL platforms, it would be the + ``.lib`` file. On AIX, for the executables, and on macOS, for the shared + libraries, it could be, respectively, the ``.imp`` or ``.tbd`` import file, + depending of the value of :prop_tgt:`ENABLE_EXPORTS` property. + + An empty string is returned when there is no import file associated with the + target. + +.. genex:: $<TARGET_IMPORT_FILE_BASE_NAME:tgt> + + .. versionadded:: 3.27 + + Base name of file linker import file of the target ``tgt`` without prefix and + suffix. For example, if target file name is ``libbase.tbd``, the base name is + ``base``. + + See also the :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`ARCHIVE_OUTPUT_NAME` + target properties and their configuration specific variants + :prop_tgt:`OUTPUT_NAME_<CONFIG>` and :prop_tgt:`ARCHIVE_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. + +.. genex:: $<TARGET_IMPORT_FILE_PREFIX:tgt> + + .. versionadded:: 3.27 + + Prefix of the import file of the target ``tgt``. + + See also the :prop_tgt:`IMPORT_PREFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_IMPORT_FILE_SUFFIX:tgt> + + .. versionadded:: 3.27 + + Suffix of the import file of the target ``tgt``. + + The suffix corresponds to the file extension (such as ".lib" or ".tbd"). + + See also the :prop_tgt:`IMPORT_SUFFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_IMPORT_FILE_NAME:tgt> + + .. versionadded:: 3.27 + + Name of the import file of the target target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_IMPORT_FILE_DIR:tgt> + + Directory of the import file of the target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + .. genex:: $<TARGET_LINKER_FILE:tgt> File used when linking to the ``tgt`` target. This will usually @@ -1501,13 +1581,22 @@ In the following, the phrase "the ``tgt`` filename" means the name of the but for a shared library on DLL platforms, it would be the ``.lib`` import library associated with the DLL. + .. versionadded:: 3.27 + On macOS, it could be the ``.tbd`` import file associated with the shared + library, depending of the value of :prop_tgt:`ENABLE_EXPORTS` property. + + This generator expression is equivalent to + :genex:`$<TARGET_LINKER_LIBRARY_FILE>` or + :genex:`$<TARGET_LINKER_IMPORT_FILE>` generator expressions, depending of the + characteristics of the target and the platform. + .. genex:: $<TARGET_LINKER_FILE_BASE_NAME:tgt> .. versionadded:: 3.15 Base name of file used to link the target ``tgt``, i.e. - ``$<TARGET_LINKER_FILE_NAME:tgt>`` without prefix and suffix. For example, - if target file name is ``libbase.a``, the base name is ``base``. + :genex:`$<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 @@ -1561,9 +1650,151 @@ In the following, the phrase "the ``tgt`` filename" means the name of the Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). +.. genex:: $<TARGET_LINKER_LIBRARY_FILE:tgt> + + .. versionadded:: 3.27 + + File used when linking o the ``tgt`` target is done using directly the + library, and not an import file. This will usually be the library that + ``tgt`` represents (``.a``, ``.so``, ``.dylib``). So, on DLL platforms, it + will be an empty string. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_BASE_NAME:tgt> + + .. versionadded:: 3.27 + + Base name of library file used to link the target ``tgt``, i.e. + :genex:`$<TARGET_LINKER_LIBRARY_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. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_PREFIX:tgt> + + .. versionadded:: 3.27 + + Prefix of the library file used to link target ``tgt``. + + See also the :prop_tgt:`PREFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_SUFFIX:tgt> + + .. versionadded:: 3.27 + + Suffix of the library file used to link target ``tgt``. + + The suffix corresponds to the file extension (such as ".a" or ".dylib"). + + See also the :prop_tgt:`SUFFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_NAME:tgt> + + .. versionadded:: 3.27 + + Name of the library file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_LIBRARY_FILE_DIR:tgt> + + .. versionadded:: 3.27 + + Directory of the library file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE:tgt> + + .. versionadded:: 3.27 + + File used when linking to the ``tgt`` target is done using an import + file. This will usually be the import file that ``tgt`` represents + (``.lib``, ``.tbd``). So, when no import file is involved in the link step, + an empty string is returned. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_BASE_NAME:tgt> + + .. versionadded:: 3.27 + + Base name of the import file used to link the target ``tgt``, i.e. + :genex:`$<TARGET_LINKER_IMPORT_FILE_NAME:tgt>` without prefix and suffix. + For example, if target file name is ``libbase.tbd``, the base name is ``base``. + + See also the :prop_tgt:`OUTPUT_NAME` and :prop_tgt:`ARCHIVE_OUTPUT_NAME`, + target properties and their configuration + specific variants :prop_tgt:`OUTPUT_NAME_<CONFIG>` and + :prop_tgt:`ARCHIVE_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. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_PREFIX:tgt> + + .. versionadded:: 3.27 + + Prefix of the import file used to link target ``tgt``. + + See also the :prop_tgt:`IMPORT_PREFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_SUFFIX:tgt> + + .. versionadded:: 3.27 + + Suffix of the import file used to link target ``tgt``. + + The suffix corresponds to the file extension (such as ".lib" or ".tbd"). + + See also the :prop_tgt:`IMPORT_SUFFIX` target property. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_NAME:tgt> + + .. versionadded:: 3.27 + + Name of the import file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_LINKER_IMPORT_FILE_DIR:tgt> + + .. versionadded:: 3.27 + + Directory of the import file used to link target ``tgt``. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + .. genex:: $<TARGET_SONAME_FILE:tgt> File with soname (``.so.3``) where ``tgt`` is the name of a target. + .. genex:: $<TARGET_SONAME_FILE_NAME:tgt> Name of file with soname (``.so.3``). @@ -1573,11 +1804,35 @@ In the following, the phrase "the ``tgt`` filename" means the name of the .. genex:: $<TARGET_SONAME_FILE_DIR:tgt> - Directory of with soname (``.so.3``). + Directory 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:: $<TARGET_SONAME_IMPORT_FILE:tgt> + + .. versionadded:: 3.27 + + Import file with soname (``.3.tbd``) where ``tgt`` is the name of a target. + +.. genex:: $<TARGET_SONAME_IMPORT_FILE_NAME:tgt> + + .. versionadded:: 3.27 + + Name of the import file with soname (``.3.tbd``). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + +.. genex:: $<TARGET_SONAME_IMPORT_FILE_DIR:tgt> + + .. versionadded:: 3.27 + + Directory of the import file with soname (``.3.tbd``). + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on. + .. genex:: $<TARGET_PDB_FILE:tgt> .. versionadded:: 3.1 @@ -1668,7 +1923,9 @@ In the following, the phrase "the ``tgt`` filename" means the name of the 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 + dependencies. If only the directories of the DLLs are needed, see the + :genex:`TARGET_RUNTIME_DLL_DIRS` generator expression. + 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**. @@ -1700,6 +1957,20 @@ On platforms that support runtime paths (``RPATH``), refer to the :prop_tgt:`INSTALL_RPATH` target property. On Apple platforms, refer to the :prop_tgt:`INSTALL_NAME_DIR` target property. +.. genex:: $<TARGET_RUNTIME_DLL_DIRS:tgt> + + .. versionadded:: 3.27 + + List of the directories which contain the DLLs that the target depends on at + runtime (see :genex:`TARGET_RUNTIME_DLLS`). 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 e.g. be used to create a batch file using + :command:`file(GENERATE)` which sets the PATH environment variable accordingly. + Export And Install Expressions ------------------------------ @@ -1725,8 +1996,10 @@ Export And Install Expressions 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. + :prop_tgt:`INSTALL_NAME_DIR` property, the ``INSTALL_NAME_DIR`` argument of + :command:`install(RUNTIME_DEPENDENCY_SET)`, the code argument of + :command:`install(CODE)`, or the file argument of :command:`install(SCRIPT)`, + and empty otherwise. Multi-level Expression Evaluation --------------------------------- |