RPATH: Add option for using $ORIGIN in build tree

This makes binaries independent of the build directory by not embedding
the build directory via RPATH.  The tests are partially based on the
existing RuntimePath test, but with the check moved into a POST_BUILD
command such that it can be skipped when the platform lacks support.

Fixes: #18413

5 files changed, 41 insertions, 0 deletions

diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 5c3eb81..1651114 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -138,6 +138,7 @@ Properties on Targets
    /prop_tgt/AUTORCC_OPTIONS
    /prop_tgt/BINARY_DIR
    /prop_tgt/BUILD_RPATH
+   /prop_tgt/BUILD_RPATH_USE_ORIGIN
    /prop_tgt/BUILD_WITH_INSTALL_NAME_DIR
    /prop_tgt/BUILD_WITH_INSTALL_RPATH
    /prop_tgt/BUNDLE_EXTENSION
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 9dd36ed..b88c661 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -322,6 +322,7 @@ Variables that Control the Build
    /variable/CMAKE_AUTOUIC_OPTIONS
    /variable/CMAKE_AUTOUIC_SEARCH_PATHS
    /variable/CMAKE_BUILD_RPATH
+   /variable/CMAKE_BUILD_RPATH_USE_ORIGIN
    /variable/CMAKE_BUILD_WITH_INSTALL_NAME_DIR
    /variable/CMAKE_BUILD_WITH_INSTALL_RPATH
    /variable/CMAKE_COMPILE_PDB_OUTPUT_DIRECTORY
diff --git a/Help/prop_tgt/BUILD_RPATH_USE_ORIGIN.rst b/Help/prop_tgt/BUILD_RPATH_USE_ORIGIN.rst
new file mode 100644
index 0000000..511de7a
--- /dev/null
+++ b/Help/prop_tgt/BUILD_RPATH_USE_ORIGIN.rst
@@ -0,0 +1,24 @@
+BUILD_RPATH_USE_ORIGIN
+----------------------
+
+Whether to use relative paths for the build ``RPATH``.
+
+This property is initialized by the value of the variable
+:variable:`CMAKE_BUILD_RPATH_USE_ORIGIN`.
+
+On platforms that support runtime paths (``RPATH``) with the
+``$ORIGIN`` token, setting this property to ``TRUE`` enables relative
+paths in the build ``RPATH`` for executables that point to shared
+libraries in the same build tree.
+
+Normally the build ``RPATH`` of an executable contains absolute paths
+to the directory of shared libraries. Directories contained within the
+build tree can be made relative to enable relocatable builds and to
+help achieving reproducible builds by omitting the build directory
+from the build environment.
+
+This property has no effect on platforms that do not support the
+``$ORIGIN`` token in ``RPATH``, or when the :variable:`CMAKE_SKIP_RPATH`
+variable is set. The runtime path set through the
+:prop_tgt:`BUILD_RPATH` target property is also unaffected by this
+property.
diff --git a/Help/release/dev/relative-rpath.rst b/Help/release/dev/relative-rpath.rst
new file mode 100644
index 0000000..5c62b10
--- /dev/null
+++ b/Help/release/dev/relative-rpath.rst
@@ -0,0 +1,8 @@
+relative-rpath
+--------------
+
+* A :variable:`CMAKE_BUILD_RPATH_USE_ORIGIN` variable and corresponding
+  :prop_tgt:`BUILD_RPATH_USE_ORIGIN` target property were added to
+  enable use of relative runtime paths (RPATHs). This helps achieving
+  relocatable and reproducible builds that are invariant of the build
+  directory.
diff --git a/Help/variable/CMAKE_BUILD_RPATH_USE_ORIGIN.rst b/Help/variable/CMAKE_BUILD_RPATH_USE_ORIGIN.rst
new file mode 100644
index 0000000..e34ede6
--- /dev/null
+++ b/Help/variable/CMAKE_BUILD_RPATH_USE_ORIGIN.rst
@@ -0,0 +1,7 @@
+CMAKE_BUILD_RPATH_USE_ORIGIN
+----------------------------
+
+Whether to use relative paths for the build ``RPATH``.
+
+This is used to initialize the :prop_tgt:`BUILD_RPATH_USE_ORIGIN` target
+property for all targets, see that property for more details.