Help/command/FIND_XXX.txt

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