mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-01-11 08:20:18 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Explain policy CMP0125 in more detail

Browse Source
This commit is contained in:
Craig Scott
2021-07-17 12:08:52 +10:00
parent 6d5f74fcd7
commit c4bc250f8c
1 changed files with 27 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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.