Merge topic 'cross-compiling-toolchain-variables'

7521da2 Introduce CMAKE_STAGING_PREFIX variable.

5 files changed, 26 insertions, 8 deletions

diff --git a/Help/command/FIND_XXX_ROOT.txt b/Help/command/FIND_XXX_ROOT.txt
index 7f80dcb..efc076f 100644
--- a/Help/command/FIND_XXX_ROOT.txt
+++ b/Help/command/FIND_XXX_ROOT.txt
@@ -1,7 +1,9 @@
 The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
 directories to be prepended to all other search directories.  This
-effectively "re-roots" the entire search under given locations.  By
-default it is empty.
+effectively "re-roots" the entire search under given locations.
+Paths which are descendants of the :variable:`CMAKE_STAGING_PREFIX` are excluded
+from this re-rooting, because that variable is always a path on the host system.
+By default the CMAKE_FIND_ROOT_PATH is empty.
 
 The :variable:`CMAKE_SYSROOT` variable can also be used to specify exactly one
 directory to use as a prefix.  Setting :variable:`CMAKE_SYSROOT` also has other
@@ -18,4 +20,4 @@ overridden on a per-call basis.  By using CMAKE_FIND_ROOT_PATH_BOTH
 the search order will be as described above.  If
 NO_CMAKE_FIND_ROOT_PATH is used then CMAKE_FIND_ROOT_PATH will not be
 used.  If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
-directories will be searched.
+directories and directories below :variable:`CMAKE_STAGING_PREFIX` will be searched.
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index dd82b40..a46539f 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -110,6 +110,7 @@ Variables that Change Behavior
    /variable/CMAKE_PREFIX_PATH
    /variable/CMAKE_PROGRAM_PATH
    /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY
+   /variable/CMAKE_STAGING_PREFIX
    /variable/CMAKE_SYSTEM_IGNORE_PATH
    /variable/CMAKE_SYSTEM_INCLUDE_PATH
    /variable/CMAKE_SYSTEM_LIBRARY_PATH
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.