Add policy CMP0068 separate install_name and RPATH settings on macOS

BUILD_WITH_INSTALL_RPATH, SKIP_BUILD_RPATH, CMAKE_SKIP_RPATH and
CMAKE_SKIP_INSTALL_RPATH no longer any effect on the install name
of a target on macOS.

Fixes: #16589

5 files changed, 51 insertions, 5 deletions

diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 3266958..0c9ee2d 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -51,6 +51,14 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
 to determine whether to report an error on use of deprecated macros or
 functions.
 
+Policies Introduced by CMake 3.9
+================================
+
+.. toctree::
+   :maxdepth: 1
+
+   CMP0068: RPATH settings on macOS do not affect install_name. </policy/CMP0068>
+
 Policies Introduced by CMake 3.8
 ================================
 
diff --git a/Help/policy/CMP0068.rst b/Help/policy/CMP0068.rst
new file mode 100644
index 0000000..978a6e3
--- /dev/null
+++ b/Help/policy/CMP0068.rst
@@ -0,0 +1,35 @@
+CMP0068
+-------
+
+``RPATH`` settings on macOS do not affect ``install_name``.
+
+CMake 3.9 and newer remove any effect the following settings may have on the
+``install_name`` of a target on macOS:
+
+* :prop_tgt:`BUILD_WITH_INSTALL_RPATH` target property
+* :prop_tgt:`SKIP_BUILD_RPATH` target property
+* :variable:`CMAKE_SKIP_RPATH` variable
+* :variable:`CMAKE_SKIP_INSTALL_RPATH` variable
+
+Previously, setting :prop_tgt:`BUILD_WITH_INSTALL_RPATH` had the effect of
+setting both the ``install_name`` of a target to :prop_tgt:`INSTALL_NAME_DIR`
+and the ``RPATH`` to :prop_tgt:`INSTALL_RPATH`.  In CMake 3.9, it only affects
+setting of ``RPATH``.  However, if one wants :prop_tgt:`INSTALL_NAME_DIR` to
+apply to the target in the build tree, one may set
+:prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR`.
+
+If :prop_tgt:`SKIP_BUILD_RPATH`, :variable:`CMAKE_SKIP_RPATH` or
+:variable:`CMAKE_SKIP_INSTALL_RPATH` were used to strip the directory portion
+of the ``install_name`` of a target, one may set ``INSTALL_NAME_DIR=""``
+instead.
+
+The ``OLD`` behavior of this policy is to use the ``RPATH`` settings for
+``install_name`` on macOS.  The ``NEW`` behavior of this policy is to ignore
+the ``RPATH`` settings for ``install_name`` on macOS.
+
+This policy was introduced in CMake version 3.9.  CMake version
+|release| warns when the policy is not set and uses ``OLD`` behavior.
+Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
+explicitly.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/prop_tgt/BUILD_WITH_INSTALL_NAME_DIR.rst b/Help/prop_tgt/BUILD_WITH_INSTALL_NAME_DIR.rst
index 7e02518..bbb9a24 100644
--- a/Help/prop_tgt/BUILD_WITH_INSTALL_NAME_DIR.rst
+++ b/Help/prop_tgt/BUILD_WITH_INSTALL_NAME_DIR.rst
@@ -9,5 +9,5 @@ This property is initialized by the value of the variable
 :variable:`CMAKE_BUILD_WITH_INSTALL_NAME_DIR` if it is set when a target is
 created.
 
-If this property is not set, the value of :prop_tgt:`BUILD_WITH_INSTALL_RPATH`
-is used in its place.
+If this property is not set and policy :policy:`CMP0068` is not ``NEW``, the
+value of :prop_tgt:`BUILD_WITH_INSTALL_RPATH` is used in its place.
diff --git a/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst b/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst
index 97c3736..0244351 100644
--- a/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst
+++ b/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst
@@ -10,6 +10,6 @@ This property is initialized by the value of the
 :variable:`CMAKE_BUILD_WITH_INSTALL_RPATH` variable if it is set when a target
 is created.
 
-This property also controls use of :prop_tgt:`INSTALL_NAME_DIR` in the build
-tree on macOS, but defers to the :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` target
-property if the latter is set.
+If policy :policy:`CMP0068` is not ``NEW``, this property also controls use of
+:prop_tgt:`INSTALL_NAME_DIR` in the build tree on macOS.  Either way, the
+:prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` target property takes precedence.
diff --git a/Help/release/dev/install_name_policy.rst b/Help/release/dev/install_name_policy.rst
index 71bdf35..7fe9a86 100644
--- a/Help/release/dev/install_name_policy.rst
+++ b/Help/release/dev/install_name_policy.rst
@@ -6,3 +6,6 @@ install_name_policy
   control whether to use the :prop_tgt:`INSTALL_NAME_DIR` target property
   value for binaries in the build tree.  This is for macOS ``install_name``
   as :prop_tgt:`BUILD_WITH_INSTALL_RPATH` is for ``RPATH``.
+
+* On macOS, ``RPATH`` settings such as :prop_tgt:`BUILD_WITH_INSTALL_RPATH`
+  no longer affect the ``install_name`` field.  See policy :policy:`CMP0068`.