**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 in Apple environments**

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

* ``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