Help/variable/CMAKE_LINK_LIBRARY_FEATURE_PROPERTIES.txt

Feature Properties Definition
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A feature properties definition is a
:ref:`semicolon-separated list <CMake Language Lists>` 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=<library_type-list>``
  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=<feature-list>``
  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_<LIBRARY>` 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 ``$<LINK_LIBRARY:WHOLE_ARCHIVE>`` 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 $<LINK_LIBRARY:WHOLE_ARCHIVE,A>)

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.