diff --git a/Help/variable/CMAKE_LANG_LINK_LIBRARY_FEATURE_PROPERTIES.rst b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FEATURE_PROPERTIES.rst index d8efd0fc14..10f4fdacac 100644 --- a/Help/variable/CMAKE_LANG_LINK_LIBRARY_FEATURE_PROPERTIES.rst +++ b/Help/variable/CMAKE_LANG_LINK_LIBRARY_FEATURE_PROPERTIES.rst @@ -3,10 +3,8 @@ CMAKE__LINK_LIBRARY__PROPERTIES .. versionadded:: 3.30 -This variable defines the semantics of the specified ```` for the -language ```` (as described by the -:variable:`CMAKE__LINK_LIBRARY_USING_` or -:variable:`CMAKE_LINK_LIBRARY_USING_` variables) used for the link -command generation. - -.. include:: CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.txt +This variable defines the semantics of the specified link library ```` +when linking with the link language ````. It takes precedence over +:variable:`CMAKE_LINK_LIBRARY__PROPERTIES` if that variable is also +defined for the same ````, but otherwise has similar effects. +See :variable:`CMAKE_LINK_LIBRARY__PROPERTIES` for further details. diff --git a/Help/variable/CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.rst b/Help/variable/CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.rst index 86b4e77191..e30c30a7fd 100644 --- a/Help/variable/CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.rst +++ b/Help/variable/CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.rst @@ -3,12 +3,113 @@ CMAKE_LINK_LIBRARY__PROPERTIES .. versionadded:: 3.30 -This variable defines the semantics of the specified ```` (as -described by the :variable:`CMAKE__LINK_LIBRARY_USING_` or -:variable:`CMAKE_LINK_LIBRARY_USING_` variables) used for the link -command generation. +This variable defines the behavior of the specified link library +````. It specifies how the ```` interacts with other +features, when the ```` should be applied, and aspects of how the +```` should be handled when CMake assembles the final linker +command line (e.g. de-duplication). -This variable will be considered only if the - :variable:`CMAKE__LINK_LIBRARY__PROPERTIES` is not defined. +The syntax of the linker flags for the ```` are controlled by the +:variable:`CMAKE__LINK_LIBRARY_USING_` and +:variable:`CMAKE_LINK_LIBRARY_USING_` variables. +The :variable:`CMAKE__LINK_LIBRARY_USING__SUPPORTED` and +:variable:`CMAKE_LINK_LIBRARY_USING__SUPPORTED` variables +control whether the ```` is available at all. -.. include:: CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.txt +When linking for a particular language ````, +``CMAKE_LINK_LIBRARY__PROPERTIES`` is ignored if the +:variable:`CMAKE__LINK_LIBRARY__PROPERTIES` variable is also +defined for the same ````. + +The value of ``CMAKE_LINK_LIBRARY__PROPERTIES`` and +:variable:`CMAKE__LINK_LIBRARY__PROPERTIES` at the end of the +directory scope in which a target is defined is what matters. + +Feature Properties Definition +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A feature properties definition is a +:ref:`semicolon-separated list ` of ``property=value(s)`` +items. If a property has multiple values, those values must be comma-separated. + +The following properties are supported: + +``LIBRARY_TYPE=`` + Specify the library types supported by the feature. Supported values are: + ``STATIC``, ``SHARED``, ``MODULE``, and ``EXECUTABLE``. + + If this property is not specified, the default is + ``LIBRARY_TYPE=STATIC,SHARED,MODULE,EXECUTABLE``. + + If the feature is used with an unsupported library type, CMake will emit a + developer warning and the feature will be ignored. + +``OVERRIDE=`` + Specify which features this one replaces in the event of a conflict. + This override mechanism is superseded by + :prop_tgt:`LINK_LIBRARY_OVERRIDE` or + :prop_tgt:`LINK_LIBRARY_OVERRIDE_` target property definitions, + if defined. + + If this property is not specified, the default is an empty list. + +``UNICITY=YES|NO|DEFAULT`` + Specify the de-duplication strategy for a library using this feature. + + ``YES`` + The library is always de-duplicated. The default strategy CMake would + normally apply is ignored. + + ``NO`` + The library is never de-duplicated. The default strategy CMake would + normally apply is ignored. + + ``DEFAULT`` + Let CMake determine a de-duplication strategy automatically. + + If this property is not specified, ``DEFAULT`` will be used. + +Example +^^^^^^^ + +A common need is the loading of a full archive as part of the creation of a +shared library. The built-in ``WHOLE_ARCHIVE`` feature can be used for that +purpose. The implementation of that built-in feature sets the following +link library feature properties: + +.. code-block:: cmake + + set(CMAKE_LINK_LIBRARY_WHOLE_ARCHIVE_PROPERTIES + LIBRARY_TYPE=STATIC + OVERRIDE=DEFAULT + UNICITY=YES + ) + +``LIBRARY_TYPE=STATIC`` + This feature is only meaningful for static libraries. +``OVERRIDE=DEFAULT`` + The ``DEFAULT`` feature will be overridden by the ``WHOLE_ARCHIVE`` feature + because they are compatible and enhance the user's experience: standard + library specification and ``$`` can be used + freely. +``UNICITY=YES`` + When this feature is used, the linker loads all symbols from the static + library, so there is no need to repeat the library on the linker + command line. + +The ``WHOLE_ARCHIVE`` feature can be used like so: + +.. code-block:: cmake + + add_library(A STATIC ...) + add_library(B STATIC ...) + + target_link_libraries(B PUBLIC A) + target_link_libraries(A PUBLIC B) + + add_library(global SHARED ...) + target_link_libraries(global PRIVATE $) + +The resulting link command will only have one instance of the ``A`` library +specified, and the linker flags will ensure that all symbols are loaded from +the ``A`` library. diff --git a/Help/variable/CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.txt b/Help/variable/CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.txt deleted file mode 100644 index 202a7ec0f6..0000000000 --- a/Help/variable/CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.txt +++ /dev/null @@ -1,87 +0,0 @@ -Feature Properties Definition -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -A feature properties definition is a -:ref:`semicolon-separated list ` of ``property=value(s)`` -items. In the case of multiple values can be specified, they are separated by -a comma. - -The following properties are supported: - -``LIBRARY_TYPE=`` - Specify which library types are supported by this feature. The possible - values are: ``STATIC``, ``SHARED``, ``MODULE`` or ``EXECUTABLE``. - - If this property is not specified, the default is - ``LIBRARY_TYPE=STATIC,SHARED,MODULE,EXECUTABLE``. - - If the feature is used with an unsupported library type, CMake will emit a - developer warning and the feature will be ignored. - -``OVERRIDE=`` - Specify which features will be replaced by this one in the event of a - conflict. This override mechanism is superseded by any - :prop_tgt:`LINK_LIBRARY_OVERRIDE` or - :prop_tgt:`LINK_LIBRARY_OVERRIDE_` target properties definitions. - - If this property is not specified, the default is an empty list. - -``UNICITY=YES|NO|DEFAULT`` - Manage the strategy of de-duplication for the libraries using this feature. - - ``YES`` - Libraries are de-duplicated regardless the default strategy applied by - CMake. - - ``NO`` - Libraries are not de-duplicated regardless the default strategy applied - by CMake. - - ``DEFAULT`` - Apply the default CMake strategy. - - If this property is not specified, ``DEFAULT`` will be used. - -Example -^^^^^^^ - -A common need is the loading of a full archive as part of the creation of a -shared library or an executable. For that purpose, the ``WHOLE_ARCHIVE`` -feature can be used. - -Currently, the associated properties with this feature are defined as follows: - -.. code-block:: cmake - - set(CMAKE_LINK_LIBRARY_WHOLE_ARCHIVE_PROPERTIES LIBRARY_TYPE=STATIC - OVERRIDE=DEFAULT - UNICITY=YES) - -``LIBRARY_TYPE=STATIC`` - Obviously, this feature is only meaningful for static libraries. -``OVERRIDE=DEFAULT`` - The ``DEFAULT`` feature will be overridden by the ``WHOLE_ARCHIVE`` feature - because they are compatible and enhance the user's experience: standard - library specification and ``$`` can be used - freely. -``UNICITY=YES`` - When this feature is used, all symbols from the static library are loaded - by the linker, so there is no need to duplicate the library on the link - command. - -A typical usage of the ``WHOLE_ARCHIVE`` can be: - -.. code-block:: cmake - - add_library(A STATIC ...) - add_library(B STATIC ...) - - target_link_libraries(B PUBLIC A) - target_link_libraries(A PUBLIC B) - - add_library(global SHARED ...) - target_link_libraries(global PRIVATE $) - -The resulting link command will only have one iteration of the ``A`` library -specified with the needed linker flags to ensure the load of all the symbols -of the library. diff --git a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt index 0359f587f0..59a0d02552 100644 --- a/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt +++ b/Help/variable/CMAKE_LINK_LIBRARY_USING_FEATURE.txt @@ -2,8 +2,8 @@ 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 (see `Predefined Features`_ further below). -The feature behavior can be described using the -:variable:`CMAKE__LINK_LIBRARY__PROPERTIES` or +Some aspects of feature behavior can be defined by the +:variable:`CMAKE__LINK_LIBRARY__PROPERTIES` and :variable:`CMAKE_LINK_LIBRARY__PROPERTIES` variables. Feature Definitions