New in version 3.13.
option() honors normal variables.
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
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 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>=ONon the command line).
In both of these cases (typically on the first run in a new build tree),
option() command gives the cache entry type
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
option() command changes nothing and any normal variable of
the same name remains set.
In CMake 3.13 and above the
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.
option() command sees a normal variable of the given
OLDbehavior 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.
NEWbehavior 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.
CMP0126 for a similar policy for the
command, but note that there are some differences in
between the two policies.
This policy was introduced in CMake version 3.13. CMake version
3.26.20230330-gbd69c12 warns when the policy is not set and uses
cmake_policy() command to set it to
explicitly within a project. Use the
CMAKE_POLICY_DEFAULT_CMP0077 variable to set the policy for
a third-party project in a subdirectory without modifying it.
OLD behavior of a policy is
deprecated by definition
and may be removed in a future version of CMake.