Merge topic 'Apple-handle-Text-Stubs'

ede33f30cf Apple: Handle generation and comsuption of text-based stubs (.tbd files)
fcbd723a50 Enhance support functions

Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: Brad King <brad.king@kitware.com>
Merge-request: !8204

6 files changed, 56 insertions, 7 deletions

diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst
index 677e06d..abb627c 100644
--- a/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst
+++ b/Help/prop_tgt/ARCHIVE_OUTPUT_DIRECTORY.rst
@@ -6,4 +6,7 @@ ARCHIVE_OUTPUT_DIRECTORY
 .. |CMAKE_XXX_OUTPUT_DIRECTORY| replace:: :variable:`CMAKE_ARCHIVE_OUTPUT_DIRECTORY`
 .. include:: XXX_OUTPUT_DIRECTORY.txt
 
+.. |IDEM| replace:: in the same directory
+.. include:: MACOS_IMPORT_FILES.txt
+
 See also the :prop_tgt:`ARCHIVE_OUTPUT_DIRECTORY_<CONFIG>` target property.
diff --git a/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst
index 6150193..1f1c467 100644
--- a/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst
+++ b/Help/prop_tgt/ARCHIVE_OUTPUT_NAME.rst
@@ -5,4 +5,7 @@ ARCHIVE_OUTPUT_NAME
 .. |xxx| replace:: archive
 .. include:: XXX_OUTPUT_NAME.txt
 
+.. |IDEM| replace:: with the same name
+.. include:: MACOS_IMPORT_FILES.txt
+
 See also the :prop_tgt:`ARCHIVE_OUTPUT_NAME_<CONFIG>` target property.
diff --git a/Help/prop_tgt/ENABLE_EXPORTS.rst b/Help/prop_tgt/ENABLE_EXPORTS.rst
index 0b1064a..3e9b285 100644
--- a/Help/prop_tgt/ENABLE_EXPORTS.rst
+++ b/Help/prop_tgt/ENABLE_EXPORTS.rst
@@ -1,7 +1,7 @@
 ENABLE_EXPORTS
 --------------
 
-Specify whether an executable exports symbols for loadable modules.
+Specify whether an executable or a shared library exports symbols.
 
 Normally an executable does not export any symbols because it is the
 final program.  It is possible for an executable to export symbols to
@@ -28,4 +28,29 @@ varies by platform:
   automatically bind symbols when the module is loaded.
 
 This property is initialized by the value of the variable
-:variable:`CMAKE_ENABLE_EXPORTS` if it is set when a target is created.
+:variable:`CMAKE_EXECUTABLE_ENABLE_EXPORTS` if it is set when an executable
+target is created.
+
+.. versionadded:: 3.27
+  On macOS, to link with a shared library (standard one as well as framework),
+  a linker import file (e.g. a text-based stubs file, with ``.tbd`` extension)
+  can be used instead of the shared library itself.
+
+The generation of these linker import files, as well as the consumption, is
+controlled by this property. When this property is set to true, CMake will
+generate a ``.tbd`` file for each shared library created by
+:command:`add_library` command. This allow other targets to use this ``.tbd``
+file to link to the library with the :command:`target_link_libraries`
+command.
+
+.. note::
+
+  For compatibility purpose, this property will be ignored if
+  :prop_tgt:`XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS <XCODE_ATTRIBUTE_<an-attribute>>`
+  target property or the
+  :variable:`CMAKE_XCODE_ATTRIBUTE_GENERATE_TEXT_BASED_STUBS <CMAKE_XCODE_ATTRIBUTE_<an-attribute>>`
+  variable is set to ``NO``.
+
+This property is initialized by the value of the variable
+:variable:`CMAKE_SHARED_LIBRARY_ENABLE_EXPORTS` if it is set when a shared
+library target is created.
diff --git a/Help/prop_tgt/IMPORTED_IMPLIB.rst b/Help/prop_tgt/IMPORTED_IMPLIB.rst
index c8b6fde..77549f3 100644
--- a/Help/prop_tgt/IMPORTED_IMPLIB.rst
+++ b/Help/prop_tgt/IMPORTED_IMPLIB.rst
@@ -3,7 +3,13 @@ IMPORTED_IMPLIB
 
 Full path to the import library for an ``IMPORTED`` target.
 
-Set this to the location of the ``.lib`` part of a Windows DLL, or on
-AIX set it to an import file created for executables that export symbols
-(see the :prop_tgt:`ENABLE_EXPORTS` target property).
-Ignored for non-imported targets.
+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.
+
+This property is ignored for non-imported targets.
diff --git a/Help/prop_tgt/IMPORTED_LOCATION.rst b/Help/prop_tgt/IMPORTED_LOCATION.rst
index ddd910a..a7207d8 100644
--- a/Help/prop_tgt/IMPORTED_LOCATION.rst
+++ b/Help/prop_tgt/IMPORTED_LOCATION.rst
@@ -27,5 +27,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) see also
+For platforms with import libraries (e.g. Windows, AIX or macOS) see also
 :prop_tgt:`IMPORTED_IMPLIB`.
diff --git a/Help/prop_tgt/MACOS_IMPORT_FILES.txt b/Help/prop_tgt/MACOS_IMPORT_FILES.txt
new file mode 100644
index 0000000..3c98fc8
--- /dev/null
+++ b/Help/prop_tgt/MACOS_IMPORT_FILES.txt
@@ -0,0 +1,12 @@
+.. note::
+
+  On macOS, this property will be ignored for the linker import files (e.g.
+  ``.tbd`` files, see :prop_tgt:`ENABLE_EXPORTS` property for details) when:
+
+  * The :prop_tgt:`FRAMEWORK` is set, because the framework layout cannot be
+    changed.
+  * The :generator:`Xcode` generator is used, due to the limitations and
+    constraints of the ``Xcode`` tool.
+
+  In both cases, the linker import files will be generated |IDEM| as the shared
+  library.