1CMP0125
2-------
3
4.. versionadded:: 3.21
5
6The :command:`find_file`, :command:`find_path`, :command:`find_library` and
7:command:`find_program` commands cache their result in the variable specified
8by their first argument.  Prior to CMake 3.21, if a cache variable of that
9name already existed before the call but the cache variable had no type, any
10non-cache variable of the same name would be discarded and the cache variable
11was always used (see also :policy:`CMP0126` for a different but similar
12behavior).  This contradicts the convention that a non-cache variable should
13take precedence over a cache variable of the same name.  Such a situation can
14arise if a user sets a cache variable on the command line without specifying
15a type, such as ``cmake -DMYVAR=blah ...`` instead of
16``cmake -DMYVAR:FILEPATH=blah``.
17
18Related to the above, if a cache variable of the specified name already exists
19and it *does* have a type, the various ``find_...()`` commands would return
20that value unchanged.  In particular, if it contained a relative path, it
21would not be converted to an absolute path in this situation.
22
23When policy ``CMP0125`` is set to ``OLD`` or is unset, the behavior is as
24described above.  When it is set to ``NEW``, the behavior is as follows:
25
26* If a non-cache variable of the specified name exists when the ``find_...()``
27  command is called, its value will be used regardless of whether a cache
28  variable of the same name already exists or not.  A cache variable will not
29  be created in this case if no such cache variable existed before.
30  If a cache variable of the specified name did already exist, the cache will
31  be updated to match the non-cache variable.
32
33* The various ``find...()`` commands will always provide an absolute path in
34  the result variable, except where a relative path provided by a cache or
35  non-cache variable cannot be resolved to an existing path.
36
37This policy was introduced in CMake version 3.21. Use the
38:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
39Unlike many policies, CMake version |release| does *not* warn when the policy
40is not set and simply uses ``OLD`` behavior.
41
42.. include:: DEPRECATED.txt
43