mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2026-05-01 20:00:51 -05: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
Help/policy/CMP0125.rst
+27 -10
View File
@@ -4,18 +4,35 @@ CMP0125
.. versionadded:: 3.21 .. versionadded:: 3.21
The :command:`find_file`, :command:`find_path`, :command:`find_library` and The :command:`find_file`, :command:`find_path`, :command:`find_library` and
:command:`find_program` commands handle cache variables in the same way :command:`find_program` commands cache their result in the variable specified
regardless of whether they are defined on the command line, with or without a by their first argument. Prior to CMake 3.21, if a cache variable of that
type, or using the :command:`set` command. 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`, Related to the above, if a cache variable of the specified name already exists
:command:`find_library`, and :command:`find_program` commands ensure that the and it *does* have a type, the various ``find_...()`` commands would return
cache variables will be used in the same way regardless how they were defined that value unchanged. In particular, if it contained a relative path, it
and the result will be always successful if the searched artifact exists. would not be converted to an absolute path in this situation.
The ``OLD`` behavior for this policy is to have the find commands' behaviors When policy ``CMP0125`` is set to ``OLD`` or is unset, the behavior is as
differ depending on how the cache variable is defined. The ``NEW`` behavior for described above. When it is set to ``NEW``, the behavior is as follows:
this policy is to have consistent behavior.
* 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 This policy was introduced in CMake version 3.21. Use the
:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.