Merge topic 'xcode-link-phase-all'

525464ed2a Xcode: Use "Link Binary With Libraries" build phase in some cases
dc0898205c Xcode: Add special case for file type extension map for .xcassets
7b3d8411a2 Xcode: Refactor build setting append code and attribute getter naming

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

5 files changed, 70 insertions, 0 deletions

diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 644e87b..8efaf8d 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -396,6 +396,7 @@ Properties on Targets
    /prop_tgt/XCODE_ATTRIBUTE_an-attribute
    /prop_tgt/XCODE_EXPLICIT_FILE_TYPE
    /prop_tgt/XCODE_GENERATE_SCHEME
+   /prop_tgt/XCODE_LINK_BUILD_PHASE_MODE
    /prop_tgt/XCODE_PRODUCT_TYPE
    /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER
    /prop_tgt/XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 082e2d5..c076257 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -247,6 +247,7 @@ Variables that Change Behavior
    /variable/CMAKE_WARN_DEPRECATED
    /variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
    /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY
+   /variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE
    /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER
    /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER_USE_AFTER_RETURN
    /variable/CMAKE_XCODE_SCHEME_DEBUG_DOCUMENT_VERSIONING
diff --git a/Help/prop_tgt/XCODE_LINK_BUILD_PHASE_MODE.rst b/Help/prop_tgt/XCODE_LINK_BUILD_PHASE_MODE.rst
new file mode 100644
index 0000000..10cdedc
--- /dev/null
+++ b/Help/prop_tgt/XCODE_LINK_BUILD_PHASE_MODE.rst
@@ -0,0 +1,52 @@
+XCODE_LINK_BUILD_PHASE_MODE
+---------------------------
+
+When using the :generator:`Xcode` generator, libraries to be linked will be
+specified in the Xcode project file using either the "Link Binary With
+Libraries" build phase or directly as linker flags.  The former allows Xcode
+to manage build paths, which may be necessary when creating Xcode archives
+because it may use different build paths to a regular build.
+
+This property controls usage of "Link Binary With Libraries" build phase for
+a target that is an app bundle, executable, shared library, shared framework
+or a module library.
+
+Possible values are:
+
+* ``NONE``
+  The libraries will be linked by specifying the linker flags directly.
+
+* ``BUILT_ONLY``
+  The "Link Binary With Libraries" build phase will be used to link to another
+  target under the following conditions:
+
+  - The target to be linked to is a regular non-imported, non-interface library
+    target.
+  - The output directory of the target being built has not been changed from
+    its default (see :prop_tgt:`RUNTIME_OUTPUT_DIRECTORY` and
+    :prop_tgt:`LIBRARY_OUTPUT_DIRECTORY`).
+
+* ``KNOWN_LOCATION``
+  The "Link Binary With Libraries" build phase will be used to link to another
+  target under the same conditions as with ``BUILT_ONLY`` and also:
+  - Imported library targets except those of type ``UNKNOWN``.
+  - Any non-target library specified directly with a path.
+
+For all other cases, the libraries will be linked by specifying the linker
+flags directly.
+
+.. warning::
+  Libraries linked using "Link Binary With Libraries" are linked after the
+  ones linked through regular linker flags.  This order should be taken into
+  account when different static libraries contain symbols with the same name,
+  as the former ones will take precedence over the latter.
+
+.. warning::
+  If two or more directories contain libraries with identical file names and
+  some libraries are linked from those directories, the library search path
+  lookup will end up linking libraries from the first directory.  This is a
+  known limitation of Xcode.
+
+This property is initialized by the value of the
+:variable:`CMAKE_XCODE_LINK_BUILD_PHASE_MODE` variable if it is set when a
+target is created.
diff --git a/Help/release/dev/xcode-link-phase-all.rst b/Help/release/dev/xcode-link-phase-all.rst
new file mode 100644
index 0000000..a38f70c
--- /dev/null
+++ b/Help/release/dev/xcode-link-phase-all.rst
@@ -0,0 +1,9 @@
+xcode-link-phase-all
+--------------------
+
+* The Xcode generator gained support for linking libraries and frameworks
+  via the *Link Binaries With Libraries* build phase instead of always by
+  embedding linker flags directly.  This behavior is controlled by a new
+  :prop_tgt:`XCODE_LINK_BUILD_PHASE_MODE` target property, which is
+  initialized by a new :variable:`CMAKE_XCODE_LINK_BUILD_PHASE_MODE`
+  variable.
diff --git a/Help/variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE.rst b/Help/variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE.rst
new file mode 100644
index 0000000..ee4d37e
--- /dev/null
+++ b/Help/variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE.rst
@@ -0,0 +1,7 @@
+CMAKE_XCODE_LINK_BUILD_PHASE_MODE
+---------------------------------
+
+This variable is used to initialize the
+:prop_tgt:`XCODE_LINK_BUILD_PHASE_MODE` property on targets.
+It affects the methods that the :generator:`Xcode` generator uses to link
+different kinds of libraries.  Its default value is ``NONE``.