Merge topic 'doc-rpath-features'

434be1256e Help: improve docs for INSTALL_NAME_DIR
f784c21567 Help: mention CMAKE_SKIP_RPATH in the RPATH docs
66ad61ba79 Help: improve documentation for BUILD_RPATH
25e7791dc1 Help: improve docs for INSTALL_RPATH
099292f123 Help: improve docs for rpath-related variables

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

5 files changed, 58 insertions, 11 deletions

diff --git a/Help/prop_tgt/BUILD_RPATH.rst b/Help/prop_tgt/BUILD_RPATH.rst
index 1f917a5..902e2f7 100644
--- a/Help/prop_tgt/BUILD_RPATH.rst
+++ b/Help/prop_tgt/BUILD_RPATH.rst
@@ -3,13 +3,34 @@ BUILD_RPATH
 
 .. versionadded:: 3.8
 
-A :ref:`semicolon-separated list <CMake Language Lists>` specifying runtime path (``RPATH``)
-entries to add to binaries linked in the build tree (for platforms that
-support it).  The entries will *not* be used for binaries in the install
-tree.  See also the :prop_tgt:`INSTALL_RPATH` target property.
+A :ref:`semicolon-separated list <CMake Language Lists>` specifying
+runtime path (``RPATH``) entries to add to binaries linked in the
+build tree (for platforms that support it).  By default, CMake sets
+the runtime path of binaries in the build tree to contain search
+paths it knows are needed to find the shared libraries they link.
+Projects may set ``BUILD_RPATH`` to specify additional search paths.
+
+The build-tree runtime path will *not* be used for binaries in the
+install tree.  It will be replaced with the install-tree runtime path
+during the installation step.  See also the :prop_tgt:`INSTALL_RPATH`
+target property.
 
 This property is initialized by the value of the variable
 :variable:`CMAKE_BUILD_RPATH` if it is set when a target is created.
 
 This property supports
 :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+Other settings that affect the build-tree runtime path include:
+
+* The :variable:`CMAKE_SKIP_RPATH` variable completely disables runtime
+  paths in both the build tree and install tree.
+
+* The :prop_tgt:`SKIP_BUILD_RPATH` target property disables setting any
+  runtime path in the build tree.
+
+* The :prop_tgt:`BUILD_RPATH_USE_ORIGIN` target property causes the
+  automatically-generated runtime path to use entries relative to ``$ORIGIN``.
+
+* The :prop_tgt:`BUILD_WITH_INSTALL_RPATH` target property causes binaries
+  in the build tree to be built with the install-tree runtime path.
diff --git a/Help/prop_tgt/INSTALL_NAME_DIR.rst b/Help/prop_tgt/INSTALL_NAME_DIR.rst
index 47a0037..84310b9 100644
--- a/Help/prop_tgt/INSTALL_NAME_DIR.rst
+++ b/Help/prop_tgt/INSTALL_NAME_DIR.rst
@@ -6,8 +6,9 @@ Directory name for installed targets on Apple platforms.
 ``INSTALL_NAME_DIR`` is a string specifying the directory portion of the
 "install_name" field of shared libraries on Apple platforms for
 installed targets.  When not set, the default directory used is determined
-by :prop_tgt:`MACOSX_RPATH`.  Policies :policy:`CMP0068` and :policy:`CMP0042`
-are also relevant.
+by :prop_tgt:`MACOSX_RPATH`.  If the :prop_tgt:`BUILD_WITH_INSTALL_NAME_DIR`
+property is set, this will be used already in the build tree.
+Policies :policy:`CMP0068` and :policy:`CMP0042` are also relevant.
 
 This property is initialized by the value of the variable
 :variable:`CMAKE_INSTALL_NAME_DIR` if it is set when a target is
@@ -16,3 +17,7 @@ created.
 This property supports :manual:`generator expressions <cmake-generator-expressions(7)>`.
 In particular, the :genex:`$<INSTALL_PREFIX>` generator expression can be
 used to set the directory relative to the install-time prefix.
+
+On platforms that support runtime paths (``RPATH``), refer to the
+:prop_tgt:`INSTALL_RPATH` target property.
+Under Windows, the :genex:`TARGET_RUNTIME_DLLS` generator expression is related.
diff --git a/Help/prop_tgt/INSTALL_RPATH.rst b/Help/prop_tgt/INSTALL_RPATH.rst
index 4549b92..e5110b8 100644
--- a/Help/prop_tgt/INSTALL_RPATH.rst
+++ b/Help/prop_tgt/INSTALL_RPATH.rst
@@ -3,10 +3,27 @@ INSTALL_RPATH
 
 The rpath to use for installed targets.
 
-A semicolon-separated list specifying the rpath to use in installed
+By default, the install rpath is empty. It can be set using this property,
+which is a semicolon-separated list specifying the rpath to use in installed
 targets (for platforms that support it).  This property is initialized
-by the value of the variable :variable:`CMAKE_INSTALL_RPATH` if it is set when
-a target is created.
+by the value of the variable :variable:`CMAKE_INSTALL_RPATH` if it is set
+when a target is created.
+Beside setting the install rpath manually, using the
+:prop_tgt:`INSTALL_RPATH_USE_LINK_PATH` target property it can also be
+generated automatically by CMake.
+
+Normally CMake uses the build tree for the RPATH when building executables
+etc on systems that use RPATH, see the :prop_tgt:`BUILD_RPATH` target
+property. When the software is installed
+the targets are edited (or relinked) by CMake (see
+:variable:`CMAKE_NO_BUILTIN_CHRPATH`) to have the install RPATH.
+This editing during installation can be avoided via
+the :prop_tgt:`BUILD_WITH_INSTALL_RPATH` target property.
+
+For handling toolchain-dependent RPATH entries the
+:prop_tgt:`INSTALL_REMOVE_ENVIRONMENT_RPATH` can be used.
+Runtime paths can be disabled completely via the :variable:`CMAKE_SKIP_RPATH`
+variable.
 
 Because the rpath may contain ``${ORIGIN}``, which coincides with CMake syntax,
 the contents of ``INSTALL_RPATH`` are properly escaped in the
@@ -14,3 +31,6 @@ the contents of ``INSTALL_RPATH`` are properly escaped in the
 
 This property supports
 :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+On Apple platforms, refer to the :prop_tgt:`INSTALL_NAME_DIR` target property.
+Under Windows, the :genex:`TARGET_RUNTIME_DLLS` generator expression is related.
diff --git a/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst
index d16a7a1..ef859cf 100644
--- a/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst
+++ b/Help/prop_tgt/INSTALL_RPATH_USE_LINK_PATH.rst
@@ -3,7 +3,7 @@ INSTALL_RPATH_USE_LINK_PATH
 
 Add paths to linker search and installed rpath.
 
-``INSTALL_RPATH_USE_LINK_PATH`` is a boolean that if set to ``True``
+``INSTALL_RPATH_USE_LINK_PATH`` is a boolean that if set to ``TRUE``
 will append to the runtime search path (rpath) of installed binaries
 any directories outside the project that are in the linker search path or
 contain linked library files.  The directories are appended after the
diff --git a/Help/prop_tgt/SKIP_BUILD_RPATH.rst b/Help/prop_tgt/SKIP_BUILD_RPATH.rst
index 7086b1b..1fe170c 100644
--- a/Help/prop_tgt/SKIP_BUILD_RPATH.rst
+++ b/Help/prop_tgt/SKIP_BUILD_RPATH.rst
@@ -4,6 +4,7 @@ SKIP_BUILD_RPATH
 Should rpaths be used for the build tree.
 
 ``SKIP_BUILD_RPATH`` is a boolean specifying whether to skip automatic
-generation of an rpath allowing the target to run from the build tree.
+generation of an rpath allowing the target to run from the build tree,
+see also the :prop_tgt:`BUILD_RPATH` target property.
 This property is initialized by the value of the variable
 :variable:`CMAKE_SKIP_BUILD_RPATH` if it is set when a target is created.