mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-10 07:40:03 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge topic 'doc-policies-3.21'

Browse Source 
7b5fa0f7b4 Help: Make policy CMP0126 wording more accurate
c4bc250f8c Help: Explain policy CMP0125 in more detail
6d5f74fcd7 Help: Clarify wording of CMP0124

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6360
This commit is contained in:
Brad King
2021-07-20 15:44:29 +00:00
committed by Kitware Robot
parent 4dcf90a94c 7b5fa0f7b4
commit c701cbdbd6
4 changed files with 52 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
Help/policy/CMP0077.rst
View File

@@ -46,6 +46,10 @@ name:
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.
See :policy:`CMP0126` for a similar policy for the :command:`set(CACHE)`
command, but note that there are some differences in ``NEW`` behavior
between the two policies.
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``

12
Help/policy/CMP0124.rst
View File

@@ -3,14 +3,12 @@ CMP0124
.. versionadded:: 3.21
The loop variables created by :command:`foreach` command have now their scope
restricted to the loop scope.
When this policy is set to ``NEW``, the scope of loop variables defined by the
:command:`foreach` command is restricted to the loop only. They will be unset
at the end of the loop.
Starting with CMake 3.21, the :command:`foreach` command ensures that the loop
variables have their scope restricted to the loop scope.
The ``OLD`` behavior for this policy let the loop variables to exist, with an
empty value, in the outer scope of loop scope.
The ``OLD`` behavior for this policy still clears the loop variables at the end
of the loop, but does not unset them. This leaves them as defined, but empty.
This policy was introduced in CMake version 3.21. Use the
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.

37
Help/policy/CMP0125.rst
View File

@@ -4,18 +4,35 @@ CMP0125
.. versionadded:: 3.21
The :command:`find_file`, :command:`find_path`, :command:`find_library` and
:command:`find_program` commands handle cache variables in the same way
regardless of whether they are defined on the command line, with or without a
type, or using the :command:`set` command.
:command:`find_program` commands cache their result in the variable specified
by their first argument. Prior to CMake 3.21, if a cache variable of that
name already existed before the call but the cache variable had no type, any
non-cache variable of the same name would be discarded and the cache variable
was always used (see also :policy:`CMP0126` for a different but similar
behavior). This contradicts the convention that a non-cache variable should
take precedence over a cache variable of the same name. Such a situation can
arise if a user sets a cache variable on the command line without specifying
a type, such as ``cmake -DMYVAR=blah ...`` instead of
``cmake -DMYVAR:FILEPATH=blah``.
Starting with CMake 3.21, the :command:`find_file`, :command:`find_path`,
:command:`find_library`, and :command:`find_program` commands ensure that the
cache variables will be used in the same way regardless how they were defined
and the result will be always successful if the searched artifact exists.
Related to the above, if a cache variable of the specified name already exists
and it *does* have a type, the various ``find_...()`` commands would return
that value unchanged. In particular, if it contained a relative path, it
would not be converted to an absolute path in this situation.
The ``OLD`` behavior for this policy is to have the find commands' behaviors
differ depending on how the cache variable is defined. The ``NEW`` behavior for
this policy is to have consistent behavior.
When policy ``CMP0125`` is set to ``OLD`` or is unset, the behavior is as
described above. When it is set to ``NEW``, the behavior is as follows:
* If a non-cache variable of the specified name exists when the ``find_...()``
command is called, its value will be used regardless of whether a cache
variable of the same name already exists or not. A cache variable will not
be created in this case if no such cache variable existed before.
If a cache variable of the specified name did already exist, the cache will
be updated to match the non-cache variable.
* The various ``find...()`` commands will always provide an absolute path in
the result variable, except where a relative path provided by a cache or
non-cache variable cannot be resolved to an existing path.
This policy was introduced in CMake version 3.21. Use the
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.

23
Help/policy/CMP0126.rst
View File

@@ -3,16 +3,25 @@ CMP0126
.. versionadded:: 3.21
The :command:`set(CACHE)` does not remove a normal variable of the same name.
When this policy is set to ``NEW``, the :command:`set(CACHE)` command does not
remove any normal variable of the same name from the current scope.
The ``OLD`` behavior removes any normal variable of the same name from the
current scope in the following situations:
Starting with CMake 3.21, the :command:`set(CACHE)` does not remove, in the
current scope, any normal variable with the same name.
* No cache variable of that name existed previously.
The ``OLD`` behavior for this policy is to have the :command:`set(CACHE)`
command removing the normal variable of the same name, if any. The ``NEW``
behavior for this policy is to keep the normal variable of the same name.
* A cache variable of that name existed previously, but it had no type.
This can occur when the variable was set on the command line using a form
like ``cmake -DMYVAR=blah`` instead of ``cmake -DMYVAR:STRING=blah``.
This policy was introduced in CMake version 3.21. Use the
Note that the ``NEW`` behavior has an important difference to the similar
``NEW`` behavior of policy :policy:`CMP0077`. The :command:`set(CACHE)`
command always sets the cache variable if it did not exist previously,
regardless of the ``CMP0126`` policy setting. The :command:`option` command
will *not* set the cache variable if a non-cache variable of the same name
already exists and :policy:`CMP0077` is set to ``NEW``.
Policy ``CMP0126`` was introduced in CMake version 3.21. Use the
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
Unlike many policies, CMake version |release| does *not* warn when the policy
is not set and simply uses ``OLD`` behavior. See documentation of the