GenEx/LINK_LIBRARY: Add features for framework support on Apple

1 files changed, 40 insertions, 0 deletions

diff --git a/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt
index dd22e14..d4fdf76 100644
--- a/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt
+++ b/Help/variable/LINK_LIBRARY_PREDEFINED_FEATURES.txt
@@ -3,3 +3,43 @@
 * ``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 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