Merge topic 'install_name_policy'

1ba91291 Add policy CMP0068 separate install_name and RPATH settings on macOS
f7b9bf41 Apple: Add BUILD_WITH_INSTALL_NAME_DIR target property
4bff2d14 Apple: Refactor support for using INSTALL_NAME_DIR.
624fb9d7 Help: Format BUILD_WITH_INSTALL_RPATH documentation

8 files changed, 87 insertions, 7 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/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 38aba81..5fad10c 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -123,6 +123,7 @@ Properties on Targets
    /prop_tgt/AUTORCC_OPTIONS
    /prop_tgt/BINARY_DIR
    /prop_tgt/BUILD_RPATH
+   /prop_tgt/BUILD_WITH_INSTALL_NAME_DIR
    /prop_tgt/BUILD_WITH_INSTALL_RPATH
    /prop_tgt/BUNDLE_EXTENSION
    /prop_tgt/BUNDLE
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 38444d1..6112e65 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -263,6 +263,7 @@ Variables that Control the Build
    /variable/CMAKE_AUTOUIC
    /variable/CMAKE_AUTOUIC_OPTIONS
    /variable/CMAKE_BUILD_RPATH
+   /variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR
    /variable/CMAKE_BUILD_WITH_INSTALL_RPATH
    /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY
    /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY_CONFIG
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
new file mode 100644
index 0000000..bbb9a24
--- /dev/null
+++ b/Help/prop_tgt/BUILD_WITH_INSTALL_NAME_DIR.rst
@@ -0,0 +1,13 @@
+BUILD_WITH_INSTALL_NAME_DIR
+---------------------------
+
+``BUILD_WITH_INSTALL_NAME_DIR`` is a boolean specifying whether the macOS
+``install_name`` of a target in the build tree uses the directory given by
+:prop_tgt:`INSTALL_NAME_DIR`.  This setting only applies to targets on macOS.
+
+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 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 abcf28f..0244351 100644
--- a/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst
+++ b/Help/prop_tgt/BUILD_WITH_INSTALL_RPATH.rst
@@ -1,11 +1,15 @@
 BUILD_WITH_INSTALL_RPATH
 ------------------------
 
-Should build tree targets have install tree rpaths.
+``BUILD_WITH_INSTALL_RPATH`` is a boolean specifying whether to link the target
+in the build tree with the :prop_tgt:`INSTALL_RPATH`.  This takes precedence
+over :prop_tgt:`SKIP_BUILD_RPATH` and avoids the need for relinking before
+installation.
 
-BUILD_WITH_INSTALL_RPATH is a boolean specifying whether to link the
-target in the build tree with the INSTALL_RPATH.  This takes
-precedence over SKIP_BUILD_RPATH and avoids the need for relinking
-before installation.  This property is initialized by the value of the
-variable CMAKE_BUILD_WITH_INSTALL_RPATH if it is set when a target is
-created.
+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.
+
+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
new file mode 100644
index 0000000..7fe9a86
--- /dev/null
+++ b/Help/release/dev/install_name_policy.rst
@@ -0,0 +1,11 @@
+install_name_policy
+-------------------
+
+* A :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR` target property and corresponding
+  :variable:`CMAKE_BUILD_WITH_INSTALL_NAME_DIR` variable were added to
+  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`.
diff --git a/Help/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR.rst b/Help/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR.rst
new file mode 100644
index 0000000..30d5d3b
--- /dev/null
+++ b/Help/variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR.rst
@@ -0,0 +1,7 @@
+CMAKE_BUILD_WITH_INSTALL_NAME_DIR
+---------------------------------
+
+Whether to use :prop_tgt:`INSTALL_NAME_DIR` on targets in the build tree.
+
+This variable is used to initialize the :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR`
+property on all targets.