diff options
Diffstat (limited to 'Help/manual/cmake-generator-expressions.7.rst')
| -rw-r--r-- | Help/manual/cmake-generator-expressions.7.rst | 285 |
1 files changed, 265 insertions, 20 deletions
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst index df13dd0..22c14df 100644 --- a/Help/manual/cmake-generator-expressions.7.rst +++ b/Help/manual/cmake-generator-expressions.7.rst @@ -599,7 +599,9 @@ String Transformations .. versionadded:: 3.15 - Removes duplicated items in the given ``list``. + 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:: $<FILTER:list,INCLUDE|EXCLUDE,regex> @@ -1019,8 +1021,19 @@ which is just the string ``tgt``. .. versionadded:: 3.9 - Full path to the bundle directory (``my.app``, ``my.framework``, or - ``my.bundle``) where ``tgt`` is the name of a target. + Full path to the bundle directory (``/path/to/my.app``, + ``/path/to/my.framework``, or ``/path/to/my.bundle``), + where ``tgt`` is the name of a target. + + Note that ``tgt`` is not added as a dependency of the target this + expression is evaluated on (see policy :policy:`CMP0112`). + +.. genex:: $<TARGET_BUNDLE_DIR_NAME:tgt> + + .. versionadded:: 3.24 + + Name of the bundle directory (``my.app``, ``my.framework``, or + ``my.bundle``), where ``tgt`` is the name of a target. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). @@ -1030,10 +1043,11 @@ which is just the string ``tgt``. .. versionadded:: 3.9 Full path to the bundle content directory where ``tgt`` is the name of a - target. For the macOS SDK it leads to ``my.app/Contents``, ``my.framework``, - or ``my.bundle/Contents``. For all other SDKs (e.g. iOS) it leads to - ``my.app``, ``my.framework``, or ``my.bundle`` due to the flat bundle - structure. + target. For the macOS SDK it leads to ``/path/to/my.app/Contents``, + ``/path/to/my.framework``, or ``/path/to/my.bundle/Contents``. + For all other SDKs (e.g. iOS) it leads to ``/path/to/my.app``, + ``/path/to/my.framework``, or ``/path/to/my.bundle`` due to the flat + bundle structure. Note that ``tgt`` is not added as a dependency of the target this expression is evaluated on (see policy :policy:`CMP0112`). @@ -1057,10 +1071,10 @@ which is just the string ``tgt``. .. versionadded:: 3.21 List of DLLs that the target depends on at runtime. This is determined by - the locations of all the ``SHARED`` and ``MODULE`` targets in the target's - transitive dependencies. Using this generator expression on targets other - than executables, ``SHARED`` libraries, and ``MODULE`` libraries is an error. - On non-DLL platforms, it evaluates to an empty string. + 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, it evaluates to an empty string. This generator expression can be used to copy all of the DLLs that a target depends on into its output directory in a ``POST_BUILD`` custom command. For @@ -1080,9 +1094,9 @@ which is just the string ``tgt``. .. note:: :ref:`Imported Targets` are supported only if they know the location - of their ``.dll`` files. An imported ``SHARED`` or ``MODULE`` library - must have :prop_tgt:`IMPORTED_LOCATION` set to its ``.dll`` file. See - the :ref:`add_library imported libraries <add_library imported libraries>` + 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 <add_library imported libraries>` section for details. Many :ref:`Find Modules` produce imported targets with the ``UNKNOWN`` type and therefore will be ignored. @@ -1106,12 +1120,243 @@ Output-Related Expressions .. versionadded:: 3.1 - Content of ``...`` except when evaluated in a link interface while - propagating :ref:`Target Usage Requirements`, in which case it is the - empty string. - Intended for use only in an :prop_tgt:`INTERFACE_LINK_LIBRARIES` target - property, perhaps via the :command:`target_link_libraries` command, - to specify private link dependencies without other usage requirements. + Content of ``...``, except while collecting :ref:`Target Usage Requirements`, + in which case it is the empty string. This is intended for use in an + :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property, typically populated + via the :command:`target_link_libraries` command, to specify private link + dependencies without other usage requirements. + + .. versionadded:: 3.24 + ``LINK_ONLY`` may also be used in a :prop_tgt:`LINK_LIBRARIES` target + property. See policy :policy:`CMP0131`. + +.. genex:: $<LINK_LIBRARY:feature,library-list> + + .. versionadded:: 3.24 + + Manage how libraries are specified during the link step. + This expression may be used to specify how to link libraries in a target. + For example: + + .. code-block:: cmake + + add_library(lib1 STATIC ...) + add_library(lib2 ...) + target_link_libraries(lib2 PRIVATE "$<LINK_LIBRARY:load_archive,lib1>") + + This specify to use the ``lib1`` target with feature ``load_archive`` for + linking target ``lib2``. The feature must have be defined by + :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` variable or, if + :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` is false, + by :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` variable. + + .. note:: + + The evaluation of this generator expression will use, for the following + variables, the values defined at the level of the creation of the target: + + * :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_<LANG>_LINK_LIBRARY_USING_<FEATURE>` + * :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_LINK_LIBRARY_USING_<FEATURE>` + + This expression can only be used to specify link libraries (i.e. part of + :command:`link_libraries` or :command:`target_link_libraries` commands and + :prop_tgt:`LINK_LIBRARIES` or :prop_tgt:`INTERFACE_LINK_LIBRARIES` target + properties). + + .. note:: + + If this expression appears in the :prop_tgt:`INTERFACE_LINK_LIBRARIES` + property of a target, it will be included in the imported target generated + by :command:`install(EXPORT)` command. It is the responsibility of the + environment consuming this import to define the link feature used by this + expression. + + The ``library-list`` argument can hold CMake targets or external libraries. + Any CMake target of type :ref:`OBJECT <Object Libraries>` or + :ref:`INTERFACE <Interface Libraries>` will be ignored by this expression and + will be handled in the standard way. + + Each target or external library involved in the link step must have only one + kind of feature (the absence of feature is also incompatible with any + feature). For example: + + .. code-block:: cmake + + add_library(lib1 ...) + + add_library(lib2 ...) + target_link_libraries(lib2 PUBLIC "$<LINK_LIBRARY:feature1,lib1>") + + add_library(lib3 ...) + target_link_libraries(lib3 PRIVATE lib1 lib2) + # an error will be raised here because lib1 has two different features + + To resolve such incompatibilities, the :prop_tgt:`LINK_LIBRARY_OVERRIDE` + and :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties can be + used. + + .. note:: + + This expression does not guarantee that the list of specified libraries + will be kept grouped. So, to manage constructs like ``start-group`` and + ``end-group``, as supported by ``GNU ld``, the :genex:`LINK_GROUP` + generator expression can be used. + + CMake pre-defines some features of general interest: + + .. include:: ../variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt + +.. genex:: $<LINK_GROUP:feature,library-list> + + .. versionadded:: 3.24 + + Manage the grouping of libraries during the link step. + This expression may be used to specify how to kept groups of libraries during + the link of a target. + For example: + + .. code-block:: cmake + + add_library(lib1 STATIC ...) + add_library(lib2 ...) + target_link_libraries(lib2 PRIVATE "$<LINK_GROUP:cross_refs,lib1,external>") + + This specify to use the ``lib1`` target and ``external`` library with the + group feature ``cross_refs`` for linking target ``lib2``. The feature must + have be defined by :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` + variable or, if :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + is false, by :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` variable. + + .. note:: + + The evaluation of this generator expression will use, for the following + variables, the values defined at the level of the creation of the target: + + * :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_<LANG>_LINK_GROUP_USING_<FEATURE>` + * :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>_SUPPORTED` + * :variable:`CMAKE_LINK_GROUP_USING_<FEATURE>` + + This expression can only be used to specify link libraries (i.e. part of + :command:`link_libraries` or :command:`target_link_libraries` commands and + :prop_tgt:`LINK_LIBRARIES` or :prop_tgt:`INTERFACE_LINK_LIBRARIES` target + properties). + + .. note:: + + If this expression appears in the :prop_tgt:`INTERFACE_LINK_LIBRARIES` + property of a target, it will be included in the imported target generated + by :command:`install(EXPORT)` command. It is the responsibility of the + environment consuming this import to define the link feature used by this + expression. + + The ``library-list`` argument can hold CMake targets or external libraries. + Any CMake target of type :ref:`OBJECT <Object Libraries>` or + :ref:`INTERFACE <Interface Libraries>` will be ignored by this expression and + will be handled in the standard way. + + .. note:: + + This 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. + + Each target or external library involved in the link step can be part of + different groups as far as these groups use the same feature, so mixing + different group features for the same target or library is forbidden. The + different groups will be part of the link step. + + .. code-block:: cmake + + add_library(lib1 ...) + add_library(lib2 ...) + + add_library(lib3 ...) + target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>") + + add_library(lib4 ...) + target_link_libraries(lib4 PRIVATE "$<LINK_GROUP:feature1,lib1,lib3>") + # lib4 will be linked with the groups {lib1,lib2} and {lib1,lib3} + + add_library(lib5 ...) + target_link_libraries(lib5 PRIVATE "$<LINK_GROUP:feature2,lib1,lib3>") + # an error will be raised here because lib1 is part of two groups with + # different features + + When a target or an external library is involved in the link step as part of + a group and also as standalone, any occurrence of the standalone link item + will be replaced by the group or groups it belong to. + + .. code-block:: cmake + + add_library(lib1 ...) + add_library(lib2 ...) + + add_library(lib3 ...) + target_link_libraries(lib3 PUBLIC lib1) + + add_library(lib4 ...) + target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>") + # lib4 will only be linked with lib3 and the group {lib1,lib2} + + This example will be "re-written" by CMake in the following form: + + .. code-block:: cmake + + add_library(lib1 ...) + add_library(lib2 ...) + + add_library(lib3 ...) + target_link_libraries(lib3 PUBLIC "$<LINK_GROUP:feature1,lib1,lib2>") + + add_library(lib4 ...) + target_link_libraries(lib4 PRIVATE lib3 "$<LINK_GROUP:feature1,lib1,lib2>") + # lib4 will only be linked with lib3 and the group {lib1,lib2} + + Be aware that the precedence of the group over the standalone link item can + result in some circular dependency between groups, which will raise an + error because circular dependencies are not allowed for groups. + + .. code-block:: cmake + + add_library(lib1A ...) + add_library(lib1B ...) + + add_library(lib2A ...) + add_library(lib2B ...) + + target_link_libraries(lib1A PUBLIC lib2A) + target_link_libraries(lib2B PUBLIC lib1B) + + add_library(lib ...) + target_link_libraries(lib3 PRIVATE "$<LINK_GROUP:feat,lib1A,lib1B>" + "$<LINK_GROUP:feat,lib2A,lib2B>") + + This example will be "re-written" by CMake in the following form: + + .. code-block:: cmake + + add_library(lib1A ...) + add_library(lib1B ...) + + add_library(lib2A ...) + add_library(lib2B ...) + + target_link_libraries(lib1A PUBLIC "$<LINK_GROUP:feat,lib2A,lib2B>") + target_link_libraries(lib2B PUBLIC "$<LINK_GROUP:feat,lib1A,lib1B>") + + add_library(lib ...) + target_link_libraries(lib3 PRIVATE "$<LINK_GROUP:feat,lib1A,lib1B>" + "$<LINK_GROUP:feat,lib2A,lib2B>") + + So, we have a circular dependency between groups ``{lib1A,lib1B}`` and + ``{lib2A,lib2B}``. + + CMake pre-defines some features of general interest: + + .. include:: ../variable/LINK_GROUP_PREDEFINED_FEATURES.txt .. genex:: $<INSTALL_INTERFACE:...> |