1A short-hand signature is:
2
3.. parsed-literal::
4
5   |FIND_XXX| (<VAR> name1 [path1 path2 ...])
6
7The general signature is:
8
9.. parsed-literal::
10
11   |FIND_XXX| (
12             <VAR>
13             name | |NAMES|
14             [HINTS [path | ENV var]... ]
15             [PATHS [path | ENV var]... ]
16             [PATH_SUFFIXES suffix1 [suffix2 ...]]
17             [DOC "cache documentation string"]
18             [NO_CACHE]
19             [REQUIRED]
20             [NO_DEFAULT_PATH]
21             [NO_PACKAGE_ROOT_PATH]
22             [NO_CMAKE_PATH]
23             [NO_CMAKE_ENVIRONMENT_PATH]
24             [NO_SYSTEM_ENVIRONMENT_PATH]
25             [NO_CMAKE_SYSTEM_PATH]
26             [CMAKE_FIND_ROOT_PATH_BOTH |
27              ONLY_CMAKE_FIND_ROOT_PATH |
28              NO_CMAKE_FIND_ROOT_PATH]
29            )
30
31This command is used to find a |SEARCH_XXX_DESC|.
32A cache entry, or a normal variable if ``NO_CACHE`` is specified,
33named by ``<VAR>`` is created to store the result of this command.
34If the |SEARCH_XXX| is found the result is stored in the variable
35and the search will not be repeated unless the variable is cleared.
36If nothing is found, the result will be ``<VAR>-NOTFOUND``.
37
38Options include:
39
40``NAMES``
41  Specify one or more possible names for the |SEARCH_XXX|.
42
43  When using this to specify names with and without a version
44  suffix, we recommend specifying the unversioned name first
45  so that locally-built packages can be found before those
46  provided by distributions.
47
48``HINTS``, ``PATHS``
49  Specify directories to search in addition to the default locations.
50  The ``ENV var`` sub-option reads paths from a system environment
51  variable.
52
53``PATH_SUFFIXES``
54  Specify additional subdirectories to check below each directory
55  location otherwise considered.
56
57``DOC``
58  Specify the documentation string for the ``<VAR>`` cache entry.
59
60``NO_CACHE``
61  .. versionadded:: 3.21
62
63  The result of the search will be stored in a normal variable rather than
64  a cache entry.
65
66  .. note::
67
68    If the variable is already set before the call (as a normal or cache
69    variable) then the search will not occur.
70
71  .. warning::
72
73    This option should be used with caution because it can greatly increase
74    the cost of repeated configure steps.
75
76``REQUIRED``
77  .. versionadded:: 3.18
78
79  Stop processing with an error message if nothing is found, otherwise
80  the search will be attempted again the next time |FIND_XXX| is invoked
81  with the same variable.
82
83If ``NO_DEFAULT_PATH`` is specified, then no additional paths are
84added to the search.
85If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
86
87.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| replace::
88   |prefix_XXX_SUBDIR| for each ``<prefix>`` in the
89   :variable:`<PackageName>_ROOT` CMake variable and the
90   :envvar:`<PackageName>_ROOT` environment variable if
91   called from within a find module loaded by
92   :command:`find_package(<PackageName>)`
93
94.. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
95   |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH`
96
97.. |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR| replace::
98   |prefix_XXX_SUBDIR| for each ``<prefix>/[s]bin`` in ``PATH``, and
99   |entry_XXX_SUBDIR| for other entries in ``PATH``
100
101.. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace::
102   |prefix_XXX_SUBDIR| for each ``<prefix>`` in
103   :variable:`CMAKE_SYSTEM_PREFIX_PATH`
104
1051. .. versionadded:: 3.12
106    If called from within a find module or any other script loaded by a call to
107    :command:`find_package(<PackageName>)`, search prefixes unique to the
108    current package being found.  Specifically, look in the
109    :variable:`<PackageName>_ROOT` CMake variable and the
110    :envvar:`<PackageName>_ROOT` environment variable.
111    The package root variables are maintained as a stack, so if called from
112    nested find modules or config packages, root paths from the parent's find
113    module or config package will be searched after paths from the current
114    module or package.  In other words, the search order would be
115    ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
116    ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc.
117    This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting
118    the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``.
119    See policy :policy:`CMP0074`.
120
121   * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX|
122
1232. Search paths specified in cmake-specific cache variables.
124   These are intended to be used on the command line with a ``-DVAR=value``.
125   The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
126   This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the
127   :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``.
128
129   * |CMAKE_PREFIX_PATH_XXX|
130   * |CMAKE_XXX_PATH|
131   * |CMAKE_XXX_MAC_PATH|
132
1333. Search paths specified in cmake-specific environment variables.
134   These are intended to be set in the user's shell configuration,
135   and therefore use the host's native path separator
136   (``;`` on Windows and ``:`` on UNIX).
137   This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or
138   by setting the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``.
139
140   * |CMAKE_PREFIX_PATH_XXX|
141   * |CMAKE_XXX_PATH|
142   * |CMAKE_XXX_MAC_PATH|
143
1444. Search the paths specified by the ``HINTS`` option.
145   These should be paths computed by system introspection, such as a
146   hint provided by the location of another item already found.
147   Hard-coded guesses should be specified with the ``PATHS`` option.
148
1495. Search the standard system environment variables.
150   This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by
151   setting the :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``.
152
153   * |SYSTEM_ENVIRONMENT_PATH_XXX|
154   * |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX|
155
1566. Search cmake variables defined in the Platform files
157   for the current system.  This can be skipped if ``NO_CMAKE_SYSTEM_PATH``
158   is passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`
159   to ``FALSE``.
160
161   * |CMAKE_SYSTEM_PREFIX_PATH_XXX|
162   * |CMAKE_SYSTEM_XXX_PATH|
163   * |CMAKE_SYSTEM_XXX_MAC_PATH|
164
165   The platform paths that these variables contain are locations that
166   typically include installed software. An example being ``/usr/local`` for
167   UNIX based platforms.
168
1697. Search the paths specified by the PATHS option
170   or in the short-hand version of the command.
171   These are typically hard-coded guesses.
172
173.. versionadded:: 3.16
174  Added ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable
175  various search locations.
176
177.. |FIND_ARGS_XXX| replace:: <VAR> NAMES name
178
179On macOS the :variable:`CMAKE_FIND_FRAMEWORK` and
180:variable:`CMAKE_FIND_APPBUNDLE` variables determine the order of
181preference between Apple-style and unix-style package components.
182
183.. include:: FIND_XXX_ROOT.txt
184.. include:: FIND_XXX_ORDER.txt
185