cmake: Allow CMAKE_INSTALL_PREFIX to be set by environment variable

Fixes: #25023

13 files changed, 73 insertions, 14 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
 
diff --git a/Modules/CMakeGenericSystem.cmake b/Modules/CMakeGenericSystem.cmake
index 77c1780..ccfde60 100644
--- a/Modules/CMakeGenericSystem.cmake
+++ b/Modules/CMakeGenericSystem.cmake
@@ -177,20 +177,27 @@ endfunction()
 # was initialized by the block below.  This is useful for user
 # projects to change the default prefix while still allowing the
 # command line to override it.
-if(NOT DEFINED CMAKE_INSTALL_PREFIX)
+if(NOT DEFINED CMAKE_INSTALL_PREFIX AND
+   NOT DEFINED ENV{CMAKE_INSTALL_PREFIX})
   set(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT 1)
 endif()
 
-# Choose a default install prefix for this platform.
-if(CMAKE_HOST_UNIX)
-  set(CMAKE_INSTALL_PREFIX "/usr/local"
+if(DEFINED ENV{CMAKE_INSTALL_PREFIX})
+  set(CMAKE_INSTALL_PREFIX "$ENV{CMAKE_INSTALL_PREFIX}"
     CACHE PATH "Install path prefix, prepended onto install directories.")
 else()
-  GetDefaultWindowsPrefixBase(CMAKE_GENERIC_PROGRAM_FILES)
-  set(CMAKE_INSTALL_PREFIX
-    "${CMAKE_GENERIC_PROGRAM_FILES}/${PROJECT_NAME}"
-    CACHE PATH "Install path prefix, prepended onto install directories.")
-  set(CMAKE_GENERIC_PROGRAM_FILES)
+  # If CMAKE_INSTALL_PREFIX env variable is not set,
+  # choose a default install prefix for this platform.
+  if(CMAKE_HOST_UNIX)
+    set(CMAKE_INSTALL_PREFIX "/usr/local"
+      CACHE PATH "Install path prefix, prepended onto install directories.")
+  else()
+    GetDefaultWindowsPrefixBase(CMAKE_GENERIC_PROGRAM_FILES)
+    set(CMAKE_INSTALL_PREFIX
+      "${CMAKE_GENERIC_PROGRAM_FILES}/${PROJECT_NAME}"
+      CACHE PATH "Install path prefix, prepended onto install directories.")
+    set(CMAKE_GENERIC_PROGRAM_FILES)
+  endif()
 endif()
 
 # Set a variable which will be used as component name in install() commands
diff --git a/Tests/RunCMake/CommandLine/EnvInstallPrefix-stdout.txt b/Tests/RunCMake/CommandLine/EnvInstallPrefix-stdout.txt
new file mode 100644
index 0000000..a0ca3d5
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/EnvInstallPrefix-stdout.txt
@@ -0,0 +1,3 @@
+-- ENV{CMAKE_INSTALL_PREFIX}='[^']*/Tests/RunCMake/CommandLine/install_prefix_set_via_env_var'
+-- CMAKE_INSTALL_PREFIX='[^']*/Tests/RunCMake/CommandLine/install_prefix_set_via_env_var'
+-- CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT=''
diff --git a/Tests/RunCMake/CommandLine/EnvInstallPrefix.cmake b/Tests/RunCMake/CommandLine/EnvInstallPrefix.cmake
new file mode 100644
index 0000000..24b1840
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/EnvInstallPrefix.cmake
@@ -0,0 +1,3 @@
+message(STATUS "ENV{CMAKE_INSTALL_PREFIX}='$ENV{CMAKE_INSTALL_PREFIX}'")
+message(STATUS "CMAKE_INSTALL_PREFIX='${CMAKE_INSTALL_PREFIX}'")
+message(STATUS "CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT='${CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT}'")
diff --git a/Tests/RunCMake/CommandLine/EnvInstallPrefixOverrideWithCmdLineOpt-stdout.txt b/Tests/RunCMake/CommandLine/EnvInstallPrefixOverrideWithCmdLineOpt-stdout.txt
new file mode 100644
index 0000000..b95e277
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/EnvInstallPrefixOverrideWithCmdLineOpt-stdout.txt
@@ -0,0 +1,3 @@
+-- ENV{CMAKE_INSTALL_PREFIX}='[^']*/Tests/RunCMake/CommandLine/install_prefix_set_via_env_var'
+-- CMAKE_INSTALL_PREFIX='[^']*/Tests/RunCMake/CommandLine/install_prefix_set_cmd_line_opt'
+-- CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT=''
diff --git a/Tests/RunCMake/CommandLine/EnvInstallPrefixOverrideWithCmdLineOpt.cmake b/Tests/RunCMake/CommandLine/EnvInstallPrefixOverrideWithCmdLineOpt.cmake
new file mode 100644
index 0000000..6de6be6
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/EnvInstallPrefixOverrideWithCmdLineOpt.cmake
@@ -0,0 +1 @@
+include(EnvInstallPrefix.cmake)
diff --git a/Tests/RunCMake/CommandLine/EnvInstallPrefixOverrideWithVar-stdout.txt b/Tests/RunCMake/CommandLine/EnvInstallPrefixOverrideWithVar-stdout.txt
new file mode 100644
index 0000000..3b7181d
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/EnvInstallPrefixOverrideWithVar-stdout.txt
@@ -0,0 +1,3 @@
+-- ENV{CMAKE_INSTALL_PREFIX}='[^']*/Tests/RunCMake/CommandLine/install_prefix_set_via_env_var'
+-- CMAKE_INSTALL_PREFIX='[^']*/Tests/RunCMake/CommandLine/install_prefix_set_via_var'
+-- CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT=''
diff --git a/Tests/RunCMake/CommandLine/EnvInstallPrefixOverrideWithVar.cmake b/Tests/RunCMake/CommandLine/EnvInstallPrefixOverrideWithVar.cmake
new file mode 100644
index 0000000..6de6be6
--- /dev/null
+++ b/Tests/RunCMake/CommandLine/EnvInstallPrefixOverrideWithVar.cmake
@@ -0,0 +1 @@
+include(EnvInstallPrefix.cmake)
diff --git a/Tests/RunCMake/CommandLine/RunCMakeTest.cmake b/Tests/RunCMake/CommandLine/RunCMakeTest.cmake
index 03b9301..7b34773 100644
--- a/Tests/RunCMake/CommandLine/RunCMakeTest.cmake
+++ b/Tests/RunCMake/CommandLine/RunCMakeTest.cmake
@@ -459,6 +459,15 @@ elseif(RunCMake_GENERATOR MATCHES "Ninja Multi-Config|Visual Studio|Xcode")
   run_EnvironmentConfigTypes()
 endif()
 
+function(run_EnvironmentInstallPrefix)
+  set(ENV{CMAKE_INSTALL_PREFIX} "${RunCMake_BINARY_DIR}/install_prefix_set_via_env_var")
+  run_cmake(EnvInstallPrefix)
+  run_cmake_with_options(EnvInstallPrefixOverrideWithVar -DCMAKE_INSTALL_PREFIX=${RunCMake_BINARY_DIR}/install_prefix_set_via_var)
+  run_cmake_with_options(EnvInstallPrefixOverrideWithCmdLineOpt --install-prefix ${RunCMake_BINARY_DIR}/install_prefix_set_cmd_line_opt)
+  unset(ENV{CMAKE_INSTALL_PREFIX})
+endfunction()
+run_EnvironmentInstallPrefix()
+
 function(run_EnvironmentToolchain)
   set(ENV{CMAKE_TOOLCHAIN_FILE} "${RunCMake_SOURCE_DIR}/EnvToolchain-toolchain.cmake")
   run_cmake(EnvToolchainAbsolute)