Merge topic 'LINK_LIBRARY-framework'

a2cfa2da4f GenEx/LINK_LIBRARY: Add features for framework support on Apple
40178f3c90 cmGlobalGenerator: Add helper to split framework path

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6967

2 files changed, 51 insertions, 0 deletions

diff --git a/Help/release/dev/Apple-link-framework.rst b/Help/release/dev/Apple-link-framework.rst
new file mode 100644
index 0000000..e194c15
--- /dev/null
+++ b/Help/release/dev/Apple-link-framework.rst
@@ -0,0 +1,11 @@
+Apple-link-framework
+--------------------
+
+* The :genex:`LINK_LIBRARY` generator expression gained the ability to link
+  frameworks in various ways when targeting ``Apple`` platforms. The following
+  new features were added:
+
+  * ``FRAMEWORK``
+  * ``NEEDED_FRAMEWORK``
+  * ``REEXPORT_FRAMEWORK``
+  * ``WEAK_FRAMEWORK``
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