1CMP0126
2-------
3
4.. versionadded:: 3.21
5
6When this policy is set to ``NEW``, the :command:`set(CACHE)` command does not
7remove any normal variable of the same name from the current scope.
8The ``OLD`` behavior removes any normal variable of the same name from the
9current scope in the following situations:
10
11* No cache variable of that name existed previously.
12
13* A cache variable of that name existed previously, but it had no type.
14  This can occur when the variable was set on the command line using a form
15  like ``cmake -DMYVAR=blah`` instead of ``cmake -DMYVAR:STRING=blah``.
16
17Note that the ``NEW`` behavior has an important difference to the similar
18``NEW`` behavior of policy :policy:`CMP0077`.  The :command:`set(CACHE)`
19command always sets the cache variable if it did not exist previously,
20regardless of the ``CMP0126`` policy setting.  The :command:`option` command
21will *not* set the cache variable if a non-cache variable of the same name
22already exists and :policy:`CMP0077` is set to ``NEW``.
23
24Policy ``CMP0126`` was introduced in CMake version 3.21. Use the
25:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly
26within a project.  Use the :variable:`CMAKE_POLICY_DEFAULT_CMP0126
27<CMAKE_POLICY_DEFAULT_CMP\<NNNN\>>` variable to set the policy for
28a third-party project in a subdirectory without modifying it.
29Unlike many policies, CMake version |release| does *not* warn when the policy
30is not set and simply uses ``OLD`` behavior.  See documentation of the
31:variable:`CMAKE_POLICY_WARNING_CMP0126 <CMAKE_POLICY_WARNING_CMP<NNNN>>`
32variable to control the warning.
33
34.. include:: DEPRECATED.txt
35