CMP0132: Don't set compiler environment variables on first run

When running CMake for the first time in a build tree, for some
generators CMake would set compiler environment variables
like CC, CXX, etc. when the corresponding language is enabled.
That behavior was never documented and can result in different
behavior between the first and subsequent runs. Add a policy
to no longer set those environment variables.

Fixes: #21378

1 files changed, 26 insertions, 0 deletions

diff --git a/Help/policy/CMP0132.rst b/Help/policy/CMP0132.rst
new file mode 100644
index 0000000000..fadbbdcda2
--- /dev/null
+++ b/Help/policy/CMP0132.rst
@@ -0,0 +1,26 @@
+CMP0132
+-------
+
+.. versionadded:: 3.24
+
+Apart from when using the Xcode generator and some Visual Studio generators,
+CMake 3.23 and below will set environment variables like :envvar:`CC`,
+:envvar:`CXX`, etc. when the corresponding language is enabled.
+This only occurs on the very first time CMake is run in a build directory,
+and the environment variables are only defined at configure time, not build
+time. On subsequent CMake runs, these environment variables are not set,
+opening up the opportunity for different behavior between the first and
+subsequent CMake runs. CMake 3.24 and above prefer to not set these
+environment variables when a language is enabled, even on the first run in
+a build directory.
+
+The ``OLD`` behavior for this policy sets the relevant environment variable
+on the first run when a language is enabled. The ``NEW`` behavior for this
+policy does not set any such environment variables.
+
+This policy was introduced in CMake version 3.24. Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+Unlike many policies, CMake version |release| does *not* warn
+when this policy is not set and simply uses ``OLD`` behavior.
+
+.. include:: DEPRECATED.txt