Help: Clarify policy CMP0077 documentation

Add background about the case in which the policy is relevant.
Describe the OLD and NEW behaviors more completely.

Fixes: #18418

1 files changed, 40 insertions, 4 deletions

diff --git a/Help/policy/CMP0077.rst b/Help/policy/CMP0077.rst
index 8efe198..44797b6 100644
--- a/Help/policy/CMP0077.rst
+++ b/Help/policy/CMP0077.rst
@@ -3,10 +3,46 @@ CMP0077
 
 :command:`option` honors normal variables.
 
-The ``OLD`` behavior for this policy is to clear any existing normal variables
-with the same name.  The ``NEW`` behavior for this policy is to not create
-a cache entry or modify any existing normal variables if a normal variable
-with the same name already exists.
+The :command:`option` command is typically used to create a cache entry
+to allow users to set the option.  However, there are cases in which a
+normal (non-cached) variable of the same name as the option may be
+defined by the project prior to calling the :command:`option` command.
+For example, a project that embeds another project as a subdirectory
+may want to hard-code options of the subproject to build the way it needs.
+
+For historical reasons in CMake 3.12 and below the :command:`option`
+command *removes* a normal (non-cached) variable of the same name when:
+
+* a cache entry of the specified name does not exist at all, or
+* a cache entry of the specified name exists but has not been given
+  a type (e.g. via ``-D<name>=ON`` on the command line).
+
+In both of these cases (typically on the first run in a new build tree),
+the :command:`option` command gives the cache entry type ``BOOL`` and
+removes any normal (non-cached) variable of the same name.  In the
+remaining case that the cache entry of the specified name already
+exists and has a type (typically on later runs in a build tree), the
+:command:`option` command changes nothing and any normal variable of
+the same name remains set.
+
+In CMake 3.13 and above the :command:`option` command prefers to
+do nothing when a normal variable of the given name already exists.
+It does not create or update a cache entry or remove the normal variable.
+The new behavior is consistent between the first and later runs in a
+build tree.  This policy provides compatibility with projects that have
+not been updated to expect the new behavior.
+
+When the :command:`option` command sees a normal variable of the given
+name:
+
+* The ``OLD`` behavior for this policy is to proceed even when a normal
+  variable of the same name exists.  If the cache entry does not already
+  exist and have a type then it is created and/or given a type and the
+  normal variable is removed.
+
+* The ``NEW`` behavior for this policy is to do nothing when a normal
+  variable of the same name exists.  The normal variable is not removed.
+  The cache entry is not created or updated and is ignored if it exists.
 
 This policy was introduced in CMake version 3.13.  CMake version
 |release| warns when the policy is not set and uses ``OLD`` behavior.