Introduce CMAKE_STAGING_PREFIX variable.

This variable can be useful in cross-compiling contexts where the
sysroot is read-only or where the sysroot should otherwise remain
pristine.

If the new CMAKE_STAGING_PREFIX variable is set, it is used instead
of CMAKE_INSTALL_PREFIX when generating the installation rules in
cmake_install.cmake.

This way, the CMAKE_INSTALL_PREFIX variable
always refers to the installation prefix on the target device, regardless
of whether host==target.

If any -rpath paths passed to the linker contain the CMAKE_STAGING_PREFIX,
the matching path fragments are replaced with the CMAKE_INSTALL_PREFIX.
Matching paths in the -rpath-link are not transformed.

The cross-prefix usr-move workaround is assumed not to require extension
regarding CMAKE_STAGING_PREFIX. The staging area is a single prefix, so
there is no scope for cross-prefix symlinks. The CMAKE_INSTALL_PREFIX
is still used to determine the workaround path, and that variable
remains the relevant one even if CMAKE_STAGING_PREFIX is used. If the
generated export files are deployed to the target, the workaround
will still be in place, and still be employed if required.

3 files changed, 20 insertions, 5 deletions

diff --git a/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst b/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst
index 91231b0..70d920b 100644
--- a/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst
+++ b/Help/variable/CMAKE_FIND_NO_INSTALL_PREFIX.rst
@@ -3,11 +3,13 @@ CMAKE_FIND_NO_INSTALL_PREFIX
 
 Ignore the :variable:`CMAKE_INSTALL_PREFIX` when searching for assets.
 
-CMake adds the :variable:`CMAKE_INSTALL_PREFIX` to the
+CMake adds the :variable:`CMAKE_INSTALL_PREFIX` and the
+:variable:`CMAKE_STAGING_PREFIX` variable to the
 :variable:`CMAKE_SYSTEM_PREFIX_PATH` by default. This variable may be set
 on the command line to control that behavior.
 
 Set :variable:`CMAKE_FIND_NO_INSTALL_PREFIX` to TRUE to tell find_package not
-to search in the :variable:`CMAKE_INSTALL_PREFIX` by default.  Note that the
+to search in the :variable:`CMAKE_INSTALL_PREFIX` or
+:variable:`CMAKE_STAGING_PREFIX` by default.  Note that the
 prefix may still be searched for other reasons, such as being the same prefix
 as the CMake installation, or for being a built-in system prefix.
diff --git a/Help/variable/CMAKE_STAGING_PREFIX.rst b/Help/variable/CMAKE_STAGING_PREFIX.rst
new file mode 100644
index 0000000..c4de7da
--- /dev/null
+++ b/Help/variable/CMAKE_STAGING_PREFIX.rst
@@ -0,0 +1,13 @@
+CMAKE_STAGING_PREFIX
+--------------------
+
+This variable may be set to a path to install to when cross-compiling. This can
+be useful if the path in :variable:`CMAKE_SYSROOT` is read-only, or otherwise
+should remain pristine.
+
+The CMAKE_STAGING_PREFIX location is also used as a search prefix by the ``find_*``
+commands. This can be controlled by setting the :variable:`CMAKE_FIND_NO_INSTALL_PREFIX`
+variable.
+
+If any RPATH/RUNPATH entries passed to the linker contain the CMAKE_STAGING_PREFIX,
+the matching path fragments are replaced with the :variable:`CMAKE_INSTALL_PREFIX`.
diff --git a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst
index 2dbae1f..537eaba 100644
--- a/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst
+++ b/Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst
@@ -9,8 +9,8 @@ appropriate subdirectories to the base directories.  So FIND_PROGRAM()
 adds /bin to each of the directories in the path, FIND_LIBRARY()
 appends /lib to each of the directories, and FIND_PATH() and
 FIND_FILE() append /include .  By default this contains the standard
-directories for the current system and the CMAKE_INSTALL_PREFIX.  It
-is NOT intended to be modified by the project, use CMAKE_PREFIX_PATH
-for this.  See also CMAKE_SYSTEM_INCLUDE_PATH,
+directories for the current system, the CMAKE_INSTALL_PREFIX and
+the :variable:`CMAKE_STAGING_PREFIX`.  It is NOT intended to be modified by
+the project, use CMAKE_PREFIX_PATH for this.  See also CMAKE_SYSTEM_INCLUDE_PATH,
 CMAKE_SYSTEM_LIBRARY_PATH, CMAKE_SYSTEM_PROGRAM_PATH, and
 CMAKE_SYSTEM_IGNORE_PATH.