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