Kitware/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-10-14 02:08:27 +08:00
Code Issues Projects Releases Wiki Activity

find_xxx: Clarify command description

Browse Source 
Also cleans up a missing infinitive in find_file

Fixes: #25844
This commit is contained in:
Vito Gamberini
2025-07-31 16:22:26 -04:00
parent 43a86ba605
commit cba75e669a
2 changed files with 25 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
Help/command/find_file.rst
View File

@@ -4,7 +4,7 @@ find_file
.. |FIND_XXX| replace:: find_file
.. |NAMES| replace:: NAMES name1 [name2 ...]
.. |SEARCH_XXX| replace:: full path to a file
.. |SEARCH_XXX_DESC| replace:: full path to named file
.. |SEARCH_XXX_DESC| replace:: full path to a named file
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
.. |entry_XXX_SUBDIR| replace:: ``<entry>/include``

31
Help/command/include/FIND_XXX.rst
View File

@@ -32,11 +32,27 @@ The general signature is:
)
This command is used to find a |SEARCH_XXX_DESC|.
A cache entry, or a normal variable if ``NO_CACHE`` is specified,
named by ``<VAR>`` is created to store the result of this command.
If the |SEARCH_XXX| is found the result is stored in the variable
and the search will not be repeated unless the variable is cleared.
If nothing is found, the result will be ``<VAR>-NOTFOUND``.
Prior to searching, |FIND_XXX| checks if variable ``<VAR>`` is defined. If
the variable is not defined, the search will be performed. If the variable is
defined and its value is ``NOTFOUND``, or ends in ``-NOTFOUND``, the search
will be performed. If the variable contains any other value the search is not
performed.
.. note::
``VAR`` is considered defined if it is available in the current scope. See
the :ref:`cmake-language(7) variables <CMake Language Variables>`
documentation for details on scopes, and the interaction of normal
variables and cache entries.
The results of the search will be stored in a cache entry named ``<VAR>``.
Future calls to |FIND_XXX| will inspect this cache entry when specifying the
same ``<VAR>``. This optimization ensures successful searches will not be
repeated unless the cache entry is :command:`unset`.
If the |SEARCH_XXX| is found the recorded value in cache entry ``<VAR>`` will
be the result of the search. If nothing is found, the recorded value will be
``<VAR>-NOTFOUND``.
Options include:
@@ -103,8 +119,9 @@ Options include:
.. note::
If the variable is already set before the call (as a normal or cache
variable) then the search will not occur.
|FIND_XXX| will still check for ``<VAR>`` as usual, checking first for a
variable, and then a cache entry. If either indicate a previous successful
search, the search will not be performed.
.. warning::