cmake: Allow CMAKE_INSTALL_PREFIX to be set by environment variable

Fixes: #25023

5 files changed, 34 insertions, 5 deletions

diff --git a/Help/envvar/CMAKE_INSTALL_PREFIX.rst b/Help/envvar/CMAKE_INSTALL_PREFIX.rst
new file mode 100644
index 0000000..5c3e055
--- /dev/null
+++ b/Help/envvar/CMAKE_INSTALL_PREFIX.rst
@@ -0,0 +1,11 @@
+CMAKE_INSTALL_PREFIX
+--------------------
+
+.. versionadded:: 3.29
+
+.. include:: ENV_VAR.txt
+
+The ``CMAKE_INSTALL_PREFIX`` environment variable specifies a custom default
+value for the :variable:`CMAKE_INSTALL_PREFIX` variable in place of the
+default values specified by CMake itself. The value specified must be an
+absolute path to a directory.
diff --git a/Help/manual/cmake-env-variables.7.rst b/Help/manual/cmake-env-variables.7.rst
index 5272ab9..3ab5935 100644
--- a/Help/manual/cmake-env-variables.7.rst
+++ b/Help/manual/cmake-env-variables.7.rst
@@ -50,6 +50,7 @@ Environment Variables that Control the Build
    /envvar/CMAKE_GENERATOR_PLATFORM
    /envvar/CMAKE_GENERATOR_TOOLSET
    /envvar/CMAKE_INSTALL_MODE
+   /envvar/CMAKE_INSTALL_PREFIX
    /envvar/CMAKE_LANG_COMPILER_LAUNCHER
    /envvar/CMAKE_LANG_IMPLICIT_LINK_DIRECTORIES_EXCLUDE
    /envvar/CMAKE_LANG_LINKER_LAUNCHER
diff --git a/Help/release/dev/env-cmake-install-prefix.rst b/Help/release/dev/env-cmake-install-prefix.rst
new file mode 100644
index 0000000..db97855
--- /dev/null
+++ b/Help/release/dev/env-cmake-install-prefix.rst
@@ -0,0 +1,5 @@
+env-cmake-install-prefix
+------------------------
+
+* The :envvar:`CMAKE_INSTALL_PREFIX` environment variable was added to
+  provide a default value for the :variable:`CMAKE_BUILD_TYPE` variable.
diff --git a/Help/variable/CMAKE_INSTALL_PREFIX.rst b/Help/variable/CMAKE_INSTALL_PREFIX.rst
index c76727e..ce7cb8b 100644
--- a/Help/variable/CMAKE_INSTALL_PREFIX.rst
+++ b/Help/variable/CMAKE_INSTALL_PREFIX.rst
@@ -4,8 +4,19 @@ CMAKE_INSTALL_PREFIX
 Install directory used by :command:`install`.
 
 If ``make install`` is invoked or ``INSTALL`` is built, this directory is
-prepended onto all install directories.  This variable defaults to
-``/usr/local`` on UNIX and ``c:/Program Files/${PROJECT_NAME}`` on Windows.
+prepended onto all install directories.
+
+This variable defaults as follows:
+
+* .. versionadded:: 3.29
+
+    If the :envvar:`CMAKE_INSTALL_PREFIX` environment variable is set,
+    its value is used as default for this variable.
+
+* ``c:/Program Files/${PROJECT_NAME}`` on Windows.
+
+* ``/usr/local`` on UNIX platforms.
+
 See :variable:`CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT` for how a
 project might choose its own default.
 
diff --git a/Help/variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT.rst b/Help/variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT.rst
index 93cc319..316fea2 100644
--- a/Help/variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT.rst
+++ b/Help/variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT.rst
@@ -5,9 +5,10 @@ CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
 
 CMake sets this variable to a ``TRUE`` value when the
 :variable:`CMAKE_INSTALL_PREFIX` has just been initialized to
-its default value, typically on the first run of CMake within
-a new build tree.  This can be used by project code to change
-the default without overriding a user-provided value:
+its default value, typically on the first
+run of CMake within a new build tree and the :envvar:`CMAKE_INSTALL_PREFIX`
+environment variable is not set on the first run of CMake. This can be used
+by project code to change the default without overriding a user-provided value:
 
 .. code-block:: cmake