Merge topic 'doc-xcframeworks-stubs-apple' into release-3.28

e831eef933 Help: Note case where IMPORTED_IMPLIB isn't needed for (xc)frameworks
01735badee Help: XCFrameworks and stubs are supported on all Apple, not just macOS
6ac50df591 Help: Add missing versionadded directives for IMPORTED_IMPLIB

Acked-by: Kitware Robot <[email protected]>
Merge-request: !9058

Help/command/target_link_libraries.rst

@@ -68,9 +68,9 @@ Each ``<item>`` may be:
 
   .. versionadded:: 3.28
 
-    The library file may point to a ``.xcframework`` folder on macOS. If it
-    does, the target will get the selected library's ``Headers`` directory as
-    a usage requirement.
+    The library file may point to a ``.xcframework`` folder on Apple platforms.
+    If it does, the target will get the selected library's ``Headers``
+    directory as a usage requirement.
 
   .. versionadded:: 3.8
     On :ref:`Visual Studio Generators` for VS 2010 and above, library files

Help/prop_tgt/ENABLE_EXPORTS.rst

@@ -35,8 +35,8 @@ the property instead for backward compatibility reasons.
 See below for alternative initialization behavior for shared library targets.
 
 .. versionadded:: 3.27
-  On Apple platforms, to link with a shared library (either a bare library or a
-  framework), a linker import file can be used instead of the actual shared
+  To link with a shared library on macOS, or to a shared framework on any Apple
+  platform, a linker import file can be used instead of the actual shared
   library. These linker import files are also known as text-based stubs, and
   they have a ``.tbd`` file extension.
 

Help/prop_tgt/IMPORTED_IMPLIB.rst

@@ -6,17 +6,26 @@ Full path to the import library for an ``IMPORTED`` target.
 This property may be set:
 
 * On DLL platforms, to the location of the ``.lib`` part of the DLL.
-* On AIX, to an import file (e.g. ``.imp``) created for executables that export
-  symbols (see the :prop_tgt:`ENABLE_EXPORTS` target property).
-* On macOS, to an import file (e.g. ``.tbd``) created for shared libraries (see
-  the :prop_tgt:`ENABLE_EXPORTS` target property). For frameworks this is the
-  location of the ``.tbd`` file symlink just inside the framework folder.
+* .. versionadded:: 3.16
+    On AIX, to an import file (e.g. ``.imp``) created for executables that
+    export symbols (see the :prop_tgt:`ENABLE_EXPORTS` target property).
+* .. versionadded:: 3.27
+    On Apple platforms, to an import file (e.g. ``.tbd``) created for shared
+    libraries or frameworks (see the :prop_tgt:`ENABLE_EXPORTS` target
+    property).  For frameworks, this is the location of the ``.tbd`` file
+    symlink just inside the framework folder.
 * .. versionadded:: 3.28
     On non-DLL platforms, to the location of a shared library.
     When set without also specifying an :prop_tgt:`IMPORTED_LOCATION`,
     the library is considered to be a stub, and its location will not
     be added as a runtime search path to dependents that link it.
 
+.. versionchanged:: 3.28
+  If an imported target is an Apple framework or XCFramework, the preferred
+  arrangement is to set :prop_tgt:`IMPORTED_LOCATION` to the ``.framework``
+  or ``.xcframework`` directory.  CMake will then find the relevant ``.tbd``
+  file inside that framework or XCFramework automatically without requiring
+  ``IMPORTED_IMPLIB`` to be set.
 
 The ``IMPORTED_IMPLIB`` target property may be overridden for a
 given configuration ``<CONFIG>`` by the configuration-specific

Help/prop_tgt/IMPORTED_LOCATION.rst

@@ -17,14 +17,10 @@ non-imported targets.
 
 .. versionadded:: 3.28
 
-  For frameworks on macOS, this may be the location of the framework folder
-  itself.
-
-.. versionadded:: 3.28
-
-  This may be the location of a ``.xcframework`` folder on macOS. If it is,
-  any target that links against it will get the selected library's ``Headers``
-  directory as a usage requirement.
+  For ordinary frameworks on Apple platforms, this may be the location of the
+  ``.framework`` folder itself.  For XCFrameworks, it may be the location of
+  the ``.xcframework`` folder, in which case any target that links against it
+  will get the selected library's ``Headers`` directory as a usage requirement.
 
 The ``IMPORTED_LOCATION`` target property may be overridden for a
 given configuration ``<CONFIG>`` by the configuration-specific
@@ -38,5 +34,5 @@ selected and its :prop_tgt:`IMPORTED_LOCATION_<CONFIG>` value used.
 To get the location of an imported target read one of the :prop_tgt:`LOCATION`
 or ``LOCATION_<CONFIG>`` properties.
 
-For platforms with import libraries (e.g. Windows, AIX or macOS) see also
+For platforms with import libraries (e.g. Windows, AIX or Apple) see also
 :prop_tgt:`IMPORTED_IMPLIB`.