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

11 files changed, 86 insertions, 13 deletions

diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst
index a72eac1..8bb9dde 100644
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -1696,6 +1696,9 @@ In the following, the phrase "the ``tgt`` filename" means the name of the
     section for details.  Many :ref:`Find Modules` produce imported targets
     with the ``UNKNOWN`` type and therefore will be ignored.
 
+On platforms that support runtime paths (``RPATH``), refer to the
+:prop_tgt:`INSTALL_RPATH` target property.
+On Apple platforms, refer to the :prop_tgt:`INSTALL_NAME_DIR` target property.
 
 Export And Install Expressions
 ------------------------------
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.
diff --git a/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst b/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst
index 5b59a6e..839771a 100644
--- a/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst
+++ b/Help/variable/CMAKE_BUILD_WITH_INSTALL_RPATH.rst
@@ -9,3 +9,6 @@ installed the executables etc are relinked by CMake to have the
 install ``RPATH``.  If this variable is set to true then the software is
 always built with the install path for the ``RPATH`` and does not need to
 be relinked when installed.
+
+This is used to initialize the :prop_tgt:`BUILD_WITH_INSTALL_RPATH` target property
+for all targets.
diff --git a/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst b/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst
index b9b045e..483ec5f 100644
--- a/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst
+++ b/Help/variable/CMAKE_NO_BUILTIN_CHRPATH.rst
@@ -10,6 +10,9 @@ a builtin editor to change the runtime search path in the installed copy.
 If this variable is set to true then CMake will relink the binary before
 installation instead of using its builtin editor.
 
+For more information on RPATH handling see
+the :prop_tgt:`INSTALL_RPATH` and :prop_tgt:`BUILD_RPATH` target properties.
+
 .. versionadded:: 3.20
 
   This variable also applies to XCOFF binaries' LIBPATH.  Prior to the
diff --git a/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst b/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst
index 8da6100..dd3e2a0 100644
--- a/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst
+++ b/Help/variable/CMAKE_SKIP_BUILD_RPATH.rst
@@ -6,5 +6,13 @@ Do not include RPATHs in the build tree.
 Normally CMake uses the build tree for the RPATH when building
 executables etc on systems that use RPATH.  When the software is
 installed the executables etc are relinked by CMake to have the
-install RPATH.  If this variable is set to true then the software is
+install RPATH.  If this variable is set to ``TRUE`` then the software is
 always built with no RPATH.
+
+This is used to initialize the :prop_tgt:`SKIP_BUILD_RPATH` target property
+for all targets. For more information on RPATH handling see
+the :prop_tgt:`INSTALL_RPATH` and :prop_tgt:`BUILD_RPATH` target properties.
+
+See also the :variable:`CMAKE_SKIP_INSTALL_RPATH` variable.
+To omit RPATH in both the build and install steps, use
+:variable:`CMAKE_SKIP_RPATH` instead.
diff --git a/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst b/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst
index cc0ac21..465fdae 100644
--- a/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst
+++ b/Help/variable/CMAKE_SKIP_INSTALL_RPATH.rst
@@ -10,5 +10,10 @@ install RPATH.  If this variable is set to true then the software is
 always installed without RPATH, even if RPATH is enabled when
 building.  This can be useful for example to allow running tests from
 the build directory with RPATH enabled before the installation step.
+
+See also the :variable:`CMAKE_SKIP_BUILD_RPATH` variable.
 To omit RPATH in both the build and install steps, use
 :variable:`CMAKE_SKIP_RPATH` instead.
+
+For more information on RPATH handling see the :prop_tgt:`INSTALL_RPATH`
+and :prop_tgt:`BUILD_RPATH` target properties.
diff --git a/Help/variable/CMAKE_SKIP_RPATH.rst b/Help/variable/CMAKE_SKIP_RPATH.rst
index d7ce8e4..43f6401 100644
--- a/Help/variable/CMAKE_SKIP_RPATH.rst
+++ b/Help/variable/CMAKE_SKIP_RPATH.rst
@@ -7,4 +7,8 @@ If this is set to ``TRUE``, then the rpath information is not added to
 compiled executables.  The default is to add rpath information if the
 platform supports it.  This allows for easy running from the build
 tree.  To omit RPATH in the install step, but not the build step, use
-:variable:`CMAKE_SKIP_INSTALL_RPATH` instead.
+:variable:`CMAKE_SKIP_INSTALL_RPATH` instead. To omit RPATH in the build step,
+use :variable:`CMAKE_SKIP_BUILD_RPATH`.
+
+For more information on RPATH handling see the :prop_tgt:`INSTALL_RPATH`
+and :prop_tgt:`BUILD_RPATH` target properties.