1CMP0077
2-------
3
4.. versionadded:: 3.13
5
6:command:`option` honors normal variables.
7
8The :command:`option` command is typically used to create a cache entry
9to allow users to set the option.  However, there are cases in which a
10normal (non-cached) variable of the same name as the option may be
11defined by the project prior to calling the :command:`option` command.
12For example, a project that embeds another project as a subdirectory
13may want to hard-code options of the subproject to build the way it needs.
14
15For historical reasons in CMake 3.12 and below the :command:`option`
16command *removes* a normal (non-cached) variable of the same name when:
17
18* a cache entry of the specified name does not exist at all, or
19* a cache entry of the specified name exists but has not been given
20  a type (e.g. via ``-D<name>=ON`` on the command line).
21
22In both of these cases (typically on the first run in a new build tree),
23the :command:`option` command gives the cache entry type ``BOOL`` and
24removes any normal (non-cached) variable of the same name.  In the
25remaining case that the cache entry of the specified name already
26exists and has a type (typically on later runs in a build tree), the
27:command:`option` command changes nothing and any normal variable of
28the same name remains set.
29
30In CMake 3.13 and above the :command:`option` command prefers to
31do nothing when a normal variable of the given name already exists.
32It does not create or update a cache entry or remove the normal variable.
33The new behavior is consistent between the first and later runs in a
34build tree.  This policy provides compatibility with projects that have
35not been updated to expect the new behavior.
36
37When the :command:`option` command sees a normal variable of the given
38name:
39
40* The ``OLD`` behavior for this policy is to proceed even when a normal
41  variable of the same name exists.  If the cache entry does not already
42  exist and have a type then it is created and/or given a type and the
43  normal variable is removed.
44
45* The ``NEW`` behavior for this policy is to do nothing when a normal
46  variable of the same name exists.  The normal variable is not removed.
47  The cache entry is not created or updated and is ignored if it exists.
48
49See :policy:`CMP0126` for a similar policy for the :command:`set(CACHE)`
50command, but note that there are some differences in ``NEW`` behavior
51between the two policies.
52
53This policy was introduced in CMake version 3.13.  CMake version
54|release| warns when the policy is not set and uses ``OLD`` behavior.
55Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
56explicitly within a project.  Use the :variable:`CMAKE_POLICY_DEFAULT_CMP0077
57<CMAKE_POLICY_DEFAULT_CMP\<NNNN\>>` variable to set the policy for
58a third-party project in a subdirectory without modifying it.
59
60.. include:: DEPRECATED.txt
61