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
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
option() command removes a normal (non-cached) variable of the same name when:
-D<name>=ONon the command line).
In both of these cases (typically on the first run in a new build tree), the
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
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 name:
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.
This policy was introduced in CMake version 3.13. CMake version 3.19.0-rc3 warns when the policy is not set and uses
OLD behavior. Use the
cmake_policy() command to set it to
OLD behavior of a policy is
deprecated by definition and may be removed in a future version of CMake.
© 2000–2020 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.