mirror of
https://github.com/reactos/CMake.git
synced 2024-12-18 17:16:58 +00:00
53a391561e
Add background about the case in which the policy is relevant. Describe the OLD and NEW behaviors more completely. Fixes: #18418
53 lines
2.4 KiB
ReStructuredText
53 lines
2.4 KiB
ReStructuredText
CMP0077
|
|
-------
|
|
|
|
:command:`option` honors normal variables.
|
|
|
|
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.
|
|
Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
|
|
explicitly.
|
|
|
|
.. include:: DEPRECATED.txt
|