**Features available in all environments**

``DEFAULT``
  This feature enables default link expression. This is mainly
  useful with :prop_tgt:`LINK_LIBRARY_OVERRIDE` and
  :prop_tgt:`LINK_LIBRARY_OVERRIDE_<LIBRARY>` target properties.

**Features available for a subset of environments**

``WHOLE_ARCHIVE``
  Force load of all members in a static library.

  Target platforms supported: all ``Apple`` variants, ``Linux``, all ``BSD``
  variants, ``SunOS``, ``Windows``, ``CYGWIN``, and ``MSYS``.

  Platform-specific notes:

  * On Apple platforms, the library must be specified as a CMake target name, a
    library file name (such as ``libfoo.a``), or a library file path (such as
    ``/path/to/libfoo.a``).  It cannot be specified as a plain library name
    (such as ``foo``, where ``foo`` is not CMake target), due to a limitation
    in the Apple linker.
  * On Windows platforms, for ``MSVC`` or MSVC-like toolchains, the version
    must be greater than ``1900``.

**Features available in Apple environments**

It is assumed that the linker used is the one provided by `XCode` or is
compatible with it.

Framework support

``FRAMEWORK``
  This option tells the linker to search for the specified
  framework (use linker option ``-framework``).
``NEEDED_FRAMEWORK``
  This is the same as the ``FRAMEWORK`` feature but means
  to really link with the framework even if no symbols are used from it (use
  linker option ``-needed_framework``).
``REEXPORT_FRAMEWORK``
  This is the same as the ``FRAMEWORK`` feature but
  also specifies that all symbols in that framework should be available to
  clients linking to the library being created (use linker option
  ``-reexport_framework``).
``WEAK_FRAMEWORK``
  This is the same as the ``FRAMEWORK`` feature but forces
  the framework and all references to it to be marked as weak imports (use
  linker option ``-weak_framework``).

Features for framework linking have a special handling in CMake: the
framework can be specified as a CMake framework target or file path. In the
first case, the target must have the :prop_tgt:`FRAMEWORK` target property set
as ``TRUE`` to enable framework handling. In the later case, if the path
includes a directory part, this one will be specified as framework search path
at link step.

.. code-block:: cmake

  add_library(lib SHARED ...)
  target_link_libraries(lib PRIVATE "$<LINK_LIBRARY:NEEDED_FRAMEWORK,/path/to/my_framework>")

  # at link step we will have:
  # -F/path/to -needed_framework my_framework

.. note::

   The expected formats for the file path, with optional parts specified as
   ``()?``, are:

   * (/path/to/)?FwName(.framework)?
   * (/path/to/)?FwName.framework/FwName
   * (/path/to/)?FwName.framework/Versions/\*/FwName

Library support

``NEEDED_LIBRARY``
  This is the same as specifying a link item (target or
  library) but means to really link with the item even if no symbols are used
  from it (use linker option ``-needed_library`` or ``-needed-l``).
``REEXPORT_LIBRARY``
  This is the same as specifying a link item (target or
  library) but also specifies that all symbols in that item should be available
  to clients linking to the library being created (use linker option
  ``-reexport_library`` or ``-reexport-l``).
``WEAK_LIBRARY``
  This is the same as specifying a link item (target or
  library) but forces the item and all references to it to be marked as weak
  imports (use linker option ``-weak_library`` or ``-weak-l``).